@loucompanion/forge-bridge 0.1.3-dev.f66395c3ac21 → 0.1.3-dev.fbe15023cdfe

package/dist/cli/local-config.d.ts

@@ -7,6 +7,8 @@ export interface BridgeLocalConfig {
     readonly deviceName?: string;
     readonly defaultRepoRoot?: string;
     readonly cleanupWorktrees?: boolean;
+    readonly dockerEnabled?: boolean;
+    readonly allowOpenPublicSandbox?: boolean;
     readonly cliProviders?: readonly string[];
     readonly providerStatuses?: Readonly<Record<string, BridgeProviderStatus>>;
     readonly projectLabels?: readonly string[];
@@ -17,6 +19,8 @@ export interface BridgeLocalConfig {
     readonly supportsManagedForgeArtifacts?: boolean;
     readonly supportsRunnerAuthoredPhaseArtifacts?: boolean;
     readonly supportsDraftRunOnce?: boolean;
+    readonly supportsDraftAttachments?: boolean;
+    readonly supportsDraftImageAttachments?: boolean;
 }
 export interface LocalRepoMapping extends BridgeRepoMapping {
     readonly label: string;
@@ -32,4 +36,6 @@ export declare function removeRepoMapping(label: string): Promise<{
     readonly config: BridgeLocalConfig;
     readonly removed: boolean;
 }>;
+export declare function setServerUrl(serverUrl: string): Promise<BridgeLocalConfig>;
+export declare function setSandboxPolicy(dockerEnabled: boolean, allowOpenPublicSandbox: boolean): Promise<BridgeLocalConfig>;
 export declare function providerStatusesFor(providers: readonly string[]): Readonly<Record<string, BridgeProviderStatus>>;

package/dist/cli/local-config.js

@@ -45,6 +45,12 @@ export function applyLocalConfigDefaults(config, local) {
         deviceName: process.env.FORGE_DEVICE_NAME ?? local.deviceName ?? config.deviceName,
         defaultRepoRoot: process.env.FORGE_REPO_ROOT ?? local.defaultRepoRoot ?? config.defaultRepoRoot,
         cleanupWorktrees: local.cleanupWorktrees ?? config.cleanupWorktrees,
+        dockerEnabled: process.env.FORGE_DOCKER_SANDBOX === undefined
+            ? local.dockerEnabled ?? config.dockerEnabled
+            : config.dockerEnabled,
+        allowOpenPublicSandbox: process.env.FORGE_ALLOW_OPEN_PUBLIC_SANDBOX === undefined
+            ? local.allowOpenPublicSandbox ?? config.allowOpenPublicSandbox
+            : config.allowOpenPublicSandbox,
         cliProviders,
         providerStatuses: normalizeProviderStatuses(local.providerStatuses) ?? providerStatusesFor(cliProviders),
         projectLabels: local.projectLabels ?? config.projectLabels,
@@ -54,7 +60,9 @@ export function applyLocalConfigDefaults(config, local) {
         supportsManagedWorktrees: local.supportsManagedWorktrees ?? config.supportsManagedWorktrees,
         supportsManagedForgeArtifacts: local.supportsManagedForgeArtifacts ?? config.supportsManagedForgeArtifacts,
         supportsRunnerAuthoredPhaseArtifacts: local.supportsRunnerAuthoredPhaseArtifacts ?? config.supportsRunnerAuthoredPhaseArtifacts,
-        supportsDraftRunOnce: local.supportsDraftRunOnce ?? config.supportsDraftRunOnce
+        supportsDraftRunOnce: local.supportsDraftRunOnce ?? config.supportsDraftRunOnce,
+        supportsDraftAttachments: local.supportsDraftAttachments ?? config.supportsDraftAttachments,
+        supportsDraftImageAttachments: local.supportsDraftImageAttachments ?? config.supportsDraftImageAttachments
     };
 }
 export async function addRepoMapping(label, repoPath) {
@@ -86,6 +94,19 @@ export async function removeRepoMapping(label) {
     await writeLocalConfig(next);
     return { config: next, removed: after.length !== before.length };
 }
+export async function setServerUrl(serverUrl) {
+    const normalized = normalizeServerUrl(serverUrl);
+    const current = await readLocalConfig();
+    const next = normalizeLocalConfig({ ...current, serverUrl: normalized });
+    await writeLocalConfig(next);
+    return next;
+}
+export async function setSandboxPolicy(dockerEnabled, allowOpenPublicSandbox) {
+    const current = await readLocalConfig();
+    const next = normalizeLocalConfig({ ...current, dockerEnabled, allowOpenPublicSandbox });
+    await writeLocalConfig(next);
+    return next;
+}
 export function providerStatusesFor(providers) {
     return Object.fromEntries(providers.map((provider) => [provider, { signedIn: true, version: "", models: configuredModelsFor(provider) }]));
 }
@@ -104,6 +125,8 @@ function normalizeLocalConfig(config) {
         deviceName: cleanString(config.deviceName),
         defaultRepoRoot: cleanString(config.defaultRepoRoot),
         cleanupWorktrees: config.cleanupWorktrees,
+        dockerEnabled: config.dockerEnabled,
+        allowOpenPublicSandbox: config.allowOpenPublicSandbox,
         cliProviders: cleanList(config.cliProviders),
         providerStatuses: normalizeProviderStatuses(config.providerStatuses),
         projectLabels: cleanList(config.projectLabels),
@@ -113,7 +136,9 @@ function normalizeLocalConfig(config) {
         supportsManagedWorktrees: config.supportsManagedWorktrees,
         supportsManagedForgeArtifacts: config.supportsManagedForgeArtifacts,
         supportsRunnerAuthoredPhaseArtifacts: config.supportsRunnerAuthoredPhaseArtifacts,
-        supportsDraftRunOnce: config.supportsDraftRunOnce
+        supportsDraftRunOnce: config.supportsDraftRunOnce,
+        supportsDraftAttachments: config.supportsDraftAttachments,
+        supportsDraftImageAttachments: config.supportsDraftImageAttachments
     };
 }
 function emptyConfig() {
@@ -196,10 +221,11 @@ function normalizeQaAppLaunchTarget(value) {
         command: cleanString(value.command),
         working_directory: cleanString(value.working_directory),
         ready_url: cleanString(value.ready_url),
+        managed_runtime_port: cleanString(value.managed_runtime_port),
         routes,
         notes: cleanString(value.notes)
     };
-    return normalized.url || normalized.command || normalized.ready_url || routes?.length
+    return normalized.url || normalized.command || normalized.ready_url || normalized.managed_runtime_port
         ? normalized
         : undefined;
 }
@@ -207,6 +233,24 @@ function cleanString(value) {
     const clean = value?.trim();
     return clean ? clean : undefined;
 }
+function normalizeServerUrl(value) {
+    const clean = value.trim();
+    let parsed;
+    try {
+        parsed = new URL(clean);
+    }
+    catch {
+        throw new Error(`Invalid Forge server URL: ${value}`);
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new Error("Forge server URL must use http or https.");
+    }
+    if (parsed.username || parsed.password || parsed.search || parsed.hash) {
+        throw new Error("Forge server URL cannot include credentials, a query string, or a fragment.");
+    }
+    parsed.pathname = parsed.pathname.replace(/\/+$/u, "") || "/";
+    return parsed.toString().replace(/\/$/u, "");
+}
 function cleanList(values) {
     const clean = [...new Set((values ?? []).map((value) => value.trim()).filter(Boolean))];
     return clean.length > 0 ? clean : undefined;

package/dist/runtime/attempt-node-runtime-launcher.d.ts

@@ -0,0 +1,17 @@
+import type { AttemptProcessChildHandle, AttemptProcessSupervisor } from "./attempt-process-supervisor.js";
+import type { HostPortLeaseOwner } from "./host-port-broker.js";
+import { HostListenerInspector } from "./host-listener-inspector.js";
+import type { HostListenerOwnership, NodeRuntimeCommandLauncher, NodeRuntimeLaunchRequest, NodeRuntimeReadinessDiagnostics } from "./node-host-runtime-adapter.js";
+/** Launches one explicitly configured HTTP project beneath the attempt coordinator. */
+export declare class AttemptNodeRuntimeLauncher implements NodeRuntimeCommandLauncher<AttemptProcessChildHandle> {
+    private readonly supervisor;
+    private readonly owner;
+    private readonly logDirectory;
+    private readonly listenerInspector;
+    private readonly diagnosticsByChild;
+    constructor(supervisor: AttemptProcessSupervisor, owner: HostPortLeaseOwner, logDirectory: string, listenerInspector?: HostListenerInspector);
+    launch(request: NodeRuntimeLaunchRequest, signal?: AbortSignal): Promise<AttemptProcessChildHandle>;
+    inspectListener(child: AttemptProcessChildHandle, request: NodeRuntimeLaunchRequest): Promise<HostListenerOwnership>;
+    stop(child: AttemptProcessChildHandle): Promise<void>;
+    readinessDiagnostics(child: AttemptProcessChildHandle): Promise<NodeRuntimeReadinessDiagnostics>;
+}

package/dist/runtime/attempt-node-runtime-launcher.js

@@ -0,0 +1,101 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { HostListenerInspector } from "./host-listener-inspector.js";
+const diagnosticTailLength = 4_000;
+/** Launches one explicitly configured HTTP project beneath the attempt coordinator. */
+export class AttemptNodeRuntimeLauncher {
+    supervisor;
+    owner;
+    logDirectory;
+    listenerInspector;
+    diagnosticsByChild = new WeakMap();
+    constructor(supervisor, owner, logDirectory, listenerInspector = new HostListenerInspector()) {
+        this.supervisor = supervisor;
+        this.owner = owner;
+        this.logDirectory = logDirectory;
+        this.listenerInspector = listenerInspector;
+    }
+    async launch(request, signal) {
+        const childName = projectChildName(request.port.name);
+        const stdoutPath = path.join(this.logDirectory, `${childName}.stdout.log`);
+        const stderrPath = path.join(this.logDirectory, `${childName}.stderr.log`);
+        const diagnostics = { exited: false, stdoutTail: "", stderrTail: "" };
+        let child;
+        try {
+            child = await this.supervisor.startChildReady(childName, {
+                command: request.command,
+                args: request.args,
+                cwd: request.cwd,
+                env: request.environment,
+                captureOutput: false,
+            }, {
+                onStdoutLine: async (line) => {
+                    diagnostics.stdoutTail = appendTail(diagnostics.stdoutTail, line);
+                    await appendLine(stdoutPath, line);
+                },
+                onStderrLine: async (line) => {
+                    diagnostics.stderrTail = appendTail(diagnostics.stderrTail, line);
+                    await appendLine(stderrPath, line);
+                },
+            }, signal, { maxStartAttempts: 3, retryDelayMs: 250 });
+        }
+        catch (error) {
+            throw enrichLaunchFailure(error, diagnostics);
+        }
+        this.diagnosticsByChild.set(child, diagnostics);
+        void child.result.then(result => {
+            diagnostics.exited = true;
+            diagnostics.exitCode = result.exitCode;
+            diagnostics.stdoutTail = appendTail(diagnostics.stdoutTail, result.stdout);
+            diagnostics.stderrTail = appendTail(diagnostics.stderrTail, result.stderr);
+        }, error => {
+            diagnostics.exited = true;
+            diagnostics.stderrTail = appendTail(diagnostics.stderrTail, error instanceof Error ? error.message : String(error));
+        });
+        return child;
+    }
+    async inspectListener(child, request) {
+        return await this.listenerInspector.inspect(child, request.port, this.owner);
+    }
+    async stop(child) {
+        await child.stop(this.owner.fencingToken);
+    }
+    async readinessDiagnostics(child) {
+        // Yield once so an already-settled result can update the diagnostic record.
+        await Promise.resolve();
+        const diagnostics = this.diagnosticsByChild.get(child);
+        return diagnostics ?? { exited: false };
+    }
+}
+function projectChildName(portName) {
+    const candidate = `project-${portName}`;
+    if (/^[a-z][a-z0-9_-]{0,31}$/u.test(candidate))
+        return candidate;
+    const digest = createHash("sha256").update(portName).digest("hex").slice(0, 16);
+    return `project-${digest}`;
+}
+async function appendLine(target, line) {
+    await fs.appendFile(target, `${line}\n`, { encoding: "utf8", mode: 0o600 });
+}
+function appendTail(current, value) {
+    if (!value)
+        return current;
+    const combined = current ? `${current}\n${value}` : value;
+    return combined.slice(-diagnosticTailLength);
+}
+function enrichLaunchFailure(error, diagnostics) {
+    const message = error instanceof Error ? error.message : String(error);
+    const evidence = [
+        diagnostics.stderrTail ? `stderr tail: ${boundedDiagnostic(diagnostics.stderrTail)}` : "",
+        diagnostics.stdoutTail ? `stdout tail: ${boundedDiagnostic(diagnostics.stdoutTail)}` : "",
+    ].filter(Boolean);
+    return evidence.length > 0
+        ? new Error(`${message} ${evidence.join("; ")}`, { cause: error })
+        : error instanceof Error
+            ? error
+            : new Error(message);
+}
+function boundedDiagnostic(value) {
+    return value.replaceAll(/[\r\n\t]+/gu, " ").trim().slice(-1_000);
+}

package/dist/runtime/attempt-process-supervisor-registry.d.ts

@@ -0,0 +1,20 @@
+import type { ProviderProcessHandlers, ProviderProcessRunRequest, ProviderProcessRunner, ProviderProcessRunResult } from "../session/provider-cli/provider-cli.process.js";
+import { AttemptProcessSupervisor, type AttemptProcessSupervisorIdentity, type AttemptProcessSupervisorOptions } from "./attempt-process-supervisor.js";
+/** Runner-local authority for active host attempt process coordinators. */
+export declare class AttemptProcessSupervisorRegistry {
+    private readonly active;
+    register(identity: AttemptProcessSupervisorIdentity, runner: ProviderProcessRunner, options?: AttemptProcessSupervisorOptions): AttemptProcessSupervisor;
+    require(dispatchAttemptId: string, fencingToken: string): AttemptProcessSupervisor;
+    unregister(dispatchAttemptId: string, fencingToken: string): boolean;
+    has(dispatchAttemptId: string): boolean;
+}
+/**
+ * Routes managed-host provider commands through the attempt's named provider
+ * child while retaining the raw runner for Docker and unmanaged execution.
+ */
+export declare class AttemptCoordinatedProviderProcessRunner implements ProviderProcessRunner {
+    private readonly registry;
+    private readonly rawRunner;
+    constructor(registry: AttemptProcessSupervisorRegistry, rawRunner: ProviderProcessRunner);
+    run(request: ProviderProcessRunRequest, handlers?: ProviderProcessHandlers, signal?: AbortSignal): Promise<ProviderProcessRunResult>;
+}

package/dist/runtime/attempt-process-supervisor-registry.js

@@ -0,0 +1,64 @@
+import { AttemptProcessSupervisor, } from "./attempt-process-supervisor.js";
+/** Runner-local authority for active host attempt process coordinators. */
+export class AttemptProcessSupervisorRegistry {
+    active = new Map();
+    register(identity, runner, options = {}) {
+        const existing = this.active.get(identity.dispatchAttemptId);
+        if (existing) {
+            if (existing.fencingToken !== identity.fencingToken) {
+                throw new Error("attempt_process_registry_conflict: dispatch attempt is registered under a different fence.");
+            }
+            return existing.supervisor;
+        }
+        const supervisor = new AttemptProcessSupervisor(identity, runner, options);
+        this.active.set(identity.dispatchAttemptId, { fencingToken: identity.fencingToken, supervisor });
+        return supervisor;
+    }
+    require(dispatchAttemptId, fencingToken) {
+        const registered = this.active.get(dispatchAttemptId);
+        if (!registered) {
+            throw new Error("attempt_process_registry_missing: no process coordinator owns this dispatch attempt.");
+        }
+        if (registered.fencingToken !== fencingToken) {
+            throw new Error("attempt_process_registry_fenced: process coordinator fence does not match the dispatch.");
+        }
+        return registered.supervisor;
+    }
+    unregister(dispatchAttemptId, fencingToken) {
+        const registered = this.active.get(dispatchAttemptId);
+        if (!registered || registered.fencingToken !== fencingToken)
+            return false;
+        return this.active.delete(dispatchAttemptId);
+    }
+    has(dispatchAttemptId) {
+        return this.active.has(dispatchAttemptId);
+    }
+}
+/**
+ * Routes managed-host provider commands through the attempt's named provider
+ * child while retaining the raw runner for Docker and unmanaged execution.
+ */
+export class AttemptCoordinatedProviderProcessRunner {
+    registry;
+    rawRunner;
+    constructor(registry, rawRunner) {
+        this.registry = registry;
+        this.rawRunner = rawRunner;
+    }
+    async run(request, handlers, signal) {
+        if (request.env?.FORGE_RUNTIME_MODE !== "host") {
+            return await this.rawRunner.run(request, handlers, signal);
+        }
+        const dispatchAttemptId = requiredEnvironment(request, "FORGE_DISPATCH_ATTEMPT_ID");
+        const fencingToken = requiredEnvironment(request, "FORGE_FENCING_TOKEN");
+        const supervisor = this.registry.require(dispatchAttemptId, fencingToken);
+        const child = await supervisor.startChildReady("provider", request, handlers, signal, { maxStartAttempts: request.stdin === undefined ? 1 : 3, retryDelayMs: 100 });
+        return await child.result;
+    }
+}
+function requiredEnvironment(request, name) {
+    const value = request.env?.[name]?.trim();
+    if (!value)
+        throw new Error(`attempt_process_registry_invalid: ${name} is required for managed-host execution.`);
+    return value;
+}

package/dist/runtime/attempt-process-supervisor.d.ts

@@ -0,0 +1,86 @@
+import type { ProviderProcessHandlers, ProviderProcessRunRequest, ProviderProcessRunner, ProviderProcessRunResult } from "../session/provider-cli/provider-cli.process.js";
+export type AttemptProcessChildStatus = "starting" | "running" | "stopping" | "exited" | "failed";
+export type AttemptProcessSupervisorStatus = "active" | "stopping" | "stopped" | "degraded";
+export interface AttemptProcessSupervisorIdentity {
+    readonly processSupervisorId: string;
+    readonly dispatchAttemptId: string;
+    readonly executionLeaseId: string;
+    readonly fencingToken: string;
+    readonly logDirectory: string;
+}
+export interface AttemptProcessChildLedgerEntry {
+    readonly name: string;
+    readonly generation: number;
+    readonly childId: string;
+    readonly processSupervisorId: string;
+    readonly metadataPath: string;
+    readonly status: AttemptProcessChildStatus;
+    readonly startedAt: string;
+    readonly settledAt?: string;
+    readonly exitCode?: number;
+    readonly failure?: string;
+}
+export interface AttemptProcessSupervisorLedger {
+    readonly schemaVersion: 1;
+    readonly attemptSupervisorId: string;
+    readonly dispatchAttemptId: string;
+    readonly executionLeaseId: string;
+    readonly status: AttemptProcessSupervisorStatus;
+    readonly updatedAt: string;
+    readonly children: readonly AttemptProcessChildLedgerEntry[];
+}
+export interface AttemptProcessChildHandle {
+    readonly name: string;
+    readonly generation: number;
+    readonly childId: string;
+    readonly processSupervisorId: string;
+    readonly metadataPath: string;
+    readonly ready: Promise<void>;
+    readonly result: Promise<ProviderProcessRunResult>;
+    stop(fencingToken: string): Promise<ProviderProcessRunResult>;
+}
+export interface AttemptProcessSupervisorOptions {
+    readonly metadataReadyTimeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+export interface AttemptProcessChildReadyOptions {
+    readonly maxStartAttempts?: number;
+    readonly retryDelayMs?: number;
+}
+/**
+ * Owns the independently supervised process trees that belong to one host
+ * dispatch attempt. Each named child gets a distinct Windows Job Object or
+ * Unix process group through the existing process runner, while this
+ * coordinator supplies shared fencing, cancellation, and a durable ledger.
+ */
+export declare class AttemptProcessSupervisor {
+    private readonly runner;
+    readonly ledgerPath: string;
+    private readonly identity;
+    private readonly metadataReadyTimeoutMs;
+    private readonly records;
+    private readonly currentByName;
+    private readonly attemptController;
+    private status;
+    private persistTail;
+    private persistenceFailure;
+    private stopOperation;
+    constructor(identity: AttemptProcessSupervisorIdentity, runner: ProviderProcessRunner, options?: AttemptProcessSupervisorOptions);
+    startChild(name: string, request: ProviderProcessRunRequest, handlers?: ProviderProcessHandlers, signal?: AbortSignal): Promise<AttemptProcessChildHandle>;
+    /**
+     * Starts a child and proves that the OS process tree is supervised before
+     * returning it to the caller. A launch that settles before producing its
+     * provider-ready supervision record is safe to retry: the raw runner only
+     * persists that record after the actual provider child has started, before
+     * Forge announces the provider as active.
+     */
+    startChildReady(name: string, request: ProviderProcessRunRequest, handlers?: ProviderProcessHandlers, signal?: AbortSignal, options?: AttemptProcessChildReadyOptions): Promise<AttemptProcessChildHandle>;
+    stopChild(name: string, generation: number, fencingToken: string, reason?: unknown): Promise<ProviderProcessRunResult>;
+    stopAll(fencingToken: string, reason?: unknown): Promise<void>;
+    private performStopAll;
+    snapshot(): AttemptProcessSupervisorLedger;
+    private observeChildReady;
+    private settleChild;
+    private assertFence;
+    private persist;
+}