@loucompanion/forge-bridge 0.1.3-dev.fbe15023cdfe → 0.1.4-dev.41da3780c451

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

@@ -19,6 +19,8 @@ export interface ProviderCliDraftContext {
 }
 export interface ProviderCliRunResult {
     readonly summary: string;
+    readonly resultCommitSha?: string | null;
+    readonly publishedCommitSha?: string | null;
     readonly spec?: RunnerDispatchSpec | null;
     readonly artifact?: RunnerDispatchArtifact | null;
     readonly artifacts?: readonly RunnerDispatchArtifact[] | null;

package/dist/session/provider-cli/provider-output-state.d.ts

@@ -4,6 +4,8 @@ export declare function messageFromError(error: unknown): string;
 export declare function clip(value: string, maxLength: number): string;
 export interface ProviderOutputState {
     readonly sessionLabel: string | null;
+    /** Stable provider conversation identifier used for an in-place repair turn. */
+    readonly providerThreadId: string | null;
     finalMessage: string | null;
     /** True only while the provider has reported a tool/command start without a matching completion. */
     readonly hasActiveToolCall: boolean;
@@ -13,6 +15,14 @@ export interface ProviderOutputState {
 }
 export declare function createProviderOutputState(provider: string): ProviderOutputState;
 export declare function parseJsonLine(line: string): Record<string, unknown> | null;
+/**
+ * Claude Code exposes MCP tools as `mcp__<server>__<tool>` and replaces characters outside
+ * `[A-Za-z0-9_-]` with `_`, so `forge.complete_qa` arrives as `mcp__forge__forge_complete_qa`.
+ */
+export declare function parseClaudeMcpToolName(name: string): {
+    readonly server: string;
+    readonly tool: string;
+} | null;
 export declare function formatCodexMcpToolCallEvents(type: string, event: Record<string, unknown>): readonly RunnerDispatchEvent[];
 export declare function objectField(source: Record<string, unknown>, key: string): Record<string, unknown>;
 export declare function stringField(source: Record<string, unknown>, key: string): string | null;

package/dist/session/provider-cli/provider-output-state.js

@@ -16,9 +16,14 @@ export function clip(value, maxLength) {
     return `${value.slice(0, maxLength - ellipsis.length)}${ellipsis}`;
 }
 export function createProviderOutputState(provider) {
-    return provider.trim().toLowerCase() === "cursor"
-        ? new CursorStreamJsonState()
-        : new CodexJsonState();
+    const normalized = provider.trim().toLowerCase();
+    if (normalized === "cursor") {
+        return new CursorStreamJsonState();
+    }
+    if (normalized === "claude") {
+        return new ClaudeStreamJsonState();
+    }
+    return new CodexJsonState();
 }
 class CursorStreamJsonState {
     sessionId = null;
@@ -29,6 +34,9 @@ class CursorStreamJsonState {
     get sessionLabel() {
         return this.sessionId ? `session ${this.sessionId}` : null;
     }
+    get providerThreadId() {
+        return this.sessionId;
+    }
     get usage() {
         return this.accumulatedUsage;
     }
@@ -49,7 +57,8 @@ class CursorStreamJsonState {
                         role: "runner",
                         kind: "checkpoint",
                         content: `Cursor session started: ${this.sessionId}.`,
-                        eventType: "provider_thread_started"
+                        eventType: "provider_thread_started",
+                        data: JSON.stringify({ threadId: this.sessionId })
                     }];
             }
         }
@@ -116,13 +125,19 @@ class CursorStreamJsonState {
         if (Object.keys(usage).length === 0 && durationMs === 0) {
             return;
         }
+        const uncachedInputTokens = readUsageNumber(usage, "inputTokens");
+        const cacheReadTokens = readUsageNumber(usage, "cacheReadTokens");
+        const cacheCreationTokens = readUsageNumber(usage, "cacheWriteTokens");
         this.accumulatedUsage = addUsage(this.accumulatedUsage ?? emptyUsage("provider_reported"), {
-            inputTokens: readUsageNumber(usage, "inputTokens"),
+            inputTokens: uncachedInputTokens + cacheReadTokens + cacheCreationTokens,
+            uncachedInputTokens,
             outputTokens: readUsageNumber(usage, "outputTokens"),
-            cacheReadTokens: readUsageNumber(usage, "cacheReadTokens"),
-            cacheCreationTokens: readUsageNumber(usage, "cacheWriteTokens"),
+            cacheReadTokens,
+            cacheCreationTokens,
             providerDurationMs: durationMs > 0 ? durationMs : null,
-            source: "provider_reported"
+            source: "provider_reported",
+            inputTokenSemantics: "excludes_cache_tokens",
+            rawUsage: [{ provider: "cursor", usage }]
         });
     }
 }
