@loucompanion/forge-bridge 0.1.1-dev.32d4dd5874ee → 0.1.1-dev.4f31cdd58cac

package/dist/session/provider-cli/provider-cli.service.js

@@ -7,9 +7,11 @@ import { promisify } from "node:util";
 import { GitClient } from "../../shared/git/git.js";
 import { resolveCursorAgentDirectLaunch } from "../../shared/cursor-agent/cursor-agent.launch.js";
 import { buildSpecBody, selectLaneCommand } from "../../worktree/artifact-injector.js";
-import { codexMcpConfigArgs, completionArtifactJsonPath, completionArtifactReportPath, completionPhaseFromDispatch, completionPromptForPhase, prepareCompletionToolRuntime, readCompletionArtifact } from "../phase-completion.js";
+import { codexMcpConfigArgs, completionPhaseFromDispatch, completionPromptForDevelopCycle, completionPromptForPhase, completionRedactionEnv, expectedCompletionToolName, prepareCompletionToolRuntime, readCompletionArtifact, usesDevelopCycleCompletion, writeCompletionArtifact } from "../phase-completion.js";
+import { addUsage, buildProviderUsageEvent, emptyUsage, hasUsage, readUsageNumber } from "./provider-usage.js";
 const fakeWorkerModel = "server-local-fake-worker";
 const execFileAsync = promisify(execFile);
