@loucompanion/forge-bridge 0.1.1-dev.2bc1e7f19b3a → 0.1.1-dev.4f31cdd58cac

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

@@ -8,8 +8,10 @@ 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, 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;
@@ -75,8 +77,10 @@ export class ProcessBackedProviderCliService {
             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,
@@ -92,6 +96,7 @@ export class ProcessBackedProviderCliService {
             }, context.signal);
         }
         finally {
+            await liveCompletionEvents.stop();
             await cleanupCompletionTools(completionTools, context.emit);
         }
         if (result.exitCode !== 0) {
@@ -104,11 +109,15 @@ 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 completionArtifacts = await readCompletionArtifactsForRun(worktree.worktreePath, dispatch.workItem.id, phase, developCycle);
         for (const artifact of completionArtifacts) {
-            await emitCompletionArtifactRecorded(context.emit, worktree.worktreePath, artifact);
-            await emitPhaseCompletionEvent(context.emit, artifact);
+            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) {
@@ -173,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.`
         };
@@ -208,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",
@@ -283,6 +294,7 @@ export class DeterministicProviderCliService {
                 eventType: phaseCompleteEventType(completionPhase)
             });
         }
+        await context.emit(buildProviderUsageEvent(dispatch, estimatedDeterministicUsage()));
         return {
             summary: `forge-bridge completed ${worktree.branchName} (${developCycle ? "develop cycle" : phase}).`,
             spec: {
@@ -309,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."
         };
@@ -316,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",
@@ -430,12 +444,93 @@ async function emitPhaseCompletionEvent(emit, artifact) {
         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);
@@ -471,6 +566,19 @@ function providerRedactionEnv(dispatch) {
 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);
@@ -777,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) {
@@ -841,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 {
@@ -852,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");
@@ -956,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) {
@@ -978,6 +1110,7 @@ class CodexJsonState {
             }
         }
         if (type === "turn.completed") {
+            this.accumulateUsage(event);
             return {
                 role: "runner",
                 kind: "checkpoint",
@@ -1023,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;

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

@@ -0,0 +1,64 @@
+export function emptyUsage(source = "unknown") {
+    return {
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheReadTokens: 0,
+        cacheCreationTokens: 0,
+        reasoningOutputTokens: 0,
+        providerDurationMs: null,
+        source
+    };
+}
+export function addUsage(base, next) {
+    return {
+        inputTokens: base.inputTokens + nonNegative(next.inputTokens),
+        outputTokens: base.outputTokens + nonNegative(next.outputTokens),
+        cacheReadTokens: base.cacheReadTokens + nonNegative(next.cacheReadTokens),
+        cacheCreationTokens: base.cacheCreationTokens + nonNegative(next.cacheCreationTokens),
+        reasoningOutputTokens: base.reasoningOutputTokens + nonNegative(next.reasoningOutputTokens),
+        providerDurationMs: next.providerDurationMs ?? base.providerDurationMs,
+        source: next.source ?? base.source
+    };
+}
+export function totalTokens(usage) {
+    return usage.inputTokens + usage.outputTokens + usage.cacheReadTokens + usage.cacheCreationTokens;
+}
+export function hasUsage(usage) {
+    return usage !== null && totalTokens(usage) > 0;
+}
+/**
+ * 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 function buildProviderUsageEvent(dispatch, usage) {
+    const data = {
+        provider: dispatch.execution.provider,
+        model: dispatch.execution.model,
+        lane: dispatch.execution.lane,
+        phase: dispatch.cycleRun.phase,
+        attempt: dispatch.cycleRun.attempt,
+        input_tokens: usage.inputTokens,
+        output_tokens: usage.outputTokens,
+        cache_read_tokens: usage.cacheReadTokens,
+        cache_creation_tokens: usage.cacheCreationTokens,
+        reasoning_output_tokens: usage.reasoningOutputTokens,
+        metered: dispatch.execution.authKind === "api_key",
+        usage_source: usage.source,
+        provider_duration_ms: usage.providerDurationMs
+    };
+    const total = totalTokens(usage);
+    return {
+        role: "runner",
+        kind: "checkpoint",
+        content: `Provider usage: ${total} tokens (${usage.inputTokens} in / ${usage.outputTokens} out) for ${dispatch.execution.model}.`,
+        eventType: "provider_usage",
+        data: JSON.stringify(data)
+    };
+}
+export function readUsageNumber(source, key) {
+    const value = source[key];
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
+}
+function nonNegative(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}

package/dist/session/session.types.d.ts

@@ -87,6 +87,10 @@ export interface RunnerDispatchEvent {
     readonly kind: string;
     readonly content: string;
     readonly eventType: string;
+    /** Provider/runner-reported event time (ISO-8601) when available, preserved for accurate durations. */
+    readonly occurredAt?: string | null;
+    /** Optional structured telemetry payload (JSON string), e.g. token usage for provider_usage events. */
+    readonly data?: string | null;
 }
 export interface RunnerDispatchSpec {
     readonly repoPath: string;

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const forgeBridgeVersion = "0.1.1-dev.2bc1e7f19b3a";
+export declare const forgeBridgeVersion = "0.1.1-dev.4f31cdd58cac";

package/dist/version.js

@@ -1 +1 @@
-export const forgeBridgeVersion = "0.1.1-dev.2bc1e7f19b3a";
+export const forgeBridgeVersion = "0.1.1-dev.4f31cdd58cac";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loucompanion/forge-bridge",
-  "version": "0.1.1-dev.2bc1e7f19b3a",
+  "version": "0.1.1-dev.4f31cdd58cac",
   "description": "Forge runner bridge CLI for connecting local developer machines to Forge dispatch.",
   "license": "UNLICENSED",
   "type": "module",