profclaw 2.3.0 → 2.4.0

package/dist/chat/meta-tool-handlers.js

@@ -0,0 +1,51 @@
+/**
+ * Meta-tool handlers: load_tools and fetch_result.
+ *
+ * Kept separate from tool-handler.ts so the handler stays small. These are pure
+ * functions over injected dependencies, which also makes them easy to test.
+ */
+import { readStoredRange, getTruncationConfig } from '../agents/output-truncator.js';
+import { TOOL_GROUPS, describeTool, parseFetchResultArgs, parseLoadToolsArgs, toolsInGroup, } from '../agents/tool-selector.js';
+export async function runLoadTools(args, deps) {
+    const parsed = parseLoadToolsArgs(args);
+    if (!parsed) {
+        return { success: false, error: 'load_tools expects { groups: string[] }' };
+    }
+    const loaded = deps.session.loadGroups(parsed.groups);
+    const unknown = parsed.groups.filter((g) => !loaded.includes(g.trim().toLowerCase()));
+    const tools = loaded.flatMap((group) => toolsInGroup(deps.allTools, group).map(describeTool));
+    const response = {
+        success: loaded.length > 0,
+        loaded,
+        tools,
+        note: 'These tools are callable from the next turn. Use invoke to call one now.',
+    };
+    if (unknown.length > 0) {
+        response.unknownGroups = unknown;
+        response.validGroups = TOOL_GROUPS.map((g) => g.name);
+    }
+    if (parsed.invoke) {
+        const target = parsed.invoke.tool;
+        const inLoaded = tools.some((t) => t.name === target);
+        if (!inLoaded) {
+            response.invokeError = `Tool "${target}" is not in the loaded groups`;
+        }
+        else {
+            response.invokeResult = await deps.invoke(target, parsed.invoke.args ?? {});
+        }
+    }
+    return response;
+}
+export async function runFetchResult(args, store) {
+    const parsed = parseFetchResultArgs(args);
+    if (!parsed) {
+        return { success: false, error: 'fetch_result expects { result_id, offset?, length? }' };
+    }
+    const config = getTruncationConfig();
+    const range = await readStoredRange(store, parsed.result_id, parsed.offset ?? 0, parsed.length ?? config.fetchMaxChars, config);
+    if (!range) {
+        return { success: false, error: `No stored result with id "${parsed.result_id}"` };
+    }
+    return range;
+}
+//# sourceMappingURL=meta-tool-handlers.js.map

package/dist/chat/system-prompts.js