+const developCyclePhaseOrder = ["implementation", "self_review", "validation"];
 export class RoutingProviderCliService {
     realProvider;
     deterministicProvider;
@@ -43,6 +45,7 @@ export class ProcessBackedProviderCliService {
     async runImplementation(context) {
         const { dispatch, worktree } = context;
         const phase = completionPhaseFromDispatch(dispatch);
+        const developCycle = usesDevelopCycleCompletion(dispatch);
         const metadataRoot = path.join(worktree.worktreePath, ".forge", "work-items", dispatch.workItem.id);
         await fs.mkdir(metadataRoot, { recursive: true });
         const laneCommand = selectLaneCommand(dispatch.artifacts, dispatch.execution.lane, dispatch.cycleRun.phase);
@@ -56,7 +59,7 @@ export class ProcessBackedProviderCliService {
         const completionTools = await prepareCompletionToolRuntime({ dispatch, worktree, phase });
         const command = buildProviderCliCommand(dispatch, {
             worktreePath: worktree.worktreePath,
-            prompt: buildImplementationPrompt(dispatch, phase),
+            prompt: developCycle ? buildDevelopCyclePrompt(dispatch, phase) : buildImplementationPrompt(dispatch, phase),
             completionTools
         });
         await context.emit({
@@ -68,16 +71,21 @@ export class ProcessBackedProviderCliService {
         await context.emit({
             role: "runner",
             kind: "checkpoint",
-            content: `Forge completion tools configured for ${phase}; provider must call the MCP completion tool before exit.`,
+            content: developCycle
+                ? "Forge completion tools configured for implementation -> self_review -> validation; provider must call each MCP completion tool before exit."
+                : `Forge completion tools configured for ${phase}; provider must call the MCP completion tool before exit.`,
             eventType: "completion_tools_configured"
         });
         const outputState = createProviderOutputState(dispatch.execution.provider);
+        const liveCompletionEvents = new LiveCompletionArtifactEmitter(worktree.worktreePath, dispatch.workItem.id, phase, developCycle, context.emit);
         let result;
         try {
+            liveCompletionEvents.start();
             result = await this.processRunner.run({
                 command: command.command,
                 args: command.args,
-                cwd: worktree.worktreePath
+                cwd: worktree.worktreePath,
+                env: providerRedactionEnv(dispatch)
             }, {
                 onStdoutLine: async (line) => {
                     const event = outputState.consume(line);
@@ -88,6 +96,7 @@ export class ProcessBackedProviderCliService {
             }, context.signal);
         }
         finally {
+            await liveCompletionEvents.stop();
             await cleanupCompletionTools(completionTools, context.emit);
         }
         if (result.exitCode !== 0) {
@@ -100,17 +109,23 @@ export class ProcessBackedProviderCliService {
             content: `Provider CLI completed: ${command.command} exit ${result.exitCode}${outputState.sessionLabel ? ` ${outputState.sessionLabel}` : ""}.`,
             eventType: "provider_cli_completed"
         });
+        await emitProviderUsageEvent(context.emit, dispatch, outputState);
         const committed = await commitWorktreeChanges(this.git, worktree.worktreePath, dispatch.workItem.id);
-        const completionArtifact = await readCompletionArtifact(worktree.worktreePath, dispatch.workItem.id, phase);
-        if (!completionArtifact) {
-            throw new Error(`Provider CLI completed but did not call the Forge ${phase} completion tool.`);
+        const completionArtifacts = await readCompletionArtifactsForRun(worktree.worktreePath, dispatch.workItem.id, phase, developCycle);
+        for (const artifact of completionArtifacts) {
+            if (!liveCompletionEvents.hasEmitted(completionPhaseFromArtifact(artifact))) {
+                await emitCompletionArtifactRecorded(context.emit, worktree.worktreePath, artifact);
+                await emitPhaseCompletionEvent(context.emit, artifact);
+                await emitPhaseGateEvents(context.emit, artifact);
+            }
         }
+        const completionArtifact = completionArtifacts[0];
         if (outputState.finalMessage) {
             await context.emit({
                 role: "assistant",
                 kind: "message",
                 content: outputState.finalMessage,
-                eventType: "implementation_complete"
+                eventType: "provider_final_message"
             });
         }
         else {
@@ -118,11 +133,11 @@ export class ProcessBackedProviderCliService {
                 role: "assistant",
                 kind: "message",
                 content: `${dispatch.execution.provider} CLI completed for ${worktree.branchName}.`,
-                eventType: "implementation_complete"
+                eventType: "provider_final_message"
             });
         }
         return {
-            summary: `${dispatch.execution.provider} CLI completed ${worktree.branchName} (${phase}, ${committed.commitSha.slice(0, 12)}).`,
+            summary: `${dispatch.execution.provider} CLI completed ${worktree.branchName} (${developCycle ? "develop cycle" : phase}, ${committed.commitSha.slice(0, 12)}).`,
             spec: {
                 repoPath: worktree.worktreePath,
                 path: specPath,
@@ -130,7 +145,8 @@ export class ProcessBackedProviderCliService {
                 producedBy: "forge-lane-command",
                 status: "approved"
             },
-            artifact: completionArtifact
+            artifact: completionArtifact,
+            artifacts: completionArtifacts
         };
     }
     async runQa(dispatch, emit, signal) {
@@ -166,6 +182,7 @@ export class ProcessBackedProviderCliService {
             content: `Provider CLI QA completed: ${command.command} exit ${result.exitCode}${outputState.sessionLabel ? ` ${outputState.sessionLabel}` : ""}.`,
             eventType: "provider_cli_completed"
         });
+        await emitProviderUsageEvent(emit, dispatch, outputState);
         return {
             summary: `${dispatch.execution.provider} CLI QA passed.`
         };
@@ -201,6 +218,7 @@ export class ProcessBackedProviderCliService {
         }
         const committed = await commitWorktreeChanges(this.git, worktree.worktreePath, dispatch.workItem.id);
         await this.git.run(worktree.worktreePath, ["push", "origin", `HEAD:${worktree.branchName}`]);
+        await emitProviderUsageEvent(context.emit, dispatch, outputState);
         await context.emit({
             role: "assistant",
             kind: "message",
@@ -220,6 +238,7 @@ export class DeterministicProviderCliService {
     async runImplementation(context) {
         const { dispatch, worktree } = context;
         const phase = completionPhaseFromDispatch(dispatch);
+        const developCycle = usesDevelopCycleCompletion(dispatch);
         const providerCommand = buildProviderCliCommand(dispatch);
         const providerCommandText = formatProviderCliCommand(providerCommand);
         const metadataRoot = path.join(worktree.worktreePath, ".forge", "work-items", dispatch.workItem.id);
@@ -250,41 +269,34 @@ export class DeterministicProviderCliService {
             content: `Created bridge changeset at ${changesetPath}`,
             eventType: "changeset"
         });
-        const verdict = {
-            schema_version: 1,
-            phase: "implementation",
-            status: "pass",
-            summary: "forge-bridge produced a deterministic implementation changeset.",
-            plan: [{ step: "Create deterministic changeset", status: "done" }],
-            changed_files: [{ path: "FORGE_PHASE5_CHANGESET.md", summary: "Recorded deterministic bridge evidence." }],
-            tests_added_or_updated: [{ name: "forge_bridge_run_once", evidence: "The bridge committed FORGE_PHASE5_CHANGESET.md." }],
-            docs_added_or_updated: [{ path: "FORGE_PHASE5_CHANGESET.md", summary: "Deterministic evidence document created for the run." }],
-            acceptance_criteria: [
-                {
-                    criterion: dispatch.workItem.acceptanceCriteria || "Deterministic bridge changeset exists",
-                    evidence: `FORGE_PHASE5_CHANGESET.md was committed with content hash ${sha256(changesetBody)}.`,
-                    status: "satisfied"
-                }
-            ],
-            known_gaps: [],
-            next_phase_context: "Review FORGE_PHASE5_CHANGESET.md and the bridge commit before validation.",
-            produced_by: "forge-bridge",
-            content_hash: sha256(changesetBody)
-        };
-        const verdictJson = JSON.stringify(verdict);
-        const report = `# Implementation report\n\nforge-bridge prepared \`${worktree.branchName}\` and created \`${changesetPath}\`.\n`;
-        const artifactPath = completionArtifactJsonPath(worktree.worktreePath, dispatch.workItem.id, "implementation");
-        const reportPath = completionArtifactReportPath(worktree.worktreePath, dispatch.workItem.id, "implementation");
-        await fs.writeFile(artifactPath, verdictJson + "\n", "utf8");
-        await fs.writeFile(reportPath, report, "utf8");
-        await context.emit({
-            role: "assistant",
-            kind: "message",
-            content: "Implementation complete. forge-bridge produced deterministic phase artifacts.",
-            eventType: "implementation_complete"
-        });
+        const phases = developCycle
+            ? ["implementation", "self_review", "validation"]
+            : [phase];
+        const completionArtifacts = [];
+        for (const completionPhase of phases) {
+            await writeCompletionArtifact({
+                worktreePath: worktree.worktreePath,
+                workItemId: dispatch.workItem.id,
+                phase: completionPhase,
+                producedBy: "forge-bridge",
+                redactionSecrets: exactRedactionSecrets(dispatch)
+            }, expectedCompletionToolName(completionPhase), deterministicCompletionPayload(completionPhase, dispatch, changesetBody));
+            const completionArtifact = await readCompletionArtifact(worktree.worktreePath, dispatch.workItem.id, completionPhase);
+            if (!completionArtifact) {
+                throw new Error(`Deterministic provider did not produce the Forge ${completionPhase} completion artifact.`);
+            }
+            completionArtifacts.push(completionArtifact);
+            await emitCompletionArtifactRecorded(context.emit, worktree.worktreePath, completionArtifact);
+            await context.emit({
+                role: "assistant",
+                kind: "message",
+                content: `${completionPhase.replace(/_/g, " ")} complete. forge-bridge produced deterministic phase artifacts.`,
+                eventType: phaseCompleteEventType(completionPhase)
+            });
+        }
+        await context.emit(buildProviderUsageEvent(dispatch, estimatedDeterministicUsage()));
         return {
-            summary: `forge-bridge completed ${worktree.branchName}.`,
+            summary: `forge-bridge completed ${worktree.branchName} (${developCycle ? "develop cycle" : phase}).`,
             spec: {
                 repoPath: worktree.worktreePath,
                 path: specPath,
@@ -292,15 +304,8 @@ export class DeterministicProviderCliService {
                 producedBy: "forge-lane-command",
                 status: "approved"
             },
-            artifact: {
-                repoPath: worktree.worktreePath,
-                path: artifactPath,
-                verdictJson,
-                report,
-                producedBy: "forge-bridge",
-                status: "pass",
-                phase: "implementation"
-            }
+            artifact: completionArtifacts[0],
+            artifacts: completionArtifacts
         };
     }
     async runQa(dispatch, emit) {
@@ -316,6 +321,7 @@ export class DeterministicProviderCliService {
             content: "All checks passed. forge-bridge QA completed.",
             eventType: "qa_complete"
         });
+        await emit(buildProviderUsageEvent(dispatch, estimatedDeterministicUsage()));
         return {
             summary: "forge-bridge QA passed."
         };
@@ -323,6 +329,7 @@ export class DeterministicProviderCliService {
     async runConflictResolve(context) {
         const { dispatch, worktree } = context;
         await this.git.run(worktree.worktreePath, ["commit", "--allow-empty", "-m", `forge bridge conflict resolve for ${dispatch.workItem.id.slice(0, 8)}`]);
+        await context.emit(buildProviderUsageEvent(dispatch, estimatedDeterministicUsage()));
         await context.emit({
             role: "assistant",
             kind: "message",
@@ -334,12 +341,251 @@ export class DeterministicProviderCliService {
         };
     }
 }
+function phaseCompleteEventType(phase) {
+    return phase === "implementation" ? "implementation_complete" : `${phase}_complete`;
+}
+function deterministicCompletionPayload(phase, dispatch, changesetBody) {
+    const changesetHash = sha256(changesetBody);
+    const criterion = dispatch.workItem.acceptanceCriteria || "Deterministic bridge changeset exists";
+    if (phase === "implementation") {
+        return {
+            status: "pass",
+            summary: "forge-bridge produced a deterministic implementation changeset.",
+            plan: [{ step: "Create deterministic changeset", status: "done" }],
+            changed_files: [{ path: "FORGE_PHASE5_CHANGESET.md", summary: "Recorded deterministic bridge evidence." }],
+            tests_added_or_updated: [{ name: "forge_bridge_run_once", evidence: "The bridge committed FORGE_PHASE5_CHANGESET.md." }],
+            docs_added_or_updated: [{ path: "FORGE_PHASE5_CHANGESET.md", summary: "Deterministic evidence document created for the run." }],
+            acceptance_criteria: [
+                {
+                    criterion,
+                    evidence: `FORGE_PHASE5_CHANGESET.md was committed with content hash ${changesetHash}.`,
+                    status: "satisfied"
+                }
+            ],
+            known_gaps: [],
+            next_phase_context: "Review FORGE_PHASE5_CHANGESET.md and the bridge commit before validation."
+        };
+    }
+    if (phase === "self_review") {
+        return {
+            status: "pass",
+            summary: "forge-bridge fake worker completed deterministic self-review.",
+            reviewed_diff: true,
+            findings: [],
+            security_review: {
+                status: "pass",
+                notes: "No secret handling, auth, or destructive behavior changes were introduced by the deterministic changeset."
+            },
+            edge_case_review: {
+                status: "pass",
+                notes: "The deterministic fake-worker changeset is intentionally narrow and repeatable."
+            },
+            design_review: {
+                status: "not_applicable",
+                screenshots: [],
+                notes: "No UI changes."
+            },
+            deterministic_comparison: {
+                status: "pass",
+                command_or_tool: "git diff --stat HEAD~1..HEAD",
+                notes: `Reviewed deterministic changeset with content hash ${changesetHash}.`
+            },
+            fixes_applied: [],
+            remaining_risks: []
+        };
+    }
+    return {
+        status: "pass",
+        summary: "forge-bridge fake worker completed deterministic validation.",
+        commands: [
+            {
+                command: "git status --short && git diff --check",
+                exit_code: 0,
+                status: "pass",
+                summary: "Deterministic validation command completed for the fake-worker changeset."
+            }
+        ],
+        acceptance_criteria: [
+            {
+                criterion,
+                evidence: `FORGE_PHASE5_CHANGESET.md exists with content hash ${changesetHash}.`,
+                status: "satisfied"
+            }
+        ],
+        build_status: "pass",
+        test_status: "pass",
+        lint_status: "not_applicable",
+        design_status: "not_applicable",
+        drift_checks: [
+            {
+                command_or_tool: "git diff --check",
+                status: "pass",
+                summary: "No deterministic drift or whitespace errors were reported for the fake-worker changeset."
+            }
+        ],
+        ready_for_dev_test: true
+    };
+}
+async function emitCompletionArtifactRecorded(emit, worktreePath, artifact) {
+    const relativePath = path.relative(worktreePath, artifact.path) || path.basename(artifact.path);
+    await emit({
+        role: "tool",
+        kind: "tool_result",
+        content: `Forge completion tool recorded ${artifact.phase ?? "unknown"} artifact ${relativePath} (${artifact.status}).`,
+        eventType: "completion_tool_artifact_recorded"
+    });
+}
+async function emitPhaseCompletionEvent(emit, artifact) {
+    const phase = completionPhaseFromArtifact(artifact);
+    await emit({
+        role: "assistant",
+        kind: "message",
+        content: `${phase.replace(/_/g, " ")} completion artifact recorded with status ${artifact.status}.`,
+        eventType: phaseCompleteEventType(phase)
+    });
+}
+async function emitPhaseGateEvents(emit, artifact) {
+    const phase = completionPhaseFromArtifact(artifact);
+    const status = (artifact.status ?? "").trim().toLowerCase() || "unknown";
+    await emit({
+        role: "hook",
+        kind: "checkpoint",
+        content: `phase_gate: ${phase} artifact accepted with status ${status}.`,
+        eventType: "phase_gate"
+    });
+    if (status !== "pass") {
+        return;
+    }
+    const progression = phase === "implementation"
+        ? "phase_progression: implementation -> self_review"
+        : phase === "self_review"
+            ? "phase_progression: self_review -> validation"
+            : "phase_progression: validation -> Dev Test ready";
+    await emit({
+        role: "hook",
+        kind: "checkpoint",
+        content: progression,
+        eventType: "phase_gate"
+    });
+}
+function completionPhaseFromArtifact(artifact) {
+    const phase = artifact.phase?.trim();
+    return phase === "self_review" || phase === "validation" || phase === "implementation"
+        ? phase
+        : "implementation";
+}
+class LiveCompletionArtifactEmitter {
+    worktreePath;
+    workItemId;
+    emit;
+    phases;
+    emitted = new Set();
+    timer = null;
+    pending = Promise.resolve();
+    constructor(worktreePath, workItemId, phase, developCycle, emit) {
+        this.worktreePath = worktreePath;
+        this.workItemId = workItemId;
+        this.emit = emit;
+        this.phases = developCycle
+            ? developCyclePhaseOrder.slice(developCyclePhaseOrder.indexOf(phase))
+            : [phase];
+    }
+    start() {
+        void this.pollQueued();
+        this.timer = setInterval(() => {
+            void this.pollQueued();
+        }, 250);
+    }
+    async stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        await this.pollQueued();
+    }
+    hasEmitted(phase) {
+        return this.emitted.has(phase);
+    }
+    pollQueued() {
+        this.pending = this.pending
+            .then(() => this.poll())
+            .catch(() => undefined);
+        return this.pending;
+    }
+    async poll() {
+        for (const phase of this.phases) {
+            if (this.emitted.has(phase)) {
+                continue;
+            }
+            const artifact = await readCompletionArtifact(this.worktreePath, this.workItemId, phase);
+            if (!artifact) {
+                return;
+            }
+            this.emitted.add(phase);
+            await emitCompletionArtifactRecorded(this.emit, this.worktreePath, artifact);
+            await emitPhaseCompletionEvent(this.emit, artifact);
+            await emitPhaseGateEvents(this.emit, artifact);
+            if ((artifact.status ?? "").trim().toLowerCase() !== "pass") {
+                return;
+            }
+        }
+    }
+}
+async function readCompletionArtifactsForRun(worktreePath, workItemId, phase, developCycle) {
+    if (!developCycle) {
+        const artifact = await readCompletionArtifact(worktreePath, workItemId, phase);
+        if (!artifact) {
+            throw new Error(`Provider CLI completed but did not call the Forge ${phase} completion tool.`);
+        }
+        return [artifact];
+    }
+    const artifacts = [];
+    for (const expectedPhase of ["implementation", "self_review", "validation"]) {
+        const artifact = await readCompletionArtifact(worktreePath, workItemId, expectedPhase);
+        if (!artifact) {
+            if (artifacts.length === 0) {
+                throw new Error("Provider CLI completed but did not call the Forge implementation completion tool.");
+            }
+            const previous = artifacts[artifacts.length - 1];
+            if ((previous.status ?? "").trim().toLowerCase() === "pass") {
+                throw new Error(`Provider CLI completed after ${previous.phase} passed but did not call the Forge ${expectedPhase} completion tool.`);
+            }
+            return artifacts;
+        }
+        artifacts.push(artifact);
+        if ((artifact.status ?? "").trim().toLowerCase() !== "pass") {
+            return artifacts;
+        }
+    }
+    return artifacts;
+}
+function providerRedactionEnv(dispatch) {
+    const env = completionRedactionEnv(exactRedactionSecrets(dispatch));
+    return Object.keys(env).length > 0 ? env : undefined;
+}
+function exactRedactionSecrets(dispatch) {
+    return dispatch.apiKeySecretGrant?.secret ? [dispatch.apiKeySecretGrant.secret] : [];
+}
+async function emitProviderUsageEvent(emit, dispatch, outputState) {
+    const usage = outputState.usage;
+    if (hasUsage(usage)) {
+        await emit(buildProviderUsageEvent(dispatch, usage));
+    }
+}
+function estimatedDeterministicUsage() {
+    return addUsage(emptyUsage("estimated"), {
+        inputTokens: 1000,
+        outputTokens: 400,
+        source: "estimated"
+    });
+}
 export class StreamingProviderProcessRunner {
     async run(request, handlers = {}, signal) {
         const launch = await resolveProviderProcessLaunch(request.command, request.args);
         return await new Promise((resolve, reject) => {
             const child = spawn(launch.command, launch.args, {
                 cwd: request.cwd,
+                env: request.env ? { ...process.env, ...request.env } : undefined,
                 stdio: ["ignore", "pipe", "pipe"],
                 windowsHide: true
             });
@@ -551,6 +797,19 @@ ${completionPromptForPhase(phase)}
 
 Finish with a concise summary of changed files and verification after calling the completion tool.`;
 }
+function buildDevelopCyclePrompt(dispatch, phase = completionPhaseFromDispatch(dispatch)) {
+    return `You are Forge's develop-cycle runner running locally in a prepared git worktree.
+
+Read .forge/work-items/${dispatch.workItem.id}/spec.md, implement the work item, self-review the diff, then validate it in this same provider session.
+Start in the ${phase.replace(/_/g, " ")} phase. Do not stop after implementation if it passes; continue through self-review and validation using the next instruction returned by each completion tool.
+Use the repository's existing conventions. Run relevant tests when practical.
+Forge owns protocol files: worktree prep, injected .forge commands/hooks/skills, phase verdict artifacts, reports, and commits.
+Read Forge-provided context under .forge when needed, but do not edit .forge files or create Forge verdict/report artifacts by hand.
+
+${completionPromptForDevelopCycle(phase)}
+
+Finish with a concise summary of changed files and verification after the validation completion tool has accepted the work, or after the current phase tool records a non-pass blocker.`;
+}
 function phaseWorkInstruction(phase) {
     if (phase === "self_review") {
         return "Review the implementation diff, apply safe fixes when needed, and record remaining risks explicitly.";
@@ -626,9 +885,13 @@ class CursorStreamJsonState {
     sessionId = null;
     finalMessage = null;
     emittedSession = false;
+    accumulatedUsage = null;
     get sessionLabel() {
         return this.sessionId ? `session ${this.sessionId}` : null;
     }
+    get usage() {
+        return this.accumulatedUsage;
+    }
     consume(line) {
         const event = parseJsonLine(line);
         if (!event) {
@@ -690,6 +953,7 @@ class CursorStreamJsonState {
             if (result) {
                 this.finalMessage = clip(result, 4000);
             }
+            this.accumulateUsage(event);
         }
         if (type === "error" || (type === "result" && event.is_error === true)) {
             return {
@@ -701,6 +965,21 @@ class CursorStreamJsonState {
         }
         return null;
     }
+    accumulateUsage(event) {
+        const usage = objectField(event, "usage");
+        const durationMs = readUsageNumber(event, "duration_ms") || readUsageNumber(event, "duration_api_ms");
+        if (Object.keys(usage).length === 0 && durationMs === 0) {
+            return;
+        }
+        this.accumulatedUsage = addUsage(this.accumulatedUsage ?? emptyUsage("provider_reported"), {
+            inputTokens: readUsageNumber(usage, "inputTokens"),
+            outputTokens: readUsageNumber(usage, "outputTokens"),
+            cacheReadTokens: readUsageNumber(usage, "cacheReadTokens"),
+            cacheCreationTokens: readUsageNumber(usage, "cacheWriteTokens"),
+            providerDurationMs: durationMs > 0 ? durationMs : null,
+            source: "provider_reported"
+        });
+    }
 }
 function formatCursorToolCallStarted(toolCall) {
     const readArgs = objectField(objectField(toolCall, "readToolCall"), "args");
@@ -805,9 +1084,13 @@ class CodexJsonState {
     threadId = null;
     finalMessage = null;
     emittedThread = false;
+    accumulatedUsage = null;
     get sessionLabel() {
         return this.threadId ? `thread ${this.threadId}` : null;
     }
+    get usage() {
+        return this.accumulatedUsage;
+    }
     consume(line) {
         const event = parseJsonLine(line);
         if (!event) {
@@ -827,6 +1110,7 @@ class CodexJsonState {
             }
         }
         if (type === "turn.completed") {
+            this.accumulateUsage(event);
             return {
                 role: "runner",
                 kind: "checkpoint",
@@ -872,6 +1156,19 @@ class CodexJsonState {
         }
         return null;
     }
+    accumulateUsage(event) {
+        const usage = objectField(event, "usage");
+        if (Object.keys(usage).length === 0) {
+            return;
+        }
+        this.accumulatedUsage = addUsage(this.accumulatedUsage ?? emptyUsage("provider_reported"), {
+            inputTokens: readUsageNumber(usage, "input_tokens"),
+            outputTokens: readUsageNumber(usage, "output_tokens"),
+            cacheReadTokens: readUsageNumber(usage, "cached_input_tokens"),
+            reasoningOutputTokens: readUsageNumber(usage, "reasoning_output_tokens"),
+            source: "provider_reported"
+        });
+    }
 }
 function objectField(source, key) {
     const value = source[key];

package/dist/session/provider-cli/provider-usage.d.ts

@@ -0,0 +1,25 @@
+import type { RunOnceDispatchPacket, RunnerDispatchEvent } from "../session.types.js";
+export type UsageSource = "provider_reported" | "cli_reported" | "estimated" | "unknown";
+/**
+ * Normalized, provider-agnostic token usage accumulated for a dispatch. Cost is never computed
+ * here; the API recomputes cost from these tokens x model rates (ADR-0006).
+ */
+export interface ProviderUsage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cacheReadTokens: number;
+    readonly cacheCreationTokens: number;
+    readonly reasoningOutputTokens: number;
+    readonly providerDurationMs: number | null;
+    readonly source: UsageSource;
+}
+export declare function emptyUsage(source?: UsageSource): ProviderUsage;
+export declare function addUsage(base: ProviderUsage, next: Partial<ProviderUsage>): ProviderUsage;
+export declare function totalTokens(usage: ProviderUsage): number;
+export declare function hasUsage(usage: ProviderUsage | null): usage is ProviderUsage;
+/**
+ * Builds the durable `provider_usage` event. Token numbers travel as a structured `data` JSON
+ * string (snake_case) that the API parses into a usage_event row.
+ */
+export declare function buildProviderUsageEvent(dispatch: RunOnceDispatchPacket, usage: ProviderUsage): RunnerDispatchEvent;
+export declare function readUsageNumber(source: Record<string, unknown>, key: string): number;