@loucompanion/forge-bridge 0.1.1-dev.7d43998c4521 → 0.1.1-dev.895607f4402a

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/qa-sidecar-validation.d.ts

@@ -0,0 +1,3 @@
+export declare function isPathUnderRoot(root: string, target: string): boolean;
+export declare function ensureNoSymbolicLinkPathSegments(root: string, targetDirectory: string, errorMessage: string): Promise<void>;
+export declare function sha256File(filePath: string): Promise<string>;

package/dist/session/qa-sidecar-validation.js

@@ -0,0 +1,44 @@
+import crypto from "node:crypto";
+import { createReadStream } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+export function isPathUnderRoot(root, target) {
+    const relative = path.relative(path.resolve(root), path.resolve(target));
+    return Boolean(relative)
+        && relative !== ".."
+        && !relative.startsWith(`..${path.sep}`)
+        && !path.isAbsolute(relative);
+}
+export async function ensureNoSymbolicLinkPathSegments(root, targetDirectory, errorMessage) {
+    const resolvedRoot = path.resolve(root);
+    const resolvedTargetDirectory = path.resolve(targetDirectory);
+    const relative = path.relative(resolvedRoot, resolvedTargetDirectory);
+    if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new Error(errorMessage);
+    }
+    let current = resolvedRoot;
+    const rootStat = await fs.lstat(current);
+    if (rootStat.isSymbolicLink()) {
+        throw new Error(errorMessage);
+    }
+    if (!relative) {
+        return;
+    }
+    for (const segment of relative.split(path.sep)) {
+        if (!segment) {
+            continue;
+        }
+        current = path.join(current, segment);
+        const stat = await fs.lstat(current);
+        if (stat.isSymbolicLink()) {
+            throw new Error(errorMessage);
+        }
+    }
+}
+export async function sha256File(filePath) {
+    const hash = crypto.createHash("sha256");
+    for await (const chunk of createReadStream(filePath)) {
+        hash.update(chunk);
+    }
+    return hash.digest("hex");
+}

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;
     }
