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

package/dist/sandbox/sandbox.types.d.ts

@@ -0,0 +1,83 @@
+import type { RunOnceDispatchPacket } from "../session/session.types.js";
+export interface SandboxContract {
+    readonly schemaVersion: 1;
+    readonly workingDirectory: "/workspace";
+    readonly commands: Readonly<Record<string, string>>;
+    readonly caches: readonly SandboxCache[];
+    readonly services: readonly SandboxService[];
+    readonly environment: readonly string[];
+    readonly artifacts: readonly string[];
+    readonly logs: readonly string[];
+    readonly browser: boolean;
+}
+export interface SandboxCache {
+    readonly name: string;
+    readonly mode: "readonly" | "per_attempt";
+}
+export interface SandboxService {
+    readonly type: "postgres" | "redis" | "browser";
+    readonly port: number;
+}
+export interface ValidatedSandboxContract {
+    readonly contract: SandboxContract;
+    readonly normalizedJson: string;
+    readonly digest: string;
+}
+export interface SandboxPreflightResult {
+    readonly available: boolean;
+    readonly healthy: boolean;
+    readonly generation: number;
+    readonly runtimeVersion: string | null;
+    readonly maxConcurrentSandboxes: number;
+    readonly availableMemoryBytes: number;
+    readonly availableCpuMillis: number;
+    readonly availableWorkspaceBytes: number;
+    readonly diskLow: boolean;
+    readonly unavailableCode: string | null;
+    readonly unavailableReason: string | null;
+    readonly features: SandboxFeatureMatrix;
+}
+export interface SandboxFeatureMatrix {
+    readonly rootless: boolean;
+    readonly userNamespaces: boolean;
+    readonly cgroupV2: boolean;
+    readonly seccomp: boolean;
+    readonly lsm: boolean;
+    readonly storageQuota: boolean;
+    readonly storagePolicy: boolean;
+    readonly compose: boolean;
+    readonly internalNetwork: boolean;
+    readonly buildkit: boolean;
+    readonly imagePolicy: boolean;
+    readonly securityProfile: boolean;
+    readonly egressProxy: boolean;
+}
+export interface SandboxReservation {
+    readonly dispatchAttemptId: string;
+    readonly leaseId: string;
+    readonly fencingToken: string;
+    readonly runnerInstanceId: string;
+    readonly expiresAt: string;
+    readonly reservedUntil: string;
+    readonly dispatch: RunOnceDispatchPacket;
+    readonly contract?: ValidatedSandboxContract;
+    readonly inputCommitSha?: string;
+    readonly sandboxConfigCommitSha?: string;
+    readonly imageDigest?: string;
+}
+export interface CommandResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface CommandRunner {
+    run(command: string, args: readonly string[], options?: CommandOptions): Promise<CommandResult>;
+}
+export interface CommandOptions {
+    readonly cwd?: string;
+    readonly env?: Readonly<Record<string, string>>;
+    readonly stdin?: string | Uint8Array;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+    readonly maxOutputBytes?: number;
+}

package/dist/sandbox/sandbox.types.js

@@ -0,0 +1 @@
+export {};

package/dist/sandbox/worker-supervisor.d.ts

@@ -0,0 +1,13 @@
+import type { MonotonicLeaseDeadline } from "./lease-watchdog.js";
+export type SandboxTerminationCode = "sandbox_lease_expired" | "sandbox_wall_timeout" | "sandbox_idle_timeout";
+export declare class WorkerDeadlineSupervisor {
+    readonly lease: MonotonicLeaseDeadline;
+    readonly hardWallMs: number;
+    readonly idleMs: number;
+    private readonly startedAtMs;
+    private lastActivityMs;
+    constructor(lease: MonotonicLeaseDeadline, hardWallMs: number, idleMs: number, startedAtMs?: number);
+    touch(nowMs?: number): void;
+    termination(nowMs?: number): SandboxTerminationCode | null;
+}
+export declare function terminationMessage(code: SandboxTerminationCode): string;

package/dist/sandbox/worker-supervisor.js

