@loucompanion/forge-bridge 0.1.3-dev.bd0c67bbf352 → 0.1.3-dev.d1ca67076aa9

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

@@ -0,0 +1,20 @@
+import type { RunnerDispatchEvent } from "../session.types.js";
+import { type ProviderUsage } from "./provider-usage.js";
+export declare function messageFromError(error: unknown): string;
+export declare function clip(value: string, maxLength: number): string;
+export interface ProviderOutputState {
+    readonly sessionLabel: string | null;
+    finalMessage: string | null;
+    /** Accumulated provider-reported token usage for this run, or null when none was reported. */
+    readonly usage: ProviderUsage | null;
+    consume(line: string): readonly RunnerDispatchEvent[];
+}
+export declare function createProviderOutputState(provider: string): ProviderOutputState;
+export declare function parseJsonLine(line: string): Record<string, unknown> | 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;
+export declare function numericField(source: Record<string, unknown>, key: string): number | null;
+export declare function stripUndefined(value: Record<string, unknown>): Record<string, unknown>;
+export declare function normalizedString(value: string): string;
+export declare function isNodeError(error: unknown): error is NodeJS.ErrnoException;

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

@@ -0,0 +1,445 @@
+import { addUsage, emptyUsage, readUsageNumber } from "./provider-usage.js";
+export function messageFromError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function clip(value, maxLength) {
+    if (maxLength <= 0) {
+        return "";
+    }
+    if (value.length <= maxLength) {
+        return value;
+    }
+    const ellipsis = "...";
+    if (maxLength <= ellipsis.length) {
+        return ellipsis.slice(0, maxLength);
+    }
+    return `${value.slice(0, maxLength - ellipsis.length)}${ellipsis}`;
+}
+export function createProviderOutputState(provider) {
+    return provider.trim().toLowerCase() === "cursor"
+        ? new CursorStreamJsonState()
+        : new CodexJsonState();
+}
+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) {
+            return [];
+        }
+        const type = stringField(event, "type");
+        if (type === "system" && stringField(event, "subtype") === "init") {
+            this.sessionId = stringField(event, "session_id");
+            if (this.sessionId && !this.emittedSession) {
+                this.emittedSession = true;
+                return [{
+                        role: "runner",
+                        kind: "checkpoint",
+                        content: `Cursor session started: ${this.sessionId}.`,
+                        eventType: "provider_thread_started"
+                    }];
+            }
+        }
+        if (type === "assistant") {
+            const text = assistantMessageText(event);
+            if (text) {
+                this.finalMessage = text;
+                return [{
+                        role: "assistant",
+                        kind: "message",
+                        content: clip(text, 4000),
+                        eventType: "provider_message"
+                    }];
+            }
+        }
+        if (type === "tool_call") {
+            const subtype = stringField(event, "subtype");
+            const toolCall = objectField(event, "tool_call");
+            if (subtype === "started") {
+                const summary = formatCursorToolCallStarted(toolCall);
+                if (summary) {
+                    return [{
+                            role: "worker",
+                            kind: "checkpoint",
+                            content: summary,
+                            eventType: "provider_tool_call"
+                        }];
+                }
+            }
+            if (subtype === "completed") {
+                const completed = formatCursorToolCallCompleted(toolCall);
+                if (completed) {
+                    return [{
+                            role: "worker",
+                            kind: completed.kind,
+                            content: completed.content,
+                            eventType: completed.kind === "file_edit" ? "provider_file_edit" : "provider_tool_call"
+                        }];
+                }
+            }
+        }
+        if (type === "result" && stringField(event, "subtype") === "success") {
+            const result = stringField(event, "result");
+            if (result) {
+                this.finalMessage = result;
+            }
+            this.accumulateUsage(event);
+        }
+        if (type === "error" || (type === "result" && event.is_error === true)) {
+            return [{
+                    role: "runner",
+                    kind: "error",
+                    content: clip(line.trim(), 1000),
+                    eventType: "provider_cli_error"
+                }];
+        }
+        return [];
+    }
+    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");
+    const readPath = stringField(readArgs, "path");
+    if (readPath) {
+        return `Reading ${readPath}`;
+    }
+    const writeArgs = objectField(objectField(toolCall, "writeToolCall"), "args");
+    const writePath = stringField(writeArgs, "path");
+    if (writePath) {
+        return `Writing ${writePath}`;
+    }
+    const shellArgs = objectField(objectField(toolCall, "shellToolCall"), "args");
+    const command = stringField(shellArgs, "command");
+    if (command) {
+        return `Shell command started: ${clip(command, 500)}`;
+    }
+    const fn = objectField(toolCall, "function");
+    const name = stringField(fn, "name");
+    if (name) {
+        return `Tool call started: ${name}`;
+    }
+    return null;
+}
+function formatCursorToolCallCompleted(toolCall) {
+    const writeArgs = objectField(objectField(toolCall, "writeToolCall"), "args");
+    const writePath = stringField(writeArgs, "path");
+    const writeResult = objectField(objectField(objectField(toolCall, "writeToolCall"), "result"), "success");
+    const writtenPath = stringField(writeResult, "path") ?? writePath;
+    if (writtenPath) {
+        return {
+            kind: "file_edit",
+            content: `Wrote ${writtenPath}`
+        };
+    }
+    const readArgs = objectField(objectField(toolCall, "readToolCall"), "args");
+    const readPath = stringField(readArgs, "path");
+    if (readPath) {
+        const readResult = objectField(objectField(objectField(toolCall, "readToolCall"), "result"), "success");
+        const totalLines = readResult.totalLines;
+        const lineSummary = typeof totalLines === "number" ? ` (${totalLines} lines)` : "";
+        return {
+            kind: "checkpoint",
+            content: `Read ${readPath}${lineSummary}`
+        };
+    }
+    const shellArgs = objectField(objectField(toolCall, "shellToolCall"), "args");
+    const command = stringField(shellArgs, "command");
+    if (command) {
+        return {
+            kind: "checkpoint",
+            content: `Shell command completed: ${clip(command, 500)}`
+        };
+    }
+    const fn = objectField(toolCall, "function");
+    const name = stringField(fn, "name");
+    if (name) {
+        return {
+            kind: "checkpoint",
+            content: `Tool call completed: ${name}`
+        };
+    }
+    return null;
+}
+function assistantMessageText(event) {
+    const message = objectField(event, "message");
+    const content = message.content;
+    if (!Array.isArray(content)) {
+        return null;
+    }
+    const parts = content
+        .map((entry) => {
+        if (!entry || typeof entry !== "object") {
+            return null;
+        }
+        const block = entry;
+        return stringField(block, "text");
+    })
+        .filter((text) => Boolean(text));
+    if (parts.length === 0) {
+        return null;
+    }
+    return parts.join("");
+}
+export function parseJsonLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("{")) {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return null;
+    }
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+        ? parsed
+        : null;
+}
+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) {
+            return [];
+        }
+        const type = stringField(event, "type") ?? "";
+        if (type === "thread.started") {
+            this.threadId = stringField(event, "thread_id");
+            if (this.threadId && !this.emittedThread) {
+                this.emittedThread = true;
+                return [{
+                        role: "runner",
+                        kind: "checkpoint",
+                        content: `Codex thread started: ${this.threadId}.`,
+                        eventType: "provider_thread_started"
+                    }];
+            }
+        }
+        if (type === "turn.completed") {
+            this.accumulateUsage(event);
+            return [{
+                    role: "runner",
+                    kind: "checkpoint",
+                    content: "Codex turn completed.",
+                    eventType: "provider_turn_completed"
+                }];
+        }
+        if (type === "turn.failed" || type === "error") {
+            return [{
+                    role: "runner",
+                    kind: "error",
+                    content: clip(line.trim(), 1000),
+                    eventType: "provider_cli_error"
+                }];
+        }
+        if (type === "item.completed" || type === "item.updated") {
+            const item = objectField(event, "item");
+            const itemType = stringField(item, "type");
+            if (itemType === "agent_message") {
+                const text = stringField(item, "text");
+                if (text) {
+                    this.finalMessage = text;
+                    return [{
+                            role: "assistant",
+                            kind: "message",
+                            content: clip(text, 4000),
+                            eventType: "provider_message"
+                        }];
+                }
+            }
+            if (itemType === "command_execution") {
+                const command = stringField(item, "command");
+                const status = stringField(item, "status");
+                if (command) {
+                    return [{
+                            role: "worker",
+                            kind: "checkpoint",
+                            content: `Codex command ${status || "completed"}: ${clip(command, 500)}`,
+                            eventType: "provider_command"
+                        }];
+                }
+            }
+        }
+        const mcpEvents = formatCodexMcpToolCallEvents(type, event);
+        if (mcpEvents.length > 0) {
+            return mcpEvents;
+        }
+        return [];
+    }
+    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"
+        });
+    }
+}
+export function formatCodexMcpToolCallEvents(type, event) {
+    if (type !== "item.started" && type !== "item.updated" && type !== "item.completed") {
+        return [];
+    }
+    const item = objectField(event, "item");
+    const itemType = stringField(item, "type") ?? "";
+    const serverName = mcpServerName(item);
+    const toolName = mcpToolName(item);
+    const isMcpItem = itemType.toLowerCase().includes("mcp")
+        || Boolean(serverName)
+        || (toolName ? isForgeCompletionTool(toolName) || toolName.toLowerCase().includes("mcp") : false);
+    if (!isMcpItem || !toolName) {
+        return [];
+    }
+    const status = normalizedString(stringField(item, "status")
+        ?? stringField(event, "status")
+        ?? (type === "item.started" ? "started" : type === "item.completed" ? "completed" : "updated"));
+    const failed = status === "failed" || status === "error" || status === "cancelled" || Boolean(item.error);
+    const completed = failed || type === "item.completed" || status === "completed" || status === "succeeded" || status === "success";
+    const started = type === "item.started" || status === "started" || status === "running" || status === "in_progress";
+    const data = safeProviderMcpData(item, serverName ?? "unknown", toolName, status);
+    const label = `${serverName ?? "unknown"}.${toolName}`;
+    if (failed) {
+        const summary = mcpErrorSummary(item) ?? "MCP tool call failed.";
+        const events = [{
+                role: "tool",
+                kind: "error",
+                content: `MCP tool call failed: ${label} - ${summary}`,
+                eventType: "provider_mcp_call_failed",
+                data
+            }];
+        if (isForgeCompletionTool(toolName)) {
+            events.push({
+                role: "tool",
+                kind: "error",
+                content: `Forge completion tool validation failed: ${label} - ${summary}`,
+                eventType: "completion_tool_validation_failed",
+                data
+            });
+        }
+        return events;
+    }
+    if (completed) {
+        return [{
+                role: "tool",
+                kind: "checkpoint",
+                content: `MCP tool call completed: ${label}.`,
+                eventType: "provider_mcp_call_completed",
+                data
+            }];
+    }
+    if (started) {
+        return [{
+                role: "tool",
+                kind: "checkpoint",
+                content: `MCP tool call started: ${label}.`,
+                eventType: "provider_mcp_call_started",
+                data
+            }];
+    }
+    return [];
+}
+function mcpServerName(item) {
+    return stringField(item, "server")
+        ?? stringField(item, "server_name")
+        ?? stringField(item, "mcp_server")
+        ?? stringField(objectField(item, "mcp"), "server")
+        ?? stringField(objectField(item, "mcp"), "server_name");
+}
+function mcpToolName(item) {
+    return stringField(item, "tool")
+        ?? stringField(item, "tool_name")
+        ?? stringField(item, "name")
+        ?? stringField(objectField(item, "function"), "name")
+        ?? stringField(objectField(item, "mcp"), "tool")
+        ?? stringField(objectField(item, "mcp"), "tool_name");
+}
+function mcpErrorSummary(item) {
+    const direct = stringField(item, "error")
+        ?? stringField(item, "error_message")
+        ?? stringField(item, "message");
+    if (direct) {
+        return clip(direct, 600);
+    }
+    const error = objectField(item, "error");
+    return stringField(error, "message")
+        ?? stringField(error, "summary")
+        ?? stringField(objectField(item, "result"), "error")
+        ?? null;
+}
+function safeProviderMcpData(item, serverName, toolName, status) {
+    const elapsedMs = numericField(item, "elapsed_ms") ?? numericField(item, "duration_ms");
+    return JSON.stringify(stripUndefined({
+        server_name: serverName,
+        tool_name: toolName,
+        status,
+        elapsed_ms: elapsedMs,
+        error_summary: mcpErrorSummary(item)
+    }));
+}
+function isForgeCompletionTool(toolName) {
+    const normalized = toolName.trim().toLowerCase();
+    return normalized.startsWith("forge.complete_")
+        || normalized.startsWith("complete_")
+        || normalized.includes("forge.complete_")
+        || normalized.includes("complete_architect_plan");
+}
+export function objectField(source, key) {
+    const value = source[key];
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+export function stringField(source, key) {
+    const value = source[key];
+    return typeof value === "string" && value.trim().length > 0 ? value : null;
+}
+export function numericField(source, key) {
+    const value = source[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+export function stripUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}
+export function normalizedString(value) {
+    return value.trim().toLowerCase().replace(/-/g, "_");
+}
+export function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}

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

@@ -19,6 +19,7 @@ export interface RunOnceDispatchPacket {
     readonly architectDependencies?: DispatchArchitectDependencyContext | null;
     readonly storyDevelop?: DispatchStoryDevelopContext | null;
     readonly storyQa?: DispatchStoryQaContext | null;
+    readonly designerRefs?: DispatchDesignerRefHandoffContext | null;
     readonly draft?: DispatchDraftPrompt | null;
 }
 export interface DispatchDraftPrompt {
@@ -142,6 +143,42 @@ export interface DispatchStoryQaDependencyContext {
     readonly fromWorkItemId: string;
     readonly toWorkItemId: string;
 }
+export interface DispatchDesignerRefHandoffContext {
+    readonly schemaVersion: number;
+    readonly kind: string;
+    readonly ownerType: string;
+    readonly ownerId: string;
+    readonly projectId: string;
+    readonly repoId: string;
+    readonly title: string;
+    readonly refs: readonly DispatchDesignerRefAttachment[];
+}
+export interface DispatchDesignerRefAttachment {
+    readonly ref: DispatchDesignerRef;
+    readonly reason: string;
+    readonly required: boolean;
+    readonly source: string;
+    readonly lineageKind: string;
+    readonly inheritedFromItemType?: string | null;
+    readonly inheritedFromItemId?: string | null;
+    readonly inheritedFromDesignerRefId?: string | null;
+    readonly addedByLane: string;
+    readonly sortOrder: number;
+    readonly createdAt: string;
+}
+export interface DispatchDesignerRef {
+    readonly id: string;
+    readonly projectId: string;
+    readonly repoId: string;
+    readonly refKey: string;
+    readonly kind: string;
+    readonly path: string;
+    readonly anchor?: string | null;
+    readonly title: string;
+    readonly contentHash: string;
+    readonly commitSha: string;
+    readonly createdAt: string;
+}
 export interface DispatchPullRequestContext {
     readonly number: number;
     readonly provider: string;

package/dist/session/session.types.js

@@ -26,6 +26,7 @@ export function parseRunOnceDispatchPacket(value) {
         architectDependencies: parseArchitectDependencies(packet.architectDependencies),
         storyDevelop: parseStoryDevelop(packet.storyDevelop),
         storyQa: parseStoryQa(packet.storyQa),
+        designerRefs: parseDesignerRefs(packet.designerRefs ?? packet.designer_refs),
         draft: parseDraftPrompt(packet.draft)
     };
 }
@@ -416,6 +417,58 @@ function parseStoryQaDependencies(value) {
         };
     });
 }