@@ -13,7 +13,9 @@ export class BridgeSessionService {
         const redactionSecrets = exactSecrets(dispatch);
         const events = [];
         const emit = async (event) => {
-            throwIfAborted(signal);
+            if (signal?.aborted) {
+                return;
+            }
             const redacted = redactSecrets(event, redactionSecrets);
             events.push(redacted);
             await sink.emit(redacted);
@@ -29,8 +31,12 @@ export class BridgeSessionService {
             repo: dispatch.repo,
             workItem: dispatch.workItem,
             baseBranch: dispatch.cycleRun.baseBranch || dispatch.cycleRun.requestedBase,
+            lane: dispatch.execution.lane,
+            phase: dispatch.cycleRun.phase,
             allowedRepoRoot: dispatch.serverLocal.repoRoot,
-            cleanupWorktrees: dispatch.serverLocal.cleanupWorktrees
+            cleanupWorktrees: dispatch.serverLocal.cleanupWorktrees,
+            artifacts: dispatch.artifacts,
+            warmPathOverrides: dispatch.warmPathOverrides
         });
         throwIfAborted(signal);
         await emit({
@@ -39,23 +45,36 @@ export class BridgeSessionService {
             content: `Prepared worktree ${worktree.branchName}.`,
             eventType: "worktree_prepared"
         });
+        if (worktree.dependencyWarm) {
+            await emitDependencyWarmEvents(worktree.dependencyWarm, emit);
+        }
         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);
+            throwIfAborted(signal);
+            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 {
@@ -90,3 +109,29 @@ function validateApiKeySecretGrant(dispatch) {
 function exactSecrets(dispatch) {
     return dispatch.apiKeySecretGrant?.secret ? [dispatch.apiKeySecretGrant.secret] : [];
 }
+async function emitDependencyWarmEvents(warm, emit) {
+    if (warm.linked.length > 0) {
+        await emit({
+            role: "runner",
+            kind: "checkpoint",
+            content: `Warmed dependencies via link: ${warm.linked.join(", ")}.`,
+            eventType: "dependencies_warmed"
+        });
+    }
+    for (const fallback of warm.fallbacks) {
+        await emit({
+            role: "runner",
+            kind: "checkpoint",
+            content: `Dependency install fallback (${fallback.ecosystem}): ${fallback.reason} Ran \`${fallback.command}\` in ${fallback.packageRoot}.`,
+            eventType: "dependencies_install_fallback"
+        });
+    }
+    if (warm.skipped.length > 0) {
+        await emit({
+            role: "runner",
+            kind: "checkpoint",
+            content: `Skipped warming missing dependency paths: ${warm.skipped.join(", ")}.`,
+            eventType: "dependencies_warm_skipped"
+        });
+    }
+}

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

@@ -8,7 +8,60 @@ export interface RunOnceDispatchPacket {
     readonly lease: DispatchLease;
     readonly execution: DispatchExecution;
     readonly serverLocal: DispatchServerLocalConfig;
+    readonly pullRequest?: DispatchPullRequestContext | null;
     readonly apiKeySecretGrant?: ApiKeySecretGrant | null;
+    readonly artifacts: readonly DispatchResolvedArtifact[];
+    readonly warmPathOverrides?: readonly string[];
+    readonly qaBrowser?: DispatchQaBrowserContext | null;
+    readonly qaRework?: DispatchQaReworkContext | null;
+}
+export interface DispatchQaBrowserContext {
+    readonly required: boolean;
+    readonly launchTarget?: DispatchQaAppLaunchTarget | null;
+    readonly artifactsPath: string;
+    readonly missingTargetReason?: string | null;
+}
+export interface DispatchQaAppLaunchTarget {
+    readonly url?: string | null;
+    readonly command?: string | null;
+    readonly working_directory?: string | null;
+    readonly ready_url?: string | null;
+    readonly routes: readonly string[];
+    readonly notes?: string | null;
+}
+export interface DispatchQaReworkContext {
+    readonly attempt: number;
+    readonly maxAttempts: number;
+    readonly packetPath: string;
+    readonly packetJson: string;
+    readonly findingIds: readonly string[];
+    readonly findings: readonly Record<string, unknown>[];
+}
+export interface DispatchPullRequestContext {
+    readonly number: number;
+    readonly provider: string;
+    readonly title: string;
+    readonly sourceBranch: string;
+    readonly targetBranch: string;
+    readonly url: string;
+    readonly state: string;
+    readonly checkState: string;
+    readonly mergeState: string;
+    readonly requiredChecksPassed: number;
+    readonly requiredChecksTotal: number;
+    readonly unresolvedThreads: number;
+    readonly humanApproved: boolean;
+    readonly hasMergeConflicts: boolean;
+}
+export interface DispatchResolvedArtifact {
+    readonly kind: string;
+    readonly slug: string;
+    readonly scope: string;
+    readonly body: string;
+    readonly contentHash: string;
+    readonly version: number;
+    readonly lane?: string | null;
+    readonly event?: string | null;
 }
 export interface DispatchWorkItem {
     readonly id: string;
@@ -29,6 +82,9 @@ export interface DispatchRepo {
 }
 export interface DispatchCycleRun {
     readonly id: string;
+    readonly ownerType?: string | null;
+    readonly ownerId?: string | null;
+    readonly workItemId?: string | null;
     readonly kind: string;
     readonly phase: string;
     readonly requestedBase: string;
@@ -44,6 +100,9 @@ export interface DispatchSession {
 }
 export interface DispatchLease {
     readonly id: string;
+    readonly ownerType?: string | null;
+    readonly ownerId?: string | null;
+    readonly workItemId?: string | null;
     readonly worktreeKey: string;
     readonly lane: string;
     readonly fencingToken: string;
@@ -59,6 +118,7 @@ export interface DispatchExecution {
     readonly role: string;
     readonly lane: string;
     readonly requiresApiKeySecretGrant: boolean;
+    readonly runnerRepoLocalPath?: string | null;
 }
 export interface ApiKeySecretGrant {
     readonly grantId: string;
@@ -75,6 +135,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;
@@ -90,6 +154,7 @@ export interface RunnerDispatchArtifact {
     readonly report: string;
     readonly producedBy: string;
     readonly status: string;
+    readonly phase?: string | null;
 }
 export interface RunOnceResultPacket {
     readonly schemaVersion: 1;
@@ -98,6 +163,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

@@ -1,3 +1,4 @@
+import path from "node:path";
 export function parseRunOnceDispatchPacket(value) {
     const packet = asObject(value, "dispatch packet");
     const schemaVersion = requiredNumber(packet, "schemaVersion");
@@ -14,7 +15,12 @@ export function parseRunOnceDispatchPacket(value) {
         lease: parseLease(packet.lease),
         execution: parseExecution(packet.execution),
         serverLocal: parseServerLocal(packet.serverLocal),
-        apiKeySecretGrant: parseApiKeySecretGrant(packet.apiKeySecretGrant)
+        pullRequest: parsePullRequest(packet.pullRequest),
+        apiKeySecretGrant: parseApiKeySecretGrant(packet.apiKeySecretGrant),
+        artifacts: parseArtifacts(packet.artifacts),
+        warmPathOverrides: parseWarmPathOverrides(packet.warmPathOverrides),
+        qaBrowser: parseQaBrowser(packet.qaBrowser),
+        qaRework: parseQaRework(packet.qaRework)
     };
 }
 export function failureResult(summary, events = []) {
@@ -52,6 +58,9 @@ function parseCycleRun(value) {
     const cycle = asObject(value, "cycleRun");
     return {
         id: requiredString(cycle, "id"),
+        ownerType: optionalString(cycle, "ownerType"),
+        ownerId: optionalString(cycle, "ownerId"),
+        workItemId: optionalString(cycle, "workItemId"),
         kind: requiredString(cycle, "kind"),
         phase: requiredString(cycle, "phase"),
         requestedBase: optionalString(cycle, "requestedBase") ?? "develop",
@@ -73,6 +82,9 @@ function parseLease(value) {
     const lease = asObject(value, "lease");
     return {
         id: requiredString(lease, "id"),
+        ownerType: optionalString(lease, "ownerType"),
+        ownerId: optionalString(lease, "ownerId"),
+        workItemId: optionalString(lease, "workItemId"),
         worktreeKey: requiredString(lease, "worktreeKey"),
         lane: requiredString(lease, "lane"),
         fencingToken: requiredString(lease, "fencingToken"),
@@ -90,7 +102,8 @@ function parseExecution(value) {
         repoId: requiredString(execution, "repoId"),
         role: requiredString(execution, "role"),
         lane: requiredString(execution, "lane"),
-        requiresApiKeySecretGrant: requiredBoolean(execution, "requiresApiKeySecretGrant")
+        requiresApiKeySecretGrant: requiredBoolean(execution, "requiresApiKeySecretGrant"),
+        runnerRepoLocalPath: optionalString(execution, "runnerRepoLocalPath")
     };
 }
 function parseApiKeySecretGrant(value) {
@@ -112,6 +125,136 @@ function parseServerLocal(value) {
         cleanupWorktrees: requiredBoolean(serverLocal, "cleanupWorktrees")
     };
 }
+function parsePullRequest(value) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    const pullRequest = asObject(value, "pullRequest");
+    return {
+        number: requiredNumber(pullRequest, "number"),
+        provider: requiredString(pullRequest, "provider"),
+        title: optionalString(pullRequest, "title") ?? "",
+        sourceBranch: requiredString(pullRequest, "sourceBranch"),
+        targetBranch: requiredString(pullRequest, "targetBranch"),
+        url: optionalString(pullRequest, "url") ?? "",
+        state: requiredString(pullRequest, "state"),
+        checkState: requiredString(pullRequest, "checkState"),
+        mergeState: requiredString(pullRequest, "mergeState"),
+        requiredChecksPassed: requiredNumber(pullRequest, "requiredChecksPassed"),
+        requiredChecksTotal: requiredNumber(pullRequest, "requiredChecksTotal"),
+        unresolvedThreads: requiredNumber(pullRequest, "unresolvedThreads"),
+        humanApproved: requiredBoolean(pullRequest, "humanApproved"),
+        hasMergeConflicts: requiredBoolean(pullRequest, "hasMergeConflicts")
+    };
+}
+function parseWarmPathOverrides(value) {
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error("warmPathOverrides must be an array when provided.");
+    }
+    return value.map((entry, index) => parseWarmPathOverride(entry, index));
+}
+function parseWarmPathOverride(entry, index) {
+    if (typeof entry !== "string" || entry.trim().length === 0) {
+        throw new Error(`warmPathOverrides[${index}] must be a non-empty string.`);
+    }
+    const trimmed = entry.trim();
+    if (path.isAbsolute(trimmed) || path.posix.isAbsolute(trimmed) || path.win32.isAbsolute(trimmed)) {
+        throw new Error(`warmPathOverrides[${index}] must be a relative path.`);
+    }
+    const segments = trimmed.split(/[\\/]+/).filter(Boolean);
+    if (segments.length === 0 || segments.some((segment) => segment === "." || segment === "..")) {
+        throw new Error(`warmPathOverrides[${index}] must not contain path traversal.`);
+    }
+    return segments.join("/");
+}
+function parseQaBrowser(value) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    const qaBrowser = asObject(value, "qaBrowser");
+    return {
+        required: optionalBoolean(qaBrowser, "required") ?? false,
+        launchTarget: parseQaAppLaunchTarget(qaBrowser.launchTarget ?? qaBrowser.launch_target),
+        artifactsPath: optionalString(qaBrowser, "artifactsPath") ?? optionalString(qaBrowser, "artifacts_path") ?? "",
+        missingTargetReason: optionalString(qaBrowser, "missingTargetReason") ?? optionalString(qaBrowser, "missing_target_reason")
+    };
+}
+function parseQaAppLaunchTarget(value) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    const launchTarget = asObject(value, "qaBrowser.launchTarget");
+    const routes = launchTarget.routes;
+    if (routes !== undefined && routes !== null && !Array.isArray(routes)) {
+        throw new Error("qaBrowser.launchTarget.routes must be an array when provided.");
+    }
+    return {
+        url: optionalString(launchTarget, "url"),
+        command: optionalString(launchTarget, "command"),
+        working_directory: optionalString(launchTarget, "working_directory"),
+        ready_url: optionalString(launchTarget, "ready_url"),
+        routes: Array.isArray(routes)
+            ? routes.map((entry, index) => {
+                if (typeof entry !== "string") {
+                    throw new Error(`qaBrowser.launchTarget.routes[${index}] must be a string.`);
+                }
+                return entry;
+            }).filter((entry) => entry.trim().length > 0)
+            : [],
+        notes: optionalString(launchTarget, "notes")
+    };
+}
+function parseQaRework(value) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    const qaRework = asObject(value, "qaRework");
+    const findingIdsValue = qaRework.findingIds;
+    if (!Array.isArray(findingIdsValue)) {
+        throw new Error("qaRework.findingIds must be an array.");
+    }
+    const findingsValue = qaRework.findings;
+    if (!Array.isArray(findingsValue)) {
+        throw new Error("qaRework.findings must be an array.");
+    }
+    return {
+        attempt: requiredNumber(qaRework, "attempt"),
+        maxAttempts: requiredNumber(qaRework, "maxAttempts"),
+        packetPath: requiredString(qaRework, "packetPath"),
+        packetJson: requiredString(qaRework, "packetJson"),
+        findingIds: findingIdsValue.map((entry, index) => {
+            if (typeof entry !== "string" || entry.trim().length === 0) {
+                throw new Error(`qaRework.findingIds[${index}] must be a non-empty string.`);
+            }
+            return entry;
+        }),
+        findings: findingsValue.map((entry, index) => asObject(entry, `qaRework.findings[${index}]`))
+    };
+}
+function parseArtifacts(value) {
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error("artifacts must be an array when provided.");
+    }
+    return value.map((entry, index) => {
+        const artifact = asObject(entry, `artifacts[${index}]`);
+        return {
+            kind: requiredString(artifact, "kind"),
+            slug: requiredString(artifact, "slug"),
+            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")
+        };
+    });
+}
 function asObject(value, label) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         throw new Error(`${label} must be an object.`);
@@ -142,6 +285,26 @@ function requiredBoolean(source, key) {
     }
     return value;
 }
+function optionalBoolean(source, key) {
+    const value = source[key];
+    if (value === undefined || value === null) {
+        return null;
+    }
+    if (typeof value !== "boolean") {
+        throw new Error(`${key} must be a boolean when provided.`);
+    }
+    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.7d43998c4521";
+export declare const forgeBridgeVersion = "0.1.1-dev.895607f4402a";

package/dist/version.js

@@ -1 +1 @@
-export const forgeBridgeVersion = "0.1.1-dev.7d43998c4521";
+export const forgeBridgeVersion = "0.1.1-dev.895607f4402a";