@@ -225,6 +240,292 @@ export function parseJsonLine(line) {
         ? parsed
         : null;
 }
+const claudeFileEditTools = new Set(["edit", "multiedit", "write", "notebookedit"]);
+/**
+ * Parses `claude -p --output-format stream-json --verbose` output. Each line is one of:
+ * `system/init`, `assistant` (text + tool_use blocks), `user` (tool_result blocks), or the
+ * terminal `result` event that carries the aggregated usage for the whole run.
+ */
+class ClaudeStreamJsonState {
+    sessionId = null;
+    finalMessage = null;
+    emittedSession = false;
+    accumulatedUsage = null;
+    activeToolUses = new Map();
+    get sessionLabel() {
+        return this.sessionId ? `session ${this.sessionId}` : null;
+    }
+    get providerThreadId() {
+        return this.sessionId;
+    }
+    get usage() {
+        return this.accumulatedUsage;
+    }
+    get hasActiveToolCall() {
+        return this.activeToolUses.size > 0;
+    }
+    consume(line) {
+        const event = parseJsonLine(line);
+        if (!event) {
+            return [];
+        }
+        const type = stringField(event, "type");
+        if (type === "system" && stringField(event, "subtype") === "init") {
+            return this.consumeInit(event);
+        }
+        if (type === "assistant") {
+            return this.consumeAssistant(event);
+        }
+        if (type === "user") {
+            return this.consumeToolResults(event);
+        }
+        if (type === "result") {
+            return this.consumeResult(event, line);
+        }
+        if (type === "error") {
+            return [providerCliError(line)];
+        }
+        return [];
+    }
+    consumeInit(event) {
+        const events = [];
+        this.sessionId = stringField(event, "session_id") ?? this.sessionId;
+        if (this.sessionId && !this.emittedSession) {
+            this.emittedSession = true;
+            events.push({
+                role: "runner",
+                kind: "checkpoint",
+                content: `Claude session started: ${this.sessionId}.`,
+                eventType: "provider_thread_started"
+            });
+        }
+        const servers = Array.isArray(event.mcp_servers) ? event.mcp_servers : [];
+        for (const entry of servers) {
+            if (!entry || typeof entry !== "object") {
+                continue;
+            }
+            const server = entry;
+            const name = stringField(server, "name");
+            const status = stringField(server, "status");
+            if (name && status && status !== "connected") {
+                events.push({
+                    role: "runner",
+                    kind: "checkpoint",
+                    content: `Claude MCP server ${name} is ${status}.`,
+                    eventType: "provider_mcp_server_status",
+                    data: JSON.stringify({ server_name: name, status })
+                });
+            }
+        }
+        return events;
+    }
+    consumeAssistant(event) {
+        const events = [];
+        const text = assistantMessageText(event);
+        if (text) {
+            this.finalMessage = text;
+            events.push({
+                role: "assistant",
+                kind: "message",
+                content: clip(text, 4000),
+                eventType: "provider_message"
+            });
+        }
+        for (const block of messageContentBlocks(event)) {
+            if (stringField(block, "type") !== "tool_use") {
+                continue;
+            }
+            const id = stringField(block, "id");
+            const name = stringField(block, "name");
+            if (!id || !name) {
+                continue;
+            }
+            const toolUse = { name, input: objectField(block, "input") };
+            this.activeToolUses.set(id, toolUse);
+            events.push(...formatClaudeToolUseStarted(toolUse));
+        }
+        return events;
+    }
+    consumeToolResults(event) {
+        const events = [];
+        for (const block of messageContentBlocks(event)) {
+            if (stringField(block, "type") !== "tool_result") {
+                continue;
+            }
+            const id = stringField(block, "tool_use_id");
+            const toolUse = id ? this.activeToolUses.get(id) : undefined;
+            if (!id || !toolUse) {
+                continue;
+            }
+            this.activeToolUses.delete(id);
+            events.push(...formatClaudeToolUseCompleted(toolUse, block.is_error === true, toolResultText(block)));
+        }
+        return events;
+    }
+    consumeResult(event, line) {
+        this.activeToolUses.clear();
+        this.accumulateUsage(event);
+        const result = stringField(event, "result");
+        const subtype = stringField(event, "subtype") ?? "";
+        const failed = event.is_error === true || subtype.startsWith("error");
+        if (!failed) {
+            if (result) {
+                this.finalMessage = result;
+            }
+            return [{
+                    role: "runner",
+                    kind: "checkpoint",
+                    content: "Claude turn completed.",
+                    eventType: "provider_turn_completed"
+                }];
+        }
+        return [providerCliError(line)];
+    }
+    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;
+        }
+        // Anthropic's input_tokens excludes cache reads and writes; normalize to a cache-inclusive total.
+        const uncachedInputTokens = readUsageNumber(usage, "input_tokens");
+        const cacheReadTokens = readUsageNumber(usage, "cache_read_input_tokens");
+        const cacheCreationTokens = readUsageNumber(usage, "cache_creation_input_tokens");
+        this.accumulatedUsage = addUsage(this.accumulatedUsage ?? emptyUsage("provider_reported"), {
+            inputTokens: uncachedInputTokens + cacheReadTokens + cacheCreationTokens,
+            uncachedInputTokens,
+            outputTokens: readUsageNumber(usage, "output_tokens"),
+            cacheReadTokens,
+            cacheCreationTokens,
+            providerDurationMs: durationMs > 0 ? durationMs : null,
+            source: "provider_reported",
+            inputTokenSemantics: "excludes_cache_tokens",
+            rawUsage: [{ provider: "claude", usage }]
+        });
+    }
+}
+function providerCliError(line) {
+    return {
+        role: "runner",
+        kind: "error",
+        content: clip(line.trim(), 1000),
+        eventType: "provider_cli_error"
+    };
+}
+function messageContentBlocks(event) {
+    const content = objectField(event, "message").content;
+    if (!Array.isArray(content)) {
+        return [];
+    }
+    return content.filter((entry) => Boolean(entry) && typeof entry === "object" && !Array.isArray(entry));
+}
+function toolResultText(block) {
+    const content = block.content;
+    if (typeof content === "string") {
+        return content.trim() || null;
+    }
+    if (!Array.isArray(content)) {
+        return null;
+    }
+    const text = content
+        .map((entry) => entry && typeof entry === "object" ? stringField(entry, "text") : null)
+        .filter((part) => Boolean(part))
+        .join("\n")
+        .trim();
+    return text || null;
+}
+/**
+ * Claude Code exposes MCP tools as `mcp__<server>__<tool>` and replaces characters outside
+ * `[A-Za-z0-9_-]` with `_`, so `forge.complete_qa` arrives as `mcp__forge__forge_complete_qa`.
+ */
+export function parseClaudeMcpToolName(name) {
+    const match = /^mcp__(.+?)__(.+)$/u.exec(name);
+    if (!match) {
+        return null;
+    }
+    const server = match[1] ?? "";
+    const rawTool = match[2] ?? "";
+    const tool = server === "forge" && rawTool.startsWith("forge_") ? `forge.${rawTool.slice("forge_".length)}` : rawTool;
+    return server && tool ? { server, tool } : null;
+}
+function claudeMcpEvents(toolUse, phase, errorText) {
+    const mcp = parseClaudeMcpToolName(toolUse.name);
+    if (!mcp) {
+        return null;
+    }
+    const item = {
+        type: "mcp_tool_call",
+        server: mcp.server,
+        tool: mcp.tool,
+        status: phase
+    };
+    if (phase === "failed") {
+        item.error = errorText ? clip(errorText, 600) : "MCP tool call failed.";
+    }
+    return formatCodexMcpToolCallEvents(phase === "started" ? "item.started" : "item.completed", { item });
+}
+function formatClaudeToolUseStarted(toolUse) {
+    const mcp = claudeMcpEvents(toolUse, "started", null);
+    if (mcp) {
+        return mcp;
+    }
+    const normalized = toolUse.name.toLowerCase();
+    const filePath = stringField(toolUse.input, "file_path") ?? stringField(toolUse.input, "notebook_path") ?? stringField(toolUse.input, "path");
+    let content;
+    if (normalized === "bash") {
+        const command = stringField(toolUse.input, "command");
+        content = command ? `Shell command started: ${clip(command, 500)}` : "Shell command started.";
+    }
+    else if (normalized === "read" && filePath) {
+        content = `Reading ${filePath}`;
+    }
+    else if (claudeFileEditTools.has(normalized) && filePath) {
+        content = `Writing ${filePath}`;
+    }
+    else {
+        content = `Tool call started: ${toolUse.name}`;
+    }
+    return [{
+            role: "worker",
+            kind: "checkpoint",
+            content,
+            eventType: normalized === "bash" ? "provider_command" : "provider_tool_call"
+        }];
+}
+function formatClaudeToolUseCompleted(toolUse, isError, resultText) {
+    const mcp = claudeMcpEvents(toolUse, isError ? "failed" : "completed", resultText);
+    if (mcp) {
+        return mcp;
+    }
+    const normalized = toolUse.name.toLowerCase();
+    const filePath = stringField(toolUse.input, "file_path") ?? stringField(toolUse.input, "notebook_path") ?? stringField(toolUse.input, "path");
+    if (claudeFileEditTools.has(normalized) && filePath && !isError) {
+        return [{
+                role: "worker",
+                kind: "file_edit",
+                content: `Wrote ${filePath}`,
+                eventType: "provider_file_edit"
+            }];
+    }
+    const status = isError ? "failed" : "completed";
+    let content;
+    if (normalized === "bash") {
+        const command = stringField(toolUse.input, "command");
+        content = command ? `Shell command ${status}: ${clip(command, 500)}` : `Shell command ${status}.`;
+    }
+    else if (normalized === "read" && filePath) {
+        content = isError ? `Read failed: ${filePath}` : `Read ${filePath}`;
+    }
+    else {
+        content = `Tool call ${status}: ${toolUse.name}`;
+    }
+    return [{
+            role: "worker",
+            kind: "checkpoint",
+            content,
+            eventType: normalized === "bash" ? "provider_command" : "provider_tool_call"
+        }];
+}
 class CodexJsonState {
     threadId = null;
     finalMessage = null;
@@ -234,6 +535,9 @@ class CodexJsonState {
     get sessionLabel() {
         return this.threadId ? `thread ${this.threadId}` : null;
     }
+    get providerThreadId() {
+        return this.threadId;
+    }
     get usage() {
         return this.accumulatedUsage;
     }
@@ -255,7 +559,8 @@ class CodexJsonState {
                         role: "runner",
                         kind: "checkpoint",
                         content: `Codex thread started: ${this.threadId}.`,
-                        eventType: "provider_thread_started"
+                        eventType: "provider_thread_started",
+                        data: JSON.stringify({ threadId: this.threadId })
                     }];
             }
         }