@@ -350,7 +350,12 @@ ${context.user.role ? `- Role: ${context.user.role}` : ''}`);
                 // Only include top 15 most relevant skills, not all 55
                 const prioritySkills = entries
                     .filter((e) => e.enabled !== false)
-                    .sort((a, b) => (b.metadata?.priority ?? 0) - (a.metadata?.priority ?? 0))
+                    .sort((a, b) => {
+                    const pa = a.metadata?.priority ?? 0;
+                    const pb = b.metadata?.priority ?? 0;
+                    // Name tie-break keeps the cached prompt prefix byte-stable
+                    return pb - pa || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+                })
                     .slice(0, 15);
                 const skillLines = prioritySkills
                     .map((e) => `- ${e.name}: ${e.description || 'No description'}`)

package/dist/chat/tool-handler.d.ts

@@ -25,6 +25,8 @@ export interface ChatToolHandler {
     }>;
     /** Handle approval decision */
     handleApproval(approvalId: string, decision: 'allow-once' | 'allow-always' | 'deny'): Promise<ToolExecutionResult | null>;
+    /** Delete spilled tool-result temp files. Call when the request/run ends. */
+    dispose(): Promise<void>;
 }
 export declare function createChatToolHandler(options: ChatToolHandlerOptions): Promise<ChatToolHandler>;
 /**

package/dist/chat/tool-handler.js

@@ -9,6 +9,10 @@ import { randomUUID } from 'node:crypto';
 import { getToolExecutor, getToolRegistry, initializeToolExecution, } from './execution/index.js';
 import { logger } from '../utils/logger.js';
 import { SAFE_BROWSER_TOOL_NAMES } from '../browser/index.js';
+import { ResultStore } from '../agents/result-store.js';
+import { truncateAndStore, isTruncationEnabled } from '../agents/output-truncator.js';
+import { LOAD_TOOLS_NAME, FETCH_RESULT_NAME, getToolSelectorSession, } from '../agents/tool-selector.js';
+import { runLoadTools, runFetchResult } from './meta-tool-handlers.js';
 // In-Memory Session Manager for Chat
 class ChatSessionManager {
     sessions = new Map();
@@ -78,6 +82,23 @@ export async function createChatToolHandler(options) {
     const registry = getToolRegistry();
     const executor = getToolExecutor();
     const sessionManager = new ChatSessionManager();
+    const resultStore = new ResultStore(options.conversationId.replace(/[^a-zA-Z0-9_-]/g, '_'));
+    /** Cap large results before they reach the model; the full result stays in the store. */
+    const capForModel = async (toolName, toolCallId, data) => {
+        if (!isTruncationEnabled() || toolName === FETCH_RESULT_NAME || toolName === LOAD_TOOLS_NAME) {
+            return data;
+        }
+        try {
+            return (await truncateAndStore(resultStore, toolCallId, data)).value;
+        }
+        catch (error) {
+            logger.warn(`[ChatToolHandler] Output truncation failed for ${toolName}`, {
+                component: 'ChatToolHandler',
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return data;
+        }
+    };
     // Build security policy
     const securityPolicy = {
         mode: options.securityMode || 'ask',
@@ -93,7 +114,7 @@ export async function createChatToolHandler(options) {
         securityPolicy,
         sessionManager,
     });
-    return {
+    const handler = {
         getTools() {
             const tools = registry.list();
             return tools.map((tool) => ({
@@ -107,7 +128,26 @@ export async function createChatToolHandler(options) {
                 component: 'ChatToolHandler',
                 toolCallId,
             });
+            // Meta-tools are served locally, not through the registry
+            if (toolName === LOAD_TOOLS_NAME) {
+                const allTools = registry.list().map((t) => ({
+                    name: t.name,
+                    description: t.description,
+                    parameters: t.parameters,
+                }));
+                return {
+                    result: await runLoadTools(args, {
+                        session: getToolSelectorSession(options.conversationId),
+                        allTools,
+                        invoke: async (tool, toolArgs) => (await handler.executeTool(tool, toolArgs, randomUUID())).result,
+                    }),
+                };
+            }
+            if (toolName === FETCH_RESULT_NAME) {
+                return { result: await runFetchResult(args, resultStore) };
+            }
             try {
+                getToolSelectorSession(options.conversationId).noteToolUse(toolName);
                 const context = createContext(toolCallId);
                 const result = await executor.execute({
                     id: toolCallId,
@@ -134,7 +174,7 @@ export async function createChatToolHandler(options) {
                 // The AI only sees `result` — `output` is preserved for UI rendering
                 if (result.result.success) {
                     // Extract clean data for the AI model
-                    const aiResult = result.result.data ?? { success: true };
+                    const aiResult = await capForModel(toolName, toolCallId, result.result.data ?? { success: true });
                     return {
                         result: aiResult,
                         output: result.result.output, // Sidecar for UI display
@@ -166,6 +206,9 @@ export async function createChatToolHandler(options) {
                 params: a.params,
             }));
         },
+        async dispose() {
+            await resultStore.cleanup();
+        },
         async handleApproval(approvalId, decision) {
             logger.info(`[ChatToolHandler] Handling approval: ${approvalId} -> ${decision}`, {
                 component: 'ChatToolHandler',
@@ -176,7 +219,7 @@ export async function createChatToolHandler(options) {
                     return null;
                 }
                 if (result.result.success) {
-                    const aiResult = result.result.data ?? { success: true };
+                    const aiResult = await capForModel(approvalId, randomUUID(), result.result.data ?? { success: true });
                     return {
                         result: aiResult,
                         output: result.result.output,
@@ -200,6 +243,7 @@ export async function createChatToolHandler(options) {
             }
         },
     };
+    return handler;
 }
 // Tool Categories for Chat
 /**

package/dist/cli/commands/receipt.d.ts

@@ -0,0 +1,7 @@
+/**
+ * profclaw receipt: verify, view and key generation for run receipts.
+ * Spec: docs/specs/run-receipt-v0.md
+ */
+import { Command } from 'commander';
+export declare function receiptCommand(): Command;
+//# sourceMappingURL=receipt.d.ts.map

package/dist/cli/commands/receipt.js

@@ -0,0 +1,90 @@
+/**
+ * profclaw receipt: verify, view and key generation for run receipts.
+ * Spec: docs/specs/run-receipt-v0.md
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { Command } from 'commander';
+import { verifyReceiptText, parseReceiptText } from '../../agents/receipt/receipt-verify.js';
+import { renderHtml, renderTerminalSummary } from '../../agents/receipt/receipt-view.js';
+import { generateKeyPairFiles } from '../../agents/receipt/receipt-cli.js';
+import { error, info, success } from '../utils/output.js';
+function readOrExit(file) {
+    try {
+        return readFileSync(file, 'utf-8');
+    }
+    catch (err) {
+        error(`Cannot read ${file}: ${err instanceof Error ? err.message : 'unknown error'}`);
+        process.exitCode = 1;
+        return null;
+    }
+}
+export function receiptCommand() {
+    const cmd = new Command('receipt').description('Verify, view and sign tamper-evident run receipts');
+    cmd
+        .command('verify')
+        .description('Check a receipt: exit 0 if intact, 1 if tampered, truncated or invalid')
+        .argument('<file>', 'Path to receipt.jsonl')
+        .option('--pubkey <file>', 'Trusted Ed25519 public key (PEM); the receipt must be signed by it')
+        .option('--require-signature', 'Fail if the receipt is not signed')
+        .action((file, opts) => {
+        const text = readOrExit(file);
+        if (text === null)
+            return;
+        let expectedPublicKey;
+        if (opts.pubkey) {
+            const key = readOrExit(opts.pubkey);
+            if (key === null)
+                return;
+            expectedPublicKey = key;
+        }
+        const result = verifyReceiptText(text, { expectedPublicKey, requireSignature: opts.requireSignature });
+        if (result.ok) {
+            success(result.message);
+            info('This shows the receipt was not altered after it was written. It does not prove the run happened.');
+            process.exitCode = 0;
+        }
+        else {
+            error(`TAMPERED or invalid at seq ${result.firstBadSeq ?? 0} (${result.reason ?? 'unknown'}): ${result.message}`);
+            process.exitCode = 1;
+        }
+    });
+    cmd
+        .command('view')
+        .description('Print a summary, or write a self-contained HTML viewer with --html')
+        .argument('<file>', 'Path to receipt.jsonl')
+        .option('--html <out>', 'Write a single-file HTML viewer to this path')
+        .action((file, opts) => {
+        const text = readOrExit(file);
+        if (text === null)
+            return;
+        const verify = verifyReceiptText(text);
+        const events = parseReceiptText(text);
+        if (opts.html) {
+            writeFileSync(opts.html, renderHtml(events, verify), 'utf-8');
+            info(`Wrote ${opts.html}`);
+        }
+        else {
+            process.stdout.write(renderTerminalSummary(events, verify));
+        }
+        if (!verify.ok)
+            process.exitCode = 1;
+    });
+    cmd
+        .command('keygen')
+        .description('Write an Ed25519 keypair for signing receipts (private key mode 0600)')
+        .argument('<dir>', 'Directory to write receipt-key.pem and receipt-key.pub.pem into')
+        .action((dir) => {
+        try {
+            const files = generateKeyPairFiles(dir);
+            success(`Private key: ${files.privateKeyPath} (keep it off the machine that runs agents if you can)`);
+            info(`Public key:  ${files.publicKeyPath}`);
+            info('Sign with --sign-key <private key> or env PROFCLAW_RECEIPT_KEY; check with: profclaw receipt verify <file> --pubkey <public key>');
+        }
+        catch (err) {
+            error(err instanceof Error ? err.message : 'Key generation failed');
+            process.exitCode = 1;
+        }
+    });
+    return cmd;
+}
+//# sourceMappingURL=receipt.js.map

package/dist/cli/commands/run.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Verified Run CLI Command
+ *
+ * Usage:
+ *   profclaw run "<goal>" --verify "pnpm test"                 (built-in agent)
+ *   profclaw run "<goal>" --verify "pnpm test" --agent-cmd "my-agent-cli"
+ *
+ * Done means verified: the run only succeeds when the verify command exits 0.
+ * Work happens in an isolated git worktree on a local branch. Nothing is
+ * pushed and no PR is opened.
+ *
+ * By default the built-in model-backed agent runs inside the worktree, starting
+ * on the smart router's cheap model and escalating a tier after repeated
+ * verifier failures. --agent-cmd overrides it with an external agent; the goal
+ * and feedback are written to that agent's stdin, never interpolated into a
+ * shell string.
+ */
+import { Command } from 'commander';
+import type { AgentAttemptInput, AgentAttemptResult, AgentRunner } from '../../agents/verified-run.js';
+/** Runs an external agent command, feeding the prompt on stdin. */
+export declare class CommandAgent implements AgentRunner {
+    private readonly command;
+    constructor(command: string);
+    runAttempt(input: AgentAttemptInput): Promise<AgentAttemptResult>;
+}
+export declare function buildPrompt(input: AgentAttemptInput): string;
+export declare function runCommand(): Command;
+//# sourceMappingURL=run.d.ts.map

package/dist/cli/commands/run.js

@@ -0,0 +1,204 @@
+/**
+ * Verified Run CLI Command
+ *
+ * Usage:
+ *   profclaw run "<goal>" --verify "pnpm test"                 (built-in agent)
+ *   profclaw run "<goal>" --verify "pnpm test" --agent-cmd "my-agent-cli"
+ *
+ * Done means verified: the run only succeeds when the verify command exits 0.
+ * Work happens in an isolated git worktree on a local branch. Nothing is
+ * pushed and no PR is opened.
+ *
+ * By default the built-in model-backed agent runs inside the worktree, starting
+ * on the smart router's cheap model and escalating a tier after repeated
+ * verifier failures. --agent-cmd overrides it with an external agent; the goal
+ * and feedback are written to that agent's stdin, never interpolated into a
+ * shell string.
+ */
+import { spawn } from 'node:child_process';
+import { Command } from 'commander';
+import { describeSandbox, resolveSandboxMode } from '../../agents/command-sandbox.js';
+import { CommandVerifier } from '../../agents/verifier.js';
+import { runVerifiedGoal, resolveLimits } from '../../agents/verified-run.js';
+import { createDefaultExecutorRunner } from '../../agents/executor-runner.js';
+import { setupRunReceipt, toolVersion } from '../../agents/receipt/receipt-cli.js';
+import { error, info, success, warn, formatCost, formatTokens } from '../utils/output.js';
+/** Runs an external agent command, feeding the prompt on stdin. */
+export class CommandAgent {
+    command;
+    constructor(command) {
+        this.command = command;
+    }
+    runAttempt(input) {
+        const prompt = buildPrompt(input);
+        return new Promise((resolve, reject) => {
+            const child = spawn('/bin/sh', ['-c', this.command], {
+                cwd: input.workdir,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            let out = '';
+            child.stdout.on('data', (d) => {
+                out = (out + d.toString('utf-8')).slice(-4000);
+            });
+            child.stderr.on('data', (d) => {
+                out = (out + d.toString('utf-8')).slice(-4000);
+            });
+            input.signal?.addEventListener('abort', () => child.kill('SIGTERM'), { once: true });
+            child.on('error', reject);
+            child.on('close', (code) => {
+                if (code === 0)
+                    resolve({ summary: out.trim().slice(-500), tokensUsed: 0, costUsd: 0 });
+                else
+                    reject(new Error(`agent command exited with code ${code ?? 'null'}: ${out.trim().slice(-500)}`));
+            });
+            child.stdin.on('error', () => undefined);
+            child.stdin.end(prompt);
+        });
+    }
+}
+export function buildPrompt(input) {
+    const parts = [
+        `Goal: ${input.goal}`,
+        `Work only inside: ${input.workdir}`,
+        `Your work is judged by running: ${input.verifyCommand}`,
+        'Do not push to any remote or open pull requests.',
+    ];
+    if (input.feedback)
+        parts.push('', `Attempt ${input.attempt}. Previous attempt feedback:`, input.feedback);
+    return parts.join('\n') + '\n';
+}
+function parseNumber(raw, name) {
+    if (raw === undefined)
+        return undefined;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 0)
+        throw new Error(`${name} must be a non-negative number`);
+    return n;
+}
+function formatAttemptUsage(record) {
+    const parts = [`${formatTokens(record.tokensUsed)} tokens`];
+    if (record.cacheHitRate !== undefined)
+        parts.push(`cache hit ${(record.cacheHitRate * 100).toFixed(0)}%`);
+    parts.push(formatCost(record.costUsd));
+    if (record.model)
+        parts.push(record.model);
+    return parts.join(', ');
+}
+function printRunnerEvent(event) {
+    const { attempt, choice, escalated } = event;
+    const prefix = escalated ? 'Escalating to' : 'Using';
+    info(`Attempt ${attempt}: ${prefix} ${choice.provider}/${choice.model} (${choice.tier})`);
+}
+function printEvent(event) {
+    if (event.type === 'start')
+        info(`Run ${event.runId} on branch ${event.branch}`);
+    else if (event.type === 'attempt_start')
+        info(`Attempt ${event.attempt}...`);
+    else if (event.type === 'attempt_end') {
+        const { record } = event;
+        const line = `Attempt ${record.attempt}: ${record.outcome}${record.rolledBack ? ' (rolled back)' : ''} [${formatAttemptUsage(record)}]`;
+        if (record.outcome === 'verified')
+            success(line);
+        else
+            warn(line);
+    }
+}
+export function runCommand() {
+    return new Command('run')
+        .description('Run an agent toward a goal and only finish when a verify command passes')
+        .argument('<goal>', 'What the agent should accomplish')
+        .requiredOption('--verify <command>', 'Command that must exit 0 (tests, typecheck, lint, build)')
+        .option('--agent-cmd <command>', 'External agent command (overrides the built-in agent); receives the prompt on stdin')
+        .option('--model <ids>', 'Model, or comma separated ladder cheapest first (env PROFCLAW_RUN_MODEL); default: smart router')
+        .option('--escalate-after <n>', 'Verifier failures in a row before moving up a model tier, 0 disables (env PROFCLAW_RUN_ESCALATE_AFTER)')
+        .option('--max-attempts <n>', 'Maximum attempts (env PROFCLAW_RUN_MAX_ATTEMPTS)')
+        .option('--max-tokens <n>', 'Token budget, 0 disables (env PROFCLAW_RUN_MAX_TOKENS)')
+        .option('--max-cost <usd>', 'Dollar budget, 0 disables (env PROFCLAW_RUN_MAX_COST_USD)')
+        .option('--breaker <n>', 'Non-improving attempts before the circuit breaker trips (env PROFCLAW_RUN_BREAKER_THRESHOLD)')
+        .option('--verify-timeout <ms>', 'Verifier timeout (env PROFCLAW_RUN_VERIFY_TIMEOUT_MS)')
+        .option('--branch <name>', 'Branch name for the run (default profclaw/run-<id>)')
+        .option('--sandbox-verify', 'Also run the verify command under the OS sandbox (env PROFCLAW_RUN_SANDBOX_VERIFY=1); default off')
+        .option('--cleanup', 'Remove the worktree afterwards (the branch is kept)')
+        .option('--no-receipt', 'Do not write a tamper-evident receipt.jsonl for the run')
+        .option('--sign-key <path>', 'Ed25519 private key (PEM) to sign the receipt (env PROFCLAW_RECEIPT_KEY)')
+        .option('--json', 'Output the result as JSON')
+        .action(async (goal, options) => {
+        try {
+            const flags = {
+                maxAttempts: parseNumber(options.maxAttempts, '--max-attempts'),
+                maxTokens: parseNumber(options.maxTokens, '--max-tokens'),
+                maxCostUsd: parseNumber(options.maxCost, '--max-cost'),
+                breakerThreshold: parseNumber(options.breaker, '--breaker'),
+                verifyTimeoutMs: parseNumber(options.verifyTimeout, '--verify-timeout'),
+            };
+            for (const key of Object.keys(flags)) {
+                if (flags[key] === undefined)
+                    delete flags[key];
+            }
+            const verifyCommand = options.verify;
+            const sandboxMode = resolveSandboxMode();
+            const sandboxVerify = options.sandboxVerify === true || process.env.PROFCLAW_RUN_SANDBOX_VERIFY === '1';
+            if (!options.json)
+                info(`${describeSandbox(sandboxMode)}${sandboxVerify ? '; verify command sandboxed' : ''}`);
+            const limits = resolveLimits(flags);
+            const rc = setupRunReceipt({ enabled: options.receipt !== false, projectRoot: process.cwd(), signKeyPath: options.signKey });
+            const agent = options.agentCmd
+                ? new CommandAgent(options.agentCmd)
+                : await createDefaultExecutorRunner({
+                    goal,
+                    model: options.model,
+                    config: { escalateAfter: parseNumber(options.escalateAfter, '--escalate-after') },
+                    maxTokens: limits.maxTokens,
+                    maxCostUsd: limits.maxCostUsd,
+                    onEvent: options.json ? undefined : printRunnerEvent,
+                    onToolCall: rc.onToolCall,
+                });
+            const result = await runVerifiedGoal({
+                goal,
+                verifyCommand,
+                agent,
+                projectRoot: process.cwd(),
+                runId: rc.runId,
+                receipt: rc.receipt,
+                toolInfo: { name: 'profclaw', version: toolVersion() },
+                limits: flags,
+                branchName: options.branch,
+                removeWorktree: options.cleanup,
+                onEvent: options.json ? undefined : printEvent,
+                createVerifier: (cwd) => new CommandVerifier(verifyCommand, {
+                    cwd,
+                    timeoutMs: flags.verifyTimeoutMs ?? Number(process.env.PROFCLAW_RUN_VERIFY_TIMEOUT_MS ?? 600_000),
+                    maxOutputChars: Number(process.env.PROFCLAW_RUN_MAX_OUTPUT_CHARS ?? 4_000),
+                    sandbox: sandboxVerify ? { mode: sandboxMode } : undefined,
+                }),
+            });
+            if (options.json) {
+                console.log(JSON.stringify({ ...result, diff: undefined }, null, 2));
+            }
+            else if (result.verified) {
+                success(`Verified after ${result.attempts.length} attempt(s), cost ${formatCost(result.totalCostUsd)}`);
+                info(`Branch ${result.branch} is ready for review (not pushed).`);
+                if (result.reportPath)
+                    info(`Evidence: ${result.reportPath}`);
+                if (rc.receipt)
+                    info(`Receipt: ${rc.receipt.path}`);
+            }
+            else if (result.stopReason === 'already_passing') {
+                warn('The verify command already passes before any change, so no attempt was made.');
+                if (result.reportPath)
+                    info(`Report: ${result.reportPath}`);
+            }
+            else {
+                error(`Not verified (${result.stopReason}) after ${result.attempts.length} attempt(s)`);
+                if (result.reportPath)
+                    info(`Report: ${result.reportPath}`);
+            }
+            process.exitCode = result.verified || result.stopReason === 'already_passing' ? 0 : 1;
+        }
+        catch (err) {
+            error(err instanceof Error ? err.message : 'Verified run failed');
+            process.exitCode = 1;
+        }
+    });
+}
+//# sourceMappingURL=run.js.map

package/dist/cli/index.js

@@ -37,6 +37,8 @@ import { importCommands } from './commands/import.js';
 import { historyCommands } from './commands/history.js';
 import { planCommands } from './commands/plan.js';
 import { initCommand } from './commands/init.js';
+import { runCommand } from './commands/run.js';
+import { receiptCommand } from './commands/receipt.js';
 const VERSION = '2.0.0';
 // ASCII Banner
 function showBanner() {
@@ -92,6 +94,8 @@ program.addCommand(importCommands());
 program.addCommand(historyCommands());
 program.addCommand(planCommands());
 program.addCommand(initCommand());
+program.addCommand(runCommand());
+program.addCommand(receiptCommand());
 // Default action (no command) - show banner and help
 program.action(() => {
     showBanner();

package/dist/costs/token-tracker.d.ts

@@ -2,6 +2,12 @@ export interface UsageSummary {
     totalTokens: number;
     inputTokens: number;
     outputTokens: number;
+    /** Prompt tokens served from provider cache (subset of inputTokens) */
+    cacheReadTokens: number;
+    /** Prompt tokens written to provider cache (subset of inputTokens) */
+    cacheWriteTokens: number;
+    /** cacheReadTokens / inputTokens, 0 when there is no input */
+    cacheHitRate: number;
     totalCost: number;
     taskCount: number;
     byModel: Record<string, {
@@ -22,7 +28,10 @@ export declare function initTokenTracker(): void;
 /**
  * Track usage from a chat/agentic session (not queue tasks)
  */
-export declare function trackChatUsage(model: string, totalTokens: number, inputTokens?: number, outputTokens?: number): void;
+export declare function trackChatUsage(model: string, totalTokens: number, inputTokens?: number, outputTokens?: number, cache?: {
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+}): void;
 /**
  * Get current usage summary
  */

package/dist/costs/token-tracker.js

@@ -1,5 +1,6 @@
 import { onTaskEvent } from '../queue/index.js';
-import { calculateCost } from './pricing.js';
+import { calculateCost, getModelPricing } from './pricing.js';
+import { cacheHitRate, calculateCachedInputCost, getCacheConfigForModel } from '../providers/prompt-cache.js';
 import { logger } from '../utils/logger.js';
 import { recordCost } from './persistence.js';
 // In-memory usage store
@@ -7,6 +8,9 @@ let globalUsage = {
     totalTokens: 0,
     inputTokens: 0,
     outputTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+    cacheHitRate: 0,
     totalCost: 0,
     taskCount: 0,
     byModel: {},
@@ -81,16 +85,32 @@ function trackTaskUsage(task, result) {
         cost,
     });
 }
+/**
+ * Cost of a chat call. Uncached input bills at the model input rate; cache reads
+ * and writes bill at the configurable multipliers of that same rate. Output cost
+ * comes from the existing pricing table (calculateCost with zero input).
+ */
+function calculateChatCost(model, input, output, cacheRead, cacheWrite) {
+    if (cacheRead === 0 && cacheWrite === 0)
+        return calculateCost(model, input, output);
+    const inputCost = calculateCachedInputCost(input, cacheRead, cacheWrite, getModelPricing(model).inputRate, getCacheConfigForModel(model));
+    const outputCost = calculateCost(model, 0, output);
+    return Math.round((inputCost + outputCost) * 1_000_000) / 1_000_000;
+}
 /**
  * Track usage from a chat/agentic session (not queue tasks)
  */
-export function trackChatUsage(model, totalTokens, inputTokens, outputTokens) {
+export function trackChatUsage(model, totalTokens, inputTokens, outputTokens, cache) {
     const input = inputTokens ?? Math.floor(totalTokens * 0.7);
     const output = outputTokens ?? totalTokens - input;
-    const cost = calculateCost(model, input, output);
+    const cacheRead = cache?.cacheReadTokens ?? 0;
+    const cacheWrite = cache?.cacheWriteTokens ?? 0;
+    const cost = calculateChatCost(model, input, output, cacheRead, cacheWrite);
     globalUsage.totalTokens += totalTokens;
     globalUsage.inputTokens += input;
     globalUsage.outputTokens += output;
+    globalUsage.cacheReadTokens += cacheRead;
+    globalUsage.cacheWriteTokens += cacheWrite;
     globalUsage.totalCost += cost;
     globalUsage.taskCount += 1;
     const agentId = 'chat';
@@ -116,13 +136,22 @@ export function trackChatUsage(model, totalTokens, inputTokens, outputTokens) {
         source: 'chat',
         agentId: 'chat',
     });
-    logger.debug('Chat usage tracked', { model, tokens: totalTokens, cost });
+    logger.debug('Chat usage tracked', {
+        model,
+        tokens: totalTokens,
+        cost,
+        cacheReadTokens: cacheRead,
+        cacheWriteTokens: cacheWrite,
+    });
 }
 /**
  * Get current usage summary
  */
 export function getUsageSummary() {
-    return { ...globalUsage };
+    return {
+        ...globalUsage,
+        cacheHitRate: cacheHitRate(globalUsage.cacheReadTokens, globalUsage.inputTokens),
+    };
 }
 /**
  * Reset usage (for testing or billing cycles)
@@ -132,6 +161,9 @@ export function resetUsage() {
         totalTokens: 0,
         inputTokens: 0,
         outputTokens: 0,
+        cacheReadTokens: 0,
+        cacheWriteTokens: 0,
+        cacheHitRate: 0,
         totalCost: 0,
         taskCount: 0,
         byModel: {},