@@ -0,0 +1,36 @@
+export class WorkerDeadlineSupervisor {
+    lease;
+    hardWallMs;
+    idleMs;
+    startedAtMs;
+    lastActivityMs;
+    constructor(lease, hardWallMs, idleMs, startedAtMs = performance.now()) {
+        this.lease = lease;
+        this.hardWallMs = hardWallMs;
+        this.idleMs = idleMs;
+        this.startedAtMs = startedAtMs;
+        if (!Number.isFinite(hardWallMs) || hardWallMs <= 0 || !Number.isFinite(idleMs) || idleMs <= 0) {
+            throw new Error("Sandbox watchdog limits must be positive.");
+        }
+        this.lastActivityMs = startedAtMs;
+    }
+    touch(nowMs = performance.now()) {
+        this.lastActivityMs = Math.max(this.lastActivityMs, nowMs);
+    }
+    termination(nowMs = performance.now()) {
+        if (this.lease.expired(nowMs))
+            return "sandbox_lease_expired";
+        if (nowMs - this.startedAtMs >= this.hardWallMs)
+            return "sandbox_wall_timeout";
+        if (nowMs - this.lastActivityMs >= this.idleMs)
+            return "sandbox_idle_timeout";
+        return null;
+    }
+}
+export function terminationMessage(code) {
+    switch (code) {
+        case "sandbox_lease_expired": return "The durable execution lease expired inside the sandbox.";
+        case "sandbox_wall_timeout": return "The sandbox reached its hard wall-clock limit.";
+        case "sandbox_idle_timeout": return "The sandbox produced no control or process activity before its idle limit.";
+    }
+}

package/dist/sandbox/worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sandbox/worker.js

