@loucompanion/forge-bridge 0.1.1-dev.8dcbc6245e51 → 0.1.1-dev.ac486debe210

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

@@ -3,10 +3,12 @@ import type { WorktreeHandle } from "../../worktree/worktree.types.js";
 export interface ProviderCliRunContext {
     readonly dispatch: RunOnceDispatchPacket;
     readonly worktree: WorktreeHandle;
+    readonly signal?: AbortSignal;
     emit(event: RunnerDispatchEvent): Promise<void>;
 }
 export interface ProviderCliRunResult {
     readonly summary: string;
     readonly spec?: RunnerDispatchSpec | null;
     readonly artifact?: RunnerDispatchArtifact | null;
+    readonly artifacts?: readonly RunnerDispatchArtifact[] | null;
 }

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.service.js

@@ -1,10 +1,10 @@
 import { redactSecrets } from "../shared/redaction/redaction.js";
-import { DeterministicProviderCliService } from "./provider-cli/provider-cli.service.js";
+import { RoutingProviderCliService } from "./provider-cli/provider-cli.service.js";
 import { GitWorktreeService } from "../worktree/worktree.service.js";
 export class BridgeSessionService {
     worktrees;
     providerCli;
-    constructor(worktrees = new GitWorktreeService(), providerCli = new DeterministicProviderCliService()) {
+    constructor(worktrees = new GitWorktreeService(), providerCli = new RoutingProviderCliService()) {
         this.worktrees = worktrees;
         this.providerCli = providerCli;
     }
@@ -46,21 +46,30 @@ export class BridgeSessionService {
         }
         try {
             throwIfAborted(signal);
-            const isQa = dispatch.execution.role.toLowerCase() === "qa" || dispatch.execution.lane.toLowerCase() === "qa";
+            const lane = dispatch.execution.lane.toLowerCase();
+            const role = dispatch.execution.role.toLowerCase();
+            const isQa = role === "qa" || lane === "qa";
+            const isConflictResolve = role === "conflict_resolve" || lane === "conflict_resolve";
+            const context = {
+                dispatch,
+                worktree,
+                emit,
+                signal
+            };
             const run = isQa
-                ? await this.providerCli.runQa(dispatch, emit)
-                : await this.providerCli.runImplementation({
-                    dispatch,
-                    worktree,
-                    emit
-                });
+                ? await this.providerCli.runQa(context)
+                : isConflictResolve
+                    ? await this.providerCli.runConflictResolve(context)
+                    : await this.providerCli.runImplementation(context);
+            const phaseArtifacts = run.artifacts?.length ? run.artifacts : run.artifact ? [run.artifact] : [];
             return redactSecrets({
                 schemaVersion: 1,
                 exitCode: 0,
                 summary: run.summary,
                 events,
                 spec: run.spec ?? null,
-                artifact: run.artifact ?? null
+                artifact: run.artifact ?? null,
+                artifacts: phaseArtifacts
             }, redactionSecrets);
         }
         finally {

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

@@ -18,6 +18,7 @@ export interface DispatchResolvedArtifact {
     readonly scope: string;
     readonly body: string;
     readonly contentHash: string;
+    readonly version: number;
     readonly lane?: string | null;
     readonly event?: string | null;
 }
@@ -86,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;
@@ -101,6 +106,7 @@ export interface RunnerDispatchArtifact {
     readonly report: string;
     readonly producedBy: string;
     readonly status: string;
+    readonly phase?: string | null;
 }
 export interface RunOnceResultPacket {
     readonly schemaVersion: 1;
@@ -109,6 +115,7 @@ export interface RunOnceResultPacket {
     readonly events: readonly RunnerDispatchEvent[];
     readonly spec?: RunnerDispatchSpec | null;
     readonly artifact?: RunnerDispatchArtifact | null;
+    readonly artifacts?: readonly RunnerDispatchArtifact[] | null;
 }
 export interface RunnerEventLine {
     readonly type: "runner_event";

package/dist/session/session.types.js

@@ -153,6 +153,7 @@ function parseArtifacts(value) {
             scope: requiredString(artifact, "scope"),
             body: optionalString(artifact, "body") ?? "",
             contentHash: requiredString(artifact, "contentHash"),
+            version: optionalPositiveInteger(artifact, "version") ?? 1,
             lane: optionalString(artifact, "lane"),
             event: optionalString(artifact, "event")
         };
@@ -188,6 +189,16 @@ function requiredBoolean(source, key) {
     }
     return value;
 }
+function optionalPositiveInteger(source, key) {
+    const value = source[key];
+    if (value === undefined || value === null) {
+        return null;
+    }
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+        throw new Error(`${key} must be a positive integer when provided.`);
+    }
+    return value;
+}
 function requiredNumber(source, key) {
     const value = source[key];
     if (typeof value !== "number" || !Number.isFinite(value)) {

package/dist/shared/cursor-agent/cursor-agent.launch.d.ts

@@ -0,0 +1,9 @@
+export interface CursorAgentLaunch {
+    readonly command: string;
+    readonly args: readonly string[];
+}
+export declare function isCursorAgentCommand(command: string): boolean;
+export declare function resolveCursorAgentDirectLaunch(command: string, args: readonly string[]): Promise<CursorAgentLaunch | null>;
+export declare function findLatestCursorAgentVersionDir(versionsRoot: string): Promise<string | null>;
+export declare function compareCursorAgentVersionDirNames(left: string, right: string): number;
+export declare function parseCursorAgentVersionSortKey(name: string): number;

package/dist/shared/cursor-agent/cursor-agent.launch.js

@@ -0,0 +1,66 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+const cursorAgentVersionDirPattern = /^\d{4}\.\d{1,2}\.\d{1,2}-.+/;
+export function isCursorAgentCommand(command) {
+    const normalized = command.trim().toLowerCase();
+    return normalized === "cursor-agent" || normalized === "agent";
+}
+export async function resolveCursorAgentDirectLaunch(command, args) {
+    if (!isCursorAgentCommand(command)) {
+        return null;
+    }
+    const localAppData = process.env.LOCALAPPDATA;
+    if (!localAppData) {
+        return null;
+    }
+    const versionDir = await findLatestCursorAgentVersionDir(path.join(localAppData, "cursor-agent", "versions"));
+    if (!versionDir) {
+        return null;
+    }
+    const nodePath = path.join(versionDir, "node.exe");
+    const indexPath = path.join(versionDir, "index.js");
+    if (!(await fileExists(nodePath)) || !(await fileExists(indexPath))) {
+        return null;
+    }
+    return {
+        command: nodePath,
+        args: [indexPath, ...args]
+    };
+}
+export async function findLatestCursorAgentVersionDir(versionsRoot) {
+    let entries;
+    try {
+        entries = await fs.readdir(versionsRoot);
+    }
+    catch {
+        return null;
+    }
+    const latestName = entries
+        .filter((name) => cursorAgentVersionDirPattern.test(name))
+        .sort(compareCursorAgentVersionDirNames)
+        .at(-1);
+    return latestName ? path.join(versionsRoot, latestName) : null;
+}
+export function compareCursorAgentVersionDirNames(left, right) {
+    const leftKey = parseCursorAgentVersionSortKey(left);
+    const rightKey = parseCursorAgentVersionSortKey(right);
+    if (leftKey !== rightKey) {
+        return leftKey - rightKey;
+    }
+    return left.localeCompare(right);
+}
+export function parseCursorAgentVersionSortKey(name) {
+    const datePart = name.split("-")[0] ?? "";
+    const parts = datePart.split(".");
+    if (parts.length !== 3) {
+        return 0;
+    }
+    const year = parts[0] ?? "";
+    const month = (parts[1] ?? "").padStart(2, "0");
+    const day = (parts[2] ?? "").padStart(2, "0");
+    const numeric = Number(`${year}${month}${day}`);
+    return Number.isFinite(numeric) ? numeric : 0;
+}
+async function fileExists(inputPath) {
+    return fs.stat(inputPath).then((stat) => stat.isFile()).catch(() => false);
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const forgeBridgeVersion = "0.1.1-dev.8dcbc6245e51";
+export declare const forgeBridgeVersion = "0.1.1-dev.ac486debe210";

package/dist/version.js

@@ -1 +1 @@
-export const forgeBridgeVersion = "0.1.1-dev.8dcbc6245e51";
+export const forgeBridgeVersion = "0.1.1-dev.ac486debe210";

package/dist/worktree/artifact-injector.d.ts

@@ -8,4 +8,4 @@ export declare function buildSpecBody(laneCommand: DispatchResolvedArtifact, wor
     readonly title: string;
     readonly description: string;
     readonly acceptanceCriteria: string;
-}): string;
+}, phase?: string): string;

package/dist/worktree/artifact-injector.js

@@ -15,11 +15,13 @@ export async function writeArtifact(worktreePath, artifact) {
     const scope = safeArtifactSegment("scope", artifact.scope);
     const slug = safeArtifactSegment("slug", artifact.slug);
     const forgeRoot = path.resolve(worktreePath, ".forge");
-    const targetDir = path.resolve(forgeRoot, kindFolder, scope);
-    assertInside(forgeRoot, targetDir, "Artifact directory");
-    await fs.mkdir(targetDir, { recursive: true });
-    const filePath = path.resolve(targetDir, `${slug}.md`);
+    const scopeDir = path.resolve(forgeRoot, kindFolder, scope);
+    assertInside(forgeRoot, scopeDir, "Artifact directory");
+    const filePath = normalizedArtifactKind(artifact.kind) === "skill"
+        ? path.resolve(scopeDir, slug, "SKILL.md")
+        : path.resolve(scopeDir, `${slug}.md`);
     assertInside(forgeRoot, filePath, "Artifact file");
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
     await fs.writeFile(filePath, artifact.body, "utf8");
 }
 export function selectLaneCommand(artifacts, lane, phase) {
@@ -27,10 +29,7 @@ export function selectLaneCommand(artifacts, lane, phase) {
     return artifacts.find((artifact) => normalizedArtifactKind(artifact.kind) === "command" && artifact.slug.trim().toLowerCase() === slug);
 }
 export function resolveCommandSlug(lane, phase) {
-    const normalizedPhase = phase.trim().toLowerCase();
-    if (normalizedPhase === "self_review") {
-        return "self-review-prompt";
-    }
+    const normalizedPhase = phase.trim().toLowerCase().replace(/-/g, "_");
     if (normalizedPhase === "rework") {
         return "rework-prompt";
     }
@@ -43,12 +42,13 @@ export function resolveCommandSlug(lane, phase) {
             return "dev-prompt";
     }
 }
-export function buildSpecBody(laneCommand, workItem) {
+export function buildSpecBody(laneCommand, workItem, phase = "implementation") {
     const prompt = laneCommand.body.replaceAll("{workItemId}", workItem.id);
     return `---
 work_item_id: ${workItem.id}
 status: approved
 lane: ${laneCommand.lane ?? "develop"}
+phase: ${phase}
 command_slug: ${laneCommand.slug}
 ---
 

package/dist/worktree/worktree.service.d.ts

@@ -7,6 +7,8 @@ export declare class GitWorktreeService implements WorktreeService {
     prepare(request: WorktreePrepareRequest): Promise<WorktreeHandle>;
     release(handle: WorktreeHandle): Promise<void>;
     private resolveRepoPath;
+    private findExistingRepoPath;
+    private resolveMatchingRepo;
     private ensureBaseBranch;
     private gitRefExists;
     private ensureGitIdentity;

package/dist/worktree/worktree.service.js

@@ -18,7 +18,7 @@ export class GitWorktreeService {
         const shortId = request.workItem.id.replace(/-/g, "").slice(0, 12);
         const kind = safeSegment(request.workItem.kind, "work-item");
         const branchName = normalizeBranchName(`${kind}/${shortId}`, "work-item/unknown");
-        const worktreeRoot = path.join(path.dirname(repoPath), ".forge-worktrees", path.basename(repoPath));
+        const worktreeRoot = resolveWorktreeRoot(allowedRoot, repoPath);
         const worktreePath = path.join(worktreeRoot, kind, shortId);
         const resolvedWorktreeParent = await ensureDirectory(path.dirname(worktreePath));
         if (!isSubPath(allowedRoot, resolvedWorktreeParent)) {
@@ -78,7 +78,11 @@ export class GitWorktreeService {
         if (!repo.cloneOnDemand) {
             throw new Error("Repo has no server-local path and cloneOnDemand is disabled.");
         }
-        const repoPath = path.join(allowedRoot, `${safeSegment(repo.name, "repo")}-${repo.id.replace(/-/g, "")}`);
+        const discovered = await this.findExistingRepoPath(repo, allowedRoot);
+        if (discovered) {
+            return discovered;
+        }
+        const repoPath = path.join(managedRepoRoot(allowedRoot), `${safeSegment(repo.name, "repo")}-${repo.id.replace(/-/g, "")}`);
         if (!(await gitMetadataExists(repoPath, allowedRoot))) {
             const repoPathExists = await pathExists(repoPath);
             if (repoPathExists) {
@@ -109,6 +113,46 @@ export class GitWorktreeService {
         }
         return resolved;
     }
+    async findExistingRepoPath(repo, allowedRoot) {
+        const expectedRemote = normalizeRemote(repo.remoteUrl);
+        const rawName = repo.name.trim();
+        const nameCandidates = uniqueStrings([
+            isSinglePathSegment(rawName) ? path.join(allowedRoot, rawName) : "",
+            path.join(allowedRoot, safeSegment(repo.name, "repo"))
+        ]);
+        for (const candidate of nameCandidates) {
+            const resolved = await this.resolveMatchingRepo(candidate, allowedRoot, expectedRemote);
+            if (resolved) {
+                return resolved;
+            }
+        }
+        if (expectedRemote.length > 0) {
+            const entries = await fs.readdir(allowedRoot, { withFileTypes: true }).catch(() => []);
+            for (const entry of entries) {
+                if (!entry.isDirectory() || entry.name === ".forge-worktrees") {
+                    continue;
+                }
+                const resolved = await this.resolveMatchingRepo(path.join(allowedRoot, entry.name), allowedRoot, expectedRemote);
+                if (resolved) {
+                    return resolved;
+                }
+            }
+        }
+        return null;
+    }
+    async resolveMatchingRepo(candidate, allowedRoot, expectedRemote) {
+        if (!(await gitMetadataExists(candidate, allowedRoot))) {
+            return null;
+        }
+        if (expectedRemote.length > 0) {
+            const origin = await this.git.run(candidate, ["remote", "get-url", "origin"]).catch(() => "");
+            if (normalizeRemote(origin) !== expectedRemote) {
+                return null;
+            }
+        }
+        const resolved = await resolveExistingDirectoryPath(candidate);
+        return isSubPath(allowedRoot, resolved) ? resolved : null;
+    }
     async ensureBaseBranch(repoPath, baseBranch) {
         if (await this.gitRefExists(repoPath, `refs/heads/${baseBranch}`)) {
             return;
@@ -132,6 +176,15 @@ export class GitWorktreeService {
         await this.git.run(repoPath, ["config", "user.name", "Forge Bridge"]);
     }
 }
+function managedRepoRoot(allowedRoot) {
+    return path.join(allowedRoot, ".forge-worktrees", "_repos");
+}
+function resolveWorktreeRoot(allowedRoot, repoPath) {
+    const baseName = path.basename(repoPath);
+    return isSubPath(managedRepoRoot(allowedRoot), repoPath)
+        ? path.join(allowedRoot, ".forge-worktrees", baseName)
+        : path.join(path.dirname(repoPath), ".forge-worktrees", baseName);
+}
 function isCloneableRemote(remoteUrl) {
     const trimmed = remoteUrl?.trim() ?? "";
     if (trimmed.length === 0 || trimmed.startsWith("local://")) {
@@ -194,3 +247,55 @@ async function directoryExists(inputPath) {
     const stat = await fs.stat(inputPath).catch(() => null);
     return stat?.isDirectory() ?? false;
 }
+function uniqueStrings(values) {
+    const seen = new Set();
+    const result = [];
+    for (const value of values) {
+        if (!value || seen.has(value)) {
+            continue;
+        }
+        seen.add(value);
+        result.push(value);
+    }
+    return result;
+}
+function isSinglePathSegment(value) {
+    return value.length > 0 && value !== "." && value !== ".." && !value.includes("/") && !value.includes("\\");
+}
+function normalizeRemote(remoteUrl) {
+    const trimmed = remoteUrl?.trim() ?? "";
+    if (trimmed.length === 0) {
+        return "";
+    }
+    const gitHubSsh = /^git@github\.com:(.+)$/i.exec(trimmed);
+    if (gitHubSsh) {
+        return stripGitSuffix(`https://github.com/${gitHubSsh[1]}`).toLowerCase();
+    }
+    if (path.isAbsolute(trimmed)) {
+        return normalizeLocalPath(trimmed);
+    }
+    try {
+        const url = new URL(trimmed);
+        if (url.protocol === "file:") {
+            return normalizeLocalPath(normalizeFileUrlPath(url));
+        }
+        url.username = "";
+        url.password = "";
+        url.hash = "";
+        return stripGitSuffix(url.toString().replace(/\/$/, "")).toLowerCase();
+    }
+    catch {
+        return stripGitSuffix(trimmed.replace(/\\/g, "/")).toLowerCase();
+    }
+}
+function stripGitSuffix(value) {
+    return value.replace(/\.git$/i, "").replace(/\/$/, "");
+}
+function normalizeFileUrlPath(url) {
+    const pathname = decodeURIComponent(url.pathname);
+    return /^\/[A-Za-z]:[\\/]/.test(pathname) ? pathname.slice(1) : pathname;
+}
+function normalizeLocalPath(value) {
+    const normalized = path.resolve(value).replace(/\\/g, "/");
+    return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}

package/package.json

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