ACP `session/prompt` result omits token usage — ACP hosts can't meter token costs

[maxivillus]

Summary

The ACP server (src/cli/acp.rs) runs jcode as an ACP (Agent Communication Protocol) backend, but the session/prompt response only contains stopReason. Provider token usage that the daemon already emits as ServerEvent::TokenUsage is dropped, so ACP hosts that meter token consumption (cost dashboards, quotas, billing attribution) report 0 tokens for every jcode-driven task.

Context

jcode's daemon protocol emits token accounting per provider request:

ServerEvent::TokenUsage {
    input: u64,
    output: u64,
    cache_read_input: Option<u64>,
    cache_creation_input: Option<u64>,
}

The ACP layer (AcpRuntime::run_prompt in src/cli/acp.rs) consumes events via session.read_event() but ignores TokenUsage, and finishes the RPC with:

{ "stopReason": "end_turn" }

ACP hosts in the hermes family (e.g. Multica) read token counts from the session/prompt result — top-level usage with inputTokens/outputTokens/cachedReadTokens/cacheWriteTokens, or _meta.usage — and persist them per task. With jcode those hosts see an empty usage map, so cost dashboards stay at zero.

Reproduction

1. Run jcode acp.
2. initialize → session/new → session/prompt.
3. Inspect the JSON-RPC result: no usage field regardless of how many tokens the provider streamed.

Proposed change (implemented and verified locally)

Aggregate ServerEvent::TokenUsage over the turn in run_prompt and include it in the result, plus _meta.modelId from the last ServerEvent::ModelChanged for usage attribution:

{
  "stopReason": "end_turn",
  "usage": {
    "inputTokens": 5777,
    "outputTokens": 121,
    "cachedReadTokens": 3072,
    "cacheWriteTokens": 0
  },
  "_meta": { "modelId": "deepseek-v4-flash" }
}

Key points:

• Omit the usage block when all counters are zero (keeps the response unchanged for providers without usage).
• cachedReadTokens maps from cache_read_input, cacheWriteTokens from cache_creation_input.
• Track the last ModelChanged during the turn for _meta.modelId; leave it absent when none arrived.

Environment

• jcode v0.68.0, Linux x86_64, DeepSeek provider (OpenAI-compatible chat completions).
• Verified end-to-end: Multica's hermes-family ACP client now records input_tokens / output_tokens / cache_read_tokens for jcode agents.

[maxivillus]

Follow-up: cached reads are counted inside inputTokens for OpenAI-compatible providers — please add totalTokens

When implementing the usage block, there's a subtlety that cost us a real bug: OpenAI-compatible providers (DeepSeek, OpenRouter, and most others) report prompt_tokens inclusively — the cached prefix is already part of inputTokens. So a usage block of:

{
  "inputTokens": 23457,
  "outputTokens": 94,
  "cachedReadTokens": 13184
}

does not mean "23,457 fresh input + 13,184 cached". It means "10,273 fresh input, 13,184 of which were served from cache". The two buckets overlap.

Without a way to detect that, an ACP host cannot distinguish inclusive buckets from exclusive ones, and metering goes wrong in one of two ways:

• over-counting the cached prefix at the full input rate (charged twice), or
• under-crediting it, if the host assumes the buckets are exclusive.

Suggestion: add totalTokens = inputTokens + outputTokens to the usage block. Multica (ACP host) already normalizes this: its excludeACPCachedInput sees totalTokens == inputTokens + outputTokens and subtracts cachedReadTokens from inputTokens, keeping the persisted buckets mutually exclusive. It is the only self-describing signal available; without it the numbers are ambiguous.

Real-world impact (jcode v0.68.0 + DeepSeek + Multica v0.4.19): a single task card showed Input 6.77M when the true fresh input was only 121K — the other 6.65M was the same cached prefix already counted inside input. The cached portion would also have been billed twice.

Verified end-to-end: with totalTokens in place, new tasks report correct fresh-input numbers automatically.

[blackwellmiranda8]

🧪🛠️ 配置项能不能支持环境变量覆盖

[rodriguezrussell93]

契约测试有没有上 ⭐