@@ -332,12 +637,17 @@ class CodexJsonState {
         if (Object.keys(usage).length === 0) {
             return;
         }
+        const inputTokens = readUsageNumber(usage, "input_tokens");
+        const cacheReadTokens = readUsageNumber(usage, "cached_input_tokens");
         this.accumulatedUsage = addUsage(this.accumulatedUsage ?? emptyUsage("provider_reported"), {
-            inputTokens: readUsageNumber(usage, "input_tokens"),
+            inputTokens,
+            uncachedInputTokens: Math.max(0, inputTokens - cacheReadTokens),
             outputTokens: readUsageNumber(usage, "output_tokens"),
-            cacheReadTokens: readUsageNumber(usage, "cached_input_tokens"),
+            cacheReadTokens,
             reasoningOutputTokens: readUsageNumber(usage, "reasoning_output_tokens"),
-            source: "provider_reported"
+            source: "provider_reported",
+            inputTokenSemantics: "includes_cached_input",
+            rawUsage: [{ provider: "codex", usage }]
         });
     }
 }
@@ -425,11 +735,45 @@ function mcpErrorSummary(item) {
     if (direct) {
         return clip(direct, 600);
     }
-    const error = objectField(item, "error");
-    return stringField(error, "message")
-        ?? stringField(error, "summary")
-        ?? stringField(objectField(item, "result"), "error")
-        ?? null;
+    const messages = uniqueErrorMessages([
+        item.error,
+        item.result,
+        item.content,
+    ]);
+    return messages.length > 0 ? clip(messages.join(" Caused by: "), 600) : null;
+}
+function uniqueErrorMessages(values) {
+    const messages = [];
+    const seenMessages = new Set();
+    const seenObjects = new Set();
+    const visit = (value, depth) => {
+        if (depth > 8 || value === null || value === undefined)
+            return;
+        if (typeof value === "string") {
+            const message = value.trim();
+            if (message.length > 0 && !seenMessages.has(message)) {
+                seenMessages.add(message);
+                messages.push(message);
+            }
+            return;
+        }
+        if (typeof value !== "object" || seenObjects.has(value))
+            return;
+        seenObjects.add(value);
+        if (Array.isArray(value)) {
+            for (const entry of value)
+                visit(entry, depth + 1);
+            return;
+        }
+        const record = value;
+        for (const key of ["message", "summary", "error", "cause", "data", "details", "result", "content"]) {
+            if (key in record)
+                visit(record[key], depth + 1);
+        }
+    };
+    for (const value of values)
+        visit(value, 0);
+    return messages;
 }
 function safeProviderMcpData(item, serverName, toolName, status) {
     const elapsedMs = numericField(item, "elapsed_ms") ?? numericField(item, "duration_ms");

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

@@ -1,17 +1,24 @@
 import type { RunOnceDispatchPacket, RunnerDispatchEvent } from "../session.types.js";
 export type UsageSource = "provider_reported" | "cli_reported" | "estimated" | "unknown";
+export type InputTokenSemantics = "includes_cached_input" | "excludes_cache_tokens" | "unknown";
+export declare const PROVIDER_USAGE_SCHEMA_VERSION = 1;
 /**
  * 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 {
+    /** Normalized total input. Cached input is a subset, never an additive peer. */
     readonly inputTokens: number;
+    readonly uncachedInputTokens: number | null;
     readonly outputTokens: number;
     readonly cacheReadTokens: number;
     readonly cacheCreationTokens: number;
     readonly reasoningOutputTokens: number;
     readonly providerDurationMs: number | null;
     readonly source: UsageSource;
+    readonly inputTokenSemantics: InputTokenSemantics;
+    /** Exact provider usage objects retained for audit/re-normalization. */
+    readonly rawUsage: readonly Record<string, unknown>[];
 }
 export declare function emptyUsage(source?: UsageSource): ProviderUsage;
 export declare function addUsage(base: ProviderUsage, next: Partial<ProviderUsage>): ProviderUsage;

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

