From eef0e62242a6e085c2edcdabe215a0d97ca33acc Mon Sep 17 00:00:00 2001 From: Alex Clarke Date: Mon, 14 Sep 2026 15:25:35 -0600 Subject: [PATCH] docs: usage-cost tracking (last_cost/total_cost prompt vars, default $ segment, cache prices feed cost accounting) --- Clients.md | 7 +++++-- REPL-Prompt.md | 7 ++++++- 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/Clients.md b/Clients.md index bbacc65..aa902b3 100644 --- a/Clients.md +++ b/Clients.md @@ -62,8 +62,8 @@ The `models` array lists the available models from the model client. Each one ha | `type` | * | `all` | The type of model. Coyote supports only 3 types of models: | | `input_price` | | `all` | The cost in USD per 1M tokens for each input sequence; Coyote will keep track of usage costs if this is defined | | `output_price` | | `all` | The cost in USD per 1M tokens of the model output; Coyote will keep track of usage costs if this is defined | -| `cache_read_price` | | `all` | The cost in USD per 1M tokens for reading prompt-cache tokens; populated automatically from the [model catalog](Model-Catalog) where the sources publish it | -| `cache_write_price` | | `all` | The cost in USD per 1M tokens for writing prompt-cache tokens; populated automatically from the [model catalog](Model-Catalog) where the sources publish it | +| `cache_read_price` | | `all` | The cost in USD per 1M tokens for reading prompt-cache tokens; populated automatically from the [model catalog](Model-Catalog) where the sources publish it, and used in usage-cost tracking | +| `cache_write_price` | | `all` | The cost in USD per 1M tokens for writing prompt-cache tokens; populated automatically from the [model catalog](Model-Catalog) where the sources publish it, and used in usage-cost tracking | | `patch` | | `all` | See the [model-specific patch configuration](Patches#model-specific-patches) documentation | | `max_input_tokens` | | `all` | The maximum number of input tokens for the model | | `max_output_tokens` | | `chat` | The maximum number of output tokens for the model | @@ -101,6 +101,9 @@ clients: > * Cache activity is visible in the REPL: the default right prompt shows a ⚡ segment with the tokens read from cache > on the most recent call (see the [token usage prompt variables](REPL-Prompt#variables)), and `.info session` shows > cumulative cache reads/writes for the session. +> * Coyote also tracks the real USD cost of each call (input/output/cache-read/cache-write tokens × the model's +> catalog prices): the default right prompt shows the session's running `$` total, and `.info session` / session +> exports include `total_cost`. Cost is only reported when every billed component has a known price. No estimates. > * Setting `prompt_cache: false` produces request bodies byte-identical to Coyote versions that predate prompt caching. # Authentication diff --git a/REPL-Prompt.md b/REPL-Prompt.md index 4650e3b..437196c 100644 --- a/REPL-Prompt.md +++ b/REPL-Prompt.md @@ -3,7 +3,7 @@ and `right_prompt` settings in the global Coyote configuration file: ```yaml left_prompt: '{color.red}{model}){color.green}{?session {?agent {agent}>}{session}{?role /}}{!session {?agent {agent}>}}{role}{?rag @{rag}}{color.cyan}{?session )}{!session >}{color.reset} ' -right_prompt: '{color.cyan}{?reasoning_effort [{reasoning_effort}] }{color.purple}{?last_cache_read_tokens ⚡{last_cache_read_tokens} }{?session {?consume_tokens {consume_tokens}({consume_percent}%)}{!consume_tokens {consume_tokens}}}{color.reset}' +right_prompt: '{color.cyan}{?reasoning_effort [{reasoning_effort}] }{color.purple}{?last_cache_read_tokens ⚡{last_cache_read_tokens} }{?total_cost ${total_cost} }{?session {?consume_tokens {consume_tokens}({consume_percent}%)}{!consume_tokens {consume_tokens}}}{color.reset}' ``` > [!NOTE] @@ -100,6 +100,11 @@ total_input_tokens: 5400 # Cumulative input tokens for the active sessi total_output_tokens: 1800 # Cumulative output tokens for the active session total_cache_read_tokens: 4100 # Cumulative cache-read tokens for the active session total_cache_creation_tokens: 1200 # Cumulative cache-write tokens for the active session +last_cost: 0.0142 # USD cost of the most recent API call (real usage × the model's catalog prices); + # only set when every billed component has a known price, and hidden until it + # renders as a nonzero 4-decimal amount +total_cost: 0.3982 # Cumulative USD cost for the active session, accumulated per API call with the + # prices of the model that served each call (accurate across mid-session model switches) # RAG Variables rag: temp # The name of the active RAG