@@ -0,0 +1,228 @@
+import { createHash } from "node:crypto";
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { MonotonicLeaseDeadline } from "./lease-watchdog.js";
+import { terminationMessage, WorkerDeadlineSupervisor } from "./worker-supervisor.js";
+const controlRoot = "/control";
+const runtimeRoot = "/run/forge";
+const workspace = process.env.FORGE_WORKSPACE ?? "/workspace";
+async function main() {
+    const dispatchText = await readBoundedStdin(16 * 1024 * 1024);
+    const bootstrap = JSON.parse(dispatchText);
+    if (bootstrap.schemaVersion !== 1 || !bootstrap.dispatch || typeof bootstrap.leaseControlKey !== "string") {
+        throw new Error("Invalid sandbox bootstrap packet.");
+    }
+    const dispatch = bootstrap.dispatch;
+    const sandbox = dispatch.sandbox;
+    const attemptId = requiredId(sandbox?.dispatchAttemptId, "dispatchAttemptId");
+    const lease = dispatch.lease;
+    const fencingToken = requiredId(lease?.fencingToken, "fencingToken");
+    const leaseDeadline = new MonotonicLeaseDeadline(attemptId, fencingToken, requiredString(lease?.expiresAt, "expiresAt"), bootstrap.leaseControlKey);
+    const limits = requiredLimits(bootstrap.limits);
+    await installServiceEnvironment(attemptId);
+    await fs.mkdir(runtimeRoot, { recursive: true, mode: 0o700 });
+    await fs.mkdir(path.join(controlRoot, "output"), { recursive: true, mode: 0o700 });
+    const dispatchPath = path.join(runtimeRoot, "dispatch.json");
+    const resultPath = path.join(controlRoot, "output", "result.json");
+    await fs.writeFile(dispatchPath, JSON.stringify(dispatch), { mode: 0o600 });
+    const entrypoint = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../cli/bin.js");
+    const runOutcome = await run(process.execPath, [entrypoint, "run-once", "--dispatch", dispatchPath, "--result", resultPath], {
+        deadline: leaseDeadline,
+        updatePath: path.join(runtimeRoot, "lease-update.json"),
+        supervisor: new WorkerDeadlineSupervisor(leaseDeadline, limits.hardWallMs, limits.idleMs)
+    });
+    await fs.rm(dispatchPath, { force: true });
+    if (runOutcome.terminationCode) {
+        await writeTerminationResult(resultPath, runOutcome.terminationCode);
+    }
+    let resultCommitSha = null;
+    let bundleSha256 = null;
+    let bundleBytes = 0;
+    const bundlePath = path.join(controlRoot, "output", "result.bundle");
+    if (!runOutcome.terminationCode && await exists(path.join(workspace, ".git"))) {
+        resultCommitSha = (await capture("git", ["-C", workspace, "rev-parse", "HEAD"])).trim();
+        const resultRef = `refs/forge/results/${attemptId.replace(/-/g, "")}`;
+        await runRequired("git", ["-C", workspace, "update-ref", resultRef, resultCommitSha]);
+        try {
+            await runRequired("git", ["-C", workspace, "bundle", "create", bundlePath, resultRef]);
+        }
+        finally {
+            await run("git", ["-C", workspace, "update-ref", "-d", resultRef]);
+        }
+        const bundle = await fs.readFile(bundlePath);
+        bundleBytes = bundle.length;
+        bundleSha256 = createHash("sha256").update(bundle).digest("hex");
+    }
+    const resultBytes = await fs.readFile(resultPath);
+    const manifest = {
+        schemaVersion: 1,
+        dispatchAttemptId: attemptId,
+        executionLeaseId: sandbox?.executionLeaseId,
+        fencingToken: dispatch.lease?.fencingToken,
+        runnerInstanceId: sandbox?.runnerInstanceId,
+        inputCommitSha: sandbox?.inputCommitSha,
+        resultCommitSha,
+        branch: dispatch.lease?.worktreeKey,
+        contractDigest: sandbox?.contractDigest,
+        imageDigest: sandbox?.imageDigest,
+        result: { path: "result.json", bytes: resultBytes.length, sha256: createHash("sha256").update(resultBytes).digest("hex") },
+        bundle: bundleSha256 ? { path: "result.bundle", bytes: bundleBytes, sha256: bundleSha256 } : null,
+        workerExitCode: runOutcome.exitCode,
+        workerExitClassification: runOutcome.terminationCode ?? "agent_exit"
+    };
+    const temporary = path.join(controlRoot, "output", "manifest.json.tmp");
+    await fs.writeFile(temporary, `${JSON.stringify(manifest)}\n`, { mode: 0o600 });
+    await fs.rename(temporary, path.join(controlRoot, "output", "manifest.json"));
+    return runOutcome.exitCode;
+}
+async function readBoundedStdin(limit) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of process.stdin) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        total += buffer.length;
+        if (total > limit)
+            throw new Error("Dispatch bootstrap exceeds 16 MiB.");
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+async function run(command, args, watchdog) {
+    return await new Promise((resolve, reject) => {
+        const child = spawn(command, args, { stdio: ["ignore", "pipe", "pipe"], shell: false });
+        let readingUpdate = false;
+        let killTimer = null;
+        let terminationCode = null;
+        const terminate = (code) => {
+            if (child.exitCode !== null || child.signalCode !== null)
+                return;
+            terminationCode ??= code;
+            emitTerminationEvent(terminationCode);
+            child.kill("SIGTERM");
+            killTimer = setTimeout(() => child.kill("SIGKILL"), 10_000);
+            killTimer.unref?.();
+        };
+        child.stdout.on("data", chunk => {
+            watchdog?.supervisor.touch();
+            process.stdout.write(chunk);
+        });
+        child.stderr.on("data", chunk => {
+            watchdog?.supervisor.touch();
+            process.stderr.write(chunk);
+        });
+        const monitor = watchdog ? setInterval(() => {
+            const reason = watchdog.supervisor.termination();
+            if (reason) {
+                terminate(reason);
+                return;
+            }
+            if (readingUpdate)
+                return;
+            readingUpdate = true;
+            fs.readFile(watchdog.updatePath, "utf8")
+                .then(value => {
+                const applied = watchdog.deadline.apply(JSON.parse(value));
+                if (applied)
+                    watchdog.supervisor.touch();
+                return applied;
+            })
+                .catch(() => false)
+                .finally(() => { readingUpdate = false; });
+        }, 250) : null;
+        monitor?.unref?.();
+        child.on("error", error => {
+            if (monitor)
+                clearInterval(monitor);
+            if (killTimer)
+                clearTimeout(killTimer);
+            reject(error);
+        });
+        child.on("close", code => {
+            if (monitor)
+                clearInterval(monitor);
+            if (killTimer)
+                clearTimeout(killTimer);
+            resolve({ exitCode: terminationCode ? 124 : code ?? 1, terminationCode });
+        });
+    });
+}
+async function runRequired(command, args) {
+    const outcome = await run(command, args);
+    if (outcome.exitCode !== 0)
+        throw new Error(`${command} failed with exit ${outcome.exitCode}.`);
+}
+async function capture(command, args) {
+    return await new Promise((resolve, reject) => {
+        const child = spawn(command, args, { stdio: ["ignore", "pipe", "inherit"], shell: false });
+        const chunks = [];
+        child.stdout.on("data", chunk => chunks.push(Buffer.from(chunk)));
+        child.on("error", reject);
+        child.on("close", code => code === 0 ? resolve(Buffer.concat(chunks).toString("utf8")) : reject(new Error(`${command} failed with exit ${code}.`)));
+    });
+}
+async function exists(target) { return fs.stat(target).then(() => true).catch(() => false); }
+async function installServiceEnvironment(attemptId) {
+    const attemptHex = attemptId.replace(/-/gu, "").toLowerCase();
+    const postgresPassword = await readServiceCredential("postgres-password");
+    if (postgresPassword)
+        process.env.FORGE_TEST_DATABASE = `postgresql://forge:${encodeURIComponent(postgresPassword)}@forge-${attemptHex}-postgres:5432/forge_test`;
+    const redisPassword = await readServiceCredential("redis-password");
+    if (redisPassword)
+        process.env.FORGE_TEST_REDIS = `redis://:${encodeURIComponent(redisPassword)}@forge-${attemptHex}-redis:6379/0`;
+    const browserToken = await readServiceCredential("browser-token");
+    if (browserToken)
+        process.env.FORGE_BROWSER_TOKEN = browserToken;
+}
+async function readServiceCredential(name) {
+    const target = `/run/forge-secrets/${name}`;
+    const stat = await fs.lstat(target).catch(() => null);
+    if (!stat)
+        return null;
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size < 32 || stat.size > 256) {
+        throw new Error(`Invalid ${name} service credential file.`);
+    }
+    return (await fs.readFile(target, "utf8")).trim();
+}
+function requiredId(value, label) {
+    if (typeof value !== "string" || !/^[0-9a-f-]{32,36}$/i.test(value))
+        throw new Error(`Invalid ${label}.`);
+    return value;
+}
+function requiredString(value, label) {
+    if (typeof value !== "string" || value.length === 0)
+        throw new Error(`Invalid ${label}.`);
+    return value;
+}
+function requiredLimits(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Invalid sandbox watchdog limits.");
+    const limits = value;
+    if (typeof limits.hardWallMs !== "number" || !Number.isSafeInteger(limits.hardWallMs) || limits.hardWallMs < 60_000 || limits.hardWallMs > 28_800_000
+        || typeof limits.idleMs !== "number" || !Number.isSafeInteger(limits.idleMs) || limits.idleMs < 60_000 || limits.idleMs > limits.hardWallMs) {
+        throw new Error("Invalid sandbox watchdog limits.");
+    }
+    return { hardWallMs: limits.hardWallMs, idleMs: limits.idleMs };
+}
+async function writeTerminationResult(resultPath, code) {
+    const message = terminationMessage(code);
+    const result = {
+        schemaVersion: 1,
+        exitCode: 124,
+        summary: message,
+        events: [{ role: "runner", kind: "error", content: message, eventType: code }]
+    };
+    const temporary = `${resultPath}.timeout.tmp`;
+    await fs.writeFile(temporary, `${JSON.stringify(result)}\n`, { mode: 0o600 });
+    await fs.rename(temporary, resultPath);
+}
+function emitTerminationEvent(code) {
+    const message = terminationMessage(code);
+    process.stdout.write(`${JSON.stringify({ type: "runner_event", event: { role: "runner", kind: "error", content: message, eventType: code } })}\n`);
+    process.stderr.write(`${code}: ${message}\n`);
+}
+main().then(code => { process.exitCode = code; }).catch(error => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});