@@ -1,27 +1,38 @@
+export const PROVIDER_USAGE_SCHEMA_VERSION = 1;
 export function emptyUsage(source = "unknown") {
     return {
         inputTokens: 0,
+        uncachedInputTokens: 0,
         outputTokens: 0,
         cacheReadTokens: 0,
         cacheCreationTokens: 0,
         reasoningOutputTokens: 0,
         providerDurationMs: null,
-        source
+        source,
+        inputTokenSemantics: "unknown",
+        rawUsage: []
     };
 }
 export function addUsage(base, next) {
+    const nextUncached = next.uncachedInputTokens;
+    const uncachedInputTokens = base.uncachedInputTokens === null || nextUncached === null
+        ? null
+        : base.uncachedInputTokens + nonNegative(nextUncached);
     return {
         inputTokens: base.inputTokens + nonNegative(next.inputTokens),
+        uncachedInputTokens,
         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
+        source: next.source ?? base.source,
+        inputTokenSemantics: mergeSemantics(base.inputTokenSemantics, next.inputTokenSemantics),
+        rawUsage: [...base.rawUsage, ...(next.rawUsage ?? [])]
     };
 }
 export function totalTokens(usage) {
-    return usage.inputTokens + usage.outputTokens + usage.cacheReadTokens + usage.cacheCreationTokens;
+    return usage.inputTokens + usage.outputTokens;
 }
 export function hasUsage(usage) {
     return usage !== null && totalTokens(usage) > 0;
@@ -37,20 +48,26 @@ export function buildProviderUsageEvent(dispatch, usage) {
         lane: dispatch.execution.lane,
         phase: dispatch.cycleRun.phase,
         attempt: dispatch.cycleRun.attempt,
+        usage_schema_version: PROVIDER_USAGE_SCHEMA_VERSION,
+        input_token_semantics: usage.inputTokenSemantics,
         input_tokens: usage.inputTokens,
+        uncached_input_tokens: usage.uncachedInputTokens,
         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
+        provider_duration_ms: usage.providerDurationMs,
+        normalized_total_tokens: totalTokens(usage),
+        normalized_total_formula: "total_input + output; cached_input is a subset of total_input",
+        raw_usage: usage.rawUsage
     };
     const total = totalTokens(usage);
     return {
         role: "runner",
         kind: "checkpoint",
-        content: `Provider usage: ${total} tokens (${usage.inputTokens} in / ${usage.outputTokens} out) for ${dispatch.execution.model}.`,
+        content: `Provider usage: ${total} tokens (${usage.inputTokens} total in, including ${usage.cacheReadTokens} cached / ${usage.outputTokens} out) for ${dispatch.execution.model}.`,
         eventType: "provider_usage",
         data: JSON.stringify(data)
     };
@@ -62,3 +79,9 @@ export function readUsageNumber(source, key) {
 function nonNegative(value) {
     return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
 }
+function mergeSemantics(base, next) {
+    if (!next || next === "unknown") {
+        return base;
+    }
+    return base === "unknown" || base === next ? next : "unknown";
+}