+function parseDesignerRefs(value) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    const context = asObject(value, "designerRefs");
+    const refs = context.refs;
+    if (!Array.isArray(refs)) {
+        throw new Error("designerRefs.refs must be an array.");
+    }
+    return {
+        schemaVersion: requiredNumber(context, "schemaVersion"),
+        kind: requiredString(context, "kind"),
+        ownerType: requiredString(context, "ownerType"),
+        ownerId: requiredString(context, "ownerId"),
+        projectId: requiredString(context, "projectId"),
+        repoId: requiredString(context, "repoId"),
+        title: requiredString(context, "title"),
+        refs: refs.map((entry, index) => parseDesignerRefAttachment(entry, index))
+    };
+}
+function parseDesignerRefAttachment(value, index) {
+    const attachment = asObject(value, `designerRefs.refs[${index}]`);
+    return {
+        ref: parseDesignerRef(attachment.ref, index),
+        reason: optionalString(attachment, "reason") ?? "",
+        required: requiredBoolean(attachment, "required"),
+        source: optionalString(attachment, "source") ?? "",
+        lineageKind: optionalString(attachment, "lineageKind") ?? optionalString(attachment, "lineage_kind") ?? "",
+        inheritedFromItemType: optionalString(attachment, "inheritedFromItemType") ?? optionalString(attachment, "inherited_from_item_type"),
+        inheritedFromItemId: optionalString(attachment, "inheritedFromItemId") ?? optionalString(attachment, "inherited_from_item_id"),
+        inheritedFromDesignerRefId: optionalString(attachment, "inheritedFromDesignerRefId") ?? optionalString(attachment, "inherited_from_designer_ref_id"),
+        addedByLane: optionalString(attachment, "addedByLane") ?? optionalString(attachment, "added_by_lane") ?? "",
+        sortOrder: requiredNumber(attachment, "sortOrder"),
+        createdAt: requiredString(attachment, "createdAt")
+    };
+}
+function parseDesignerRef(value, index) {
+    const designerRef = asObject(value, `designerRefs.refs[${index}].ref`);
+    return {
+        id: requiredString(designerRef, "id"),
+        projectId: requiredString(designerRef, "projectId"),
+        repoId: requiredString(designerRef, "repoId"),
+        refKey: requiredString(designerRef, "refKey"),
+        kind: requiredString(designerRef, "kind"),
+        path: requiredString(designerRef, "path"),
+        anchor: optionalString(designerRef, "anchor"),
+        title: optionalString(designerRef, "title") ?? "",
+        contentHash: requiredString(designerRef, "contentHash"),
+        commitSha: requiredString(designerRef, "commitSha"),
+        createdAt: requiredString(designerRef, "createdAt")
+    };
+}
 function parseStringArray(value, label) {
     if (!Array.isArray(value)) {
         throw new Error(`${label} must be an array.`);

package/dist/shared/process/windows-launch.d.ts

@@ -0,0 +1,8 @@
+export interface LaunchCommand {
+    readonly command: string;
+    readonly args: readonly string[];
+}
+export declare function buildWindowsCmdLaunch(command: string, args: readonly string[]): LaunchCommand;
+export declare function buildWindowsLaunchCommand(commandPath: string, args: readonly string[]): LaunchCommand;
+export declare function windowsCommandLine(command: string, args: readonly string[]): string;
+export declare function quoteWindowsCommandLineArg(value: string): string;

package/dist/shared/process/windows-launch.js

@@ -0,0 +1,38 @@
+import path from "node:path";
+export function buildWindowsCmdLaunch(command, args) {
+    return {
+        command: process.env.ComSpec ?? "cmd.exe",
+        args: ["/d", "/s", "/v:off", "/c", `"${windowsCommandLine(command, args)}"`]
+    };
+}
+export function buildWindowsLaunchCommand(commandPath, args) {
+    const extension = path.extname(commandPath).toLowerCase();
+    if (extension === ".ps1") {
+        return {
+            command: powershellExecutable(),
+            args: ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", commandPath, ...args]
+        };
+    }
+    if (extension === ".cmd" || extension === ".bat") {
+        return buildWindowsCmdLaunch(commandPath, args);
+    }
+    return { command: commandPath, args };
+}
+export function windowsCommandLine(command, args) {
+    return [command, ...args].map(quoteWindowsCommandLineArg).join(" ");
+}
+export function quoteWindowsCommandLineArg(value) {
+    const escaped = value
+        .replace(/\^/g, "^^")
+        .replace(/%/g, "^%");
+    if (escaped.length > 0 && !/[\s"&|<>()^%!]/.test(escaped)) {
+        return escaped;
+    }
+    return `"${escaped.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/g, "$1$1")}"`;
+}
+function powershellExecutable() {
+    const systemRoot = process.env.SystemRoot;
+    return systemRoot
+        ? path.join(systemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe")
+        : "powershell.exe";
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const forgeBridgeVersion = "0.1.3-dev.bd0c67bbf352";
+export declare const forgeBridgeVersion = "0.1.3-dev.d1ca67076aa9";

package/dist/version.js

@@ -1 +1 @@
-export const forgeBridgeVersion = "0.1.3-dev.bd0c67bbf352";
+export const forgeBridgeVersion = "0.1.3-dev.d1ca67076aa9";

package/package.json

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