package/dist/sandbox/workspace.service.d.ts

@@ -0,0 +1,12 @@
+import { GitClient } from "../shared/git/git.js";
+import type { WorktreeService } from "../worktree/worktree.base.js";
+import type { WorktreeHandle, WorktreePrepareRequest } from "../worktree/worktree.types.js";
+export declare class SandboxWorkspaceService implements WorktreeService {
+    private readonly workspace;
+    private readonly bundlePath;
+    private readonly inputCommitSha;
+    private readonly git;
+    constructor(workspace?: string, bundlePath?: string, inputCommitSha?: string, git?: GitClient);
+    prepare(request: WorktreePrepareRequest): Promise<WorktreeHandle>;
+    release(_handle: WorktreeHandle): Promise<void>;
+}

package/dist/sandbox/workspace.service.js

@@ -0,0 +1,49 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { GitClient } from "../shared/git/git.js";
+import { injectWorktreeArtifacts, filterArtifactsForLane } from "../worktree/artifact-injector.js";
+import { normalizeBranchName } from "../worktree/worktree.service.js";
+export class SandboxWorkspaceService {
+    workspace;
+    bundlePath;
+    inputCommitSha;
+    git;
+    constructor(workspace = process.env.FORGE_WORKSPACE ?? "/workspace", bundlePath = process.env.FORGE_INPUT_BUNDLE ?? "/control/input/repo.bundle", inputCommitSha = process.env.FORGE_INPUT_COMMIT_SHA ?? "", git = new GitClient()) {
+        this.workspace = workspace;
+        this.bundlePath = bundlePath;
+        this.inputCommitSha = inputCommitSha;
+        this.git = git;
+    }
+    async prepare(request) {
+        if (!/^[0-9a-f]{40,64}$/i.test(this.inputCommitSha))
+            throw new Error("Sandbox input commit SHA is missing or invalid.");
+        const stat = await fs.stat(this.workspace).catch(() => null);
+        if (!stat?.isDirectory())
+            throw new Error("Sandbox workspace volume is unavailable.");
+        const entries = await fs.readdir(this.workspace);
+        if (entries.length > 0)
+            throw new Error("Sandbox workspace must be empty before bundle import.");
+        await this.git.run(path.dirname(this.workspace), ["clone", "--no-checkout", "--no-local", this.bundlePath, this.workspace]);
+        const actualSha = (await this.git.run(this.workspace, ["rev-parse", "--verify", `${this.inputCommitSha}^{commit}`])).trim();
+        if (actualSha.toLowerCase() !== this.inputCommitSha.toLowerCase())
+            throw new Error("Imported bundle does not contain the exact recorded input commit.");
+        const branchName = normalizeBranchName(request.worktreeKey, `forge/${request.workItem.id.replace(/-/g, "")}`);
+        await this.git.run(this.workspace, ["checkout", "-B", branchName, this.inputCommitSha]);
+        await this.git.run(this.workspace, ["config", "user.email", "forge-agent@forge.local"]);
+        await this.git.run(this.workspace, ["config", "user.name", "Forge Agent"]);
+        await this.git.run(this.workspace, ["config", "core.hooksPath", "/dev/null"]);
+        const artifacts = filterArtifactsForLane(request.artifacts, request.lane, request.phase);
+        if (artifacts.length > 0)
+            await injectWorktreeArtifacts(this.workspace, artifacts);
+        return {
+            repoPath: this.workspace,
+            worktreePath: this.workspace,
+            branchName,
+            baseBranch: request.baseBranch,
+            cleanupWorktrees: false
+        };
+    }
+    async release(_handle) {
+        // The host supervisor owns the workspace volume lifecycle.
+    }
+}

