feat: cost observability — local prompt metrics, section breakdown, and cost reports

[Shifat7]

What changed

Adds local, estimate-only cost visibility before any optimisation behaviour changes. No dispatch behaviour is modified.

Prompt metrics (src/protocol.mjs)

• New buildRelayPromptWithMetrics() returns the unchanged relay prompt plus a breakdown:
  • totalChars, estimatedTokens = ceil(chars / 4), estimator, usageSource
  • sections: relayInstructionChars, conversationChars, toolResultChars (inside conversation), toolSchemaChars, payloadChars
  • effective limits (maxInputChars / maxTurnChars / maxConversationTurns / maxForwardedTools), retained turns, forwarded tool count
• New shared retentionLimits() helper removes duplicated clamp logic in normalizeInput/normalizeTools; buildRelayPrompt() output is byte-for-byte identical to before.

Audit fields (src/bridge.mjs)

request_reserved now carries the full breakdown + limits; completed additionally carries promptChars/estimatedPromptTokens. Every dispatched request logs estimated prompt usage.

CLI

• hacb cost-report [--last N] — per-request table (chars, ~tokens, conv/schema/result chars, tools, daily budget) plus totals/averages
• hacb explain-prompt [--verbose] — where the last relay prompt's characters went
• hacb audit --cost [count] — receipts with estimated token columns

Opt-in excerpt capture (src/config.mjs)

debugPromptExcerpts (default false). When enabled, bounded (240-char) prompt excerpts are written only to the private state dir (prompt-excerpts.jsonl, mode 0600) via an injectable writer; never to the sanitized audit or gateway logs.

Why it saves credits

This PR does not change spend by itself — it makes credit burn measurable per request so PRs 2–3 (tool shortlisting, result reducer) can show measured before/after evidence instead of guesses.

Security posture preserved

• Reports contain counts/sizes only; no raw prompt content by default.
• Excerpts are opt-in, local-only, mode 0600, excluded from audit/gateway logs.
• Tests assert prompts/tokens/output still never appear in audit or gateway logs.
• Estimates are explicitly labelled as estimates (usage_source remains unavailable; no fabricated usage objects).

Testing

npm test          # 84 pass, 0 fail (3 pre-existing skips)
npm run lint:openapi   # valid

New tests cover:

• breakdown correctness (section sums, estimator, retention-limit clamping)
• opt-in/bounded excerpt capture incl. default-off guarantee
• audit cost-field presence on request_reserved/completed
• record joining, summaries, and malformed-line tolerance in the new report module

Example output (synthetic local data)

$ hacb cost-report --last 20
TIME                  REQUEST            OUTCOME           PROMPT   ~TOKENS     CONV   SCHEMA   RESULT  TOOLS   DAILY
2026-08-22 09:00:00   1111111111         function_call     61,234    15,309   41,000    9,800    9,000     32     5/6
2026-08-22 10:30:00   2222222222         final             19,340     4,835    8,000    3,900    1,200      6     1/6

Requests: 2 (completed=2)
Estimated prompt tokens: total 20,144, avg 10,072 per request
Forwarded tools: avg 19, max 32
Estimates are local approximations only; Hyperagent does not report authoritative token usage.

Note: opened from a fork because this workstation's credentials have read-only upstream access; branch name follows the handover plan.