package/dist/session/phase-completion.artifacts.d.ts

@@ -0,0 +1,10 @@
+import { type CompletionArtifactReference, type CompletionPhase, type CompletionToolServerConfig, type DecomposeCompletionGate, type DraftCompletionGate, type QaCompletionGate } from "./phase-completion.js";
+import type { RunnerDispatchArtifact } from "./session.types.js";
+export declare function writeDecomposeGateCompletionArtifact(config: CompletionToolServerConfig, gate: DecomposeCompletionGate, toolName: string, input: unknown): Promise<CompletionArtifactReference>;
+export declare function writeDraftGateCompletionArtifact(config: CompletionToolServerConfig, gate: DraftCompletionGate, toolName: string, input: unknown): Promise<CompletionArtifactReference>;
+export declare function writeCompletionArtifact(config: CompletionToolServerConfig, toolName: string, input: unknown): Promise<CompletionArtifactReference>;
+export declare function writeArchitectCompletionArtifact(config: CompletionToolServerConfig, payload: Record<string, unknown>, status: string, producedBy: string): Promise<CompletionArtifactReference>;
+export declare function writeQaGateCompletionArtifact(config: CompletionToolServerConfig, gate: QaCompletionGate, input: unknown): Promise<CompletionArtifactReference>;
+export declare function writeQaCompletionArtifact(config: CompletionToolServerConfig, payload: Record<string, unknown>, status: string, producedBy: string): Promise<CompletionArtifactReference>;
+export declare function readQaGateArtifact(config: CompletionToolServerConfig, gate: QaCompletionGate): Promise<Record<string, unknown>>;
+export declare function readCompletionArtifact(worktreePath: string, workItemId: string, phase: CompletionPhase, ownerType?: string | null, ownerId?: string | null): Promise<RunnerDispatchArtifact | null>;