@loucompanion/forge-bridge 0.1.3-dev.b3bce6ba65a6 → 0.1.3-dev.ba293ccf876b

package/dist/runtime/attempt-path-operation.js

@@ -0,0 +1,94 @@
+import { runPinnedDirectoryProcess } from "./pinned-directory-process.js";
+/** A separate process pins cwd without changing the multithreaded Bridge's cwd.
+ * All writes use single relative components, never a re-resolved ancestor path.
+ */
+export async function runAttemptPathOperation(parent, identity, operation) {
+    try {
+        await runPinnedDirectoryProcess(parent, identity, worker, operation);
+    }
+    catch (error) {
+        throw new Error(`playwright_runtime_adapter_invalid: pinned directory operation failed: ${String(error)}`, { cause: error });
+    }
+}
+/** Archive copies may be large or numerous: never block Bridge heartbeats while a pinned worker writes. */
+export async function runAttemptArchiveOperation(parent, identity, operation) {
+    try {
+        await runPinnedDirectoryProcess(parent, identity, worker, { kind: "archive", name: operation.name, sha256: operation.sha256 }, operation.bytes);
+    }
+    catch (error) {
+        throw new Error(`host_diagnostics_copy_failed: pinned directory operation failed: ${String(error)}`, { cause: error });
+    }
+}
+const worker = String.raw `
+const fs = require('node:fs');
+const path = require('node:path');
+const input = fs.readFileSync(0);
+const boundary = input.indexOf(10);
+const job = JSON.parse(input.subarray(0, boundary).toString('utf8'));
+const same = (a, b) => a.dev === b.dev && a.ino === b.ino;
+const samePath = (a, b) => process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+const component = value => {
+  if (typeof value !== 'string' || !value || value === '.' || value === '..'
+    || ['/', ':', String.fromCharCode(92), String.fromCharCode(0)].some(char => value.includes(char)))
+    throw new Error('invalid relative component');
+};
+const statCwd = () => fs.statSync('.', { bigint: true });
+try {
+  if (!same(statCwd(), { dev: BigInt(job.dev), ino: BigInt(job.ino) })
+    || !samePath(fs.realpathSync('.'), job.parent)) throw new Error('parent identity changed');
+  if (job.kind === 'mkdir' || job.kind === 'private-directory-mode') {
+    let expected = job.parent;
+    for (const name of job.segments) {
+      component(name);
+      let before;
+      try { before = fs.lstatSync(name, { bigint: true }); }
+      catch (error) {
+        if (error.code !== 'ENOENT' || job.kind !== 'mkdir') throw error;
+        try { fs.mkdirSync(name, { mode: 0o700 }); }
+        catch (mkdirError) { if (mkdirError.code !== 'EEXIST') throw mkdirError; }
+        before = fs.lstatSync(name, { bigint: true });
+      }
+      if (!before.isDirectory() || before.isSymbolicLink()) throw new Error('redirected directory');
+      process.chdir(name);
+      expected = path.join(expected, name);
+      if (!same(before, statCwd()) || !samePath(fs.realpathSync('.'), expected)) throw new Error('child identity changed');
+    }
+    if (job.kind === 'private-directory-mode' && process.platform !== 'win32') fs.chmodSync('.', 0o700);
+  } else if (job.kind === 'overlay' || job.kind === 'archive') {
+    component(job.name);
+    let before;
+    try { before = fs.lstatSync(job.name, { bigint: true }); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+    if (before && (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1n))
+      throw new Error('overlay must be a regular file');
+    const fd = fs.openSync(job.name, (job.kind === 'archive' ? fs.constants.O_RDWR : fs.constants.O_WRONLY) | (fs.constants.O_NOFOLLOW ?? 0)
+      | (fs.constants.O_NONBLOCK ?? 0) | (before ? 0 : fs.constants.O_CREAT | fs.constants.O_EXCL), 0o600);
+    try {
+      const opened = fs.fstatSync(fd, { bigint: true });
+      if (!opened.isFile() || opened.nlink !== 1n || (before && !same(before, opened)))
+        throw new Error('overlay identity changed');
+      fs.ftruncateSync(fd, 0);
+      if (job.kind === 'overlay') fs.writeFileSync(fd, job.content, 'utf8');
+      else {
+        const bytes = input.subarray(boundary + 1);
+        fs.writeFileSync(fd, bytes);
+        fs.fsyncSync(fd);
+        const hash = require('node:crypto').createHash('sha256');
+        const chunk = Buffer.alloc(64 * 1024);
+        let offset = 0;
+        while (offset < bytes.length) {
+          const count = fs.readSync(fd, chunk, 0, Math.min(chunk.length, bytes.length - offset), offset);
+          if (!count) throw new Error('incomplete archive read');
+          hash.update(chunk.subarray(0, count));
+          offset += count;
+        }
+        const after = fs.fstatSync(fd, { bigint: true });
+        const current = fs.lstatSync(job.name, { bigint: true });
+        if (after.size !== BigInt(bytes.length) || after.nlink !== 1n || current.isSymbolicLink()
+          || !same(opened, after) || !same(after, current) || hash.digest('hex') !== job.sha256)
+          throw new Error('archive verification failed');
+      }
+    } finally { fs.closeSync(fd); }
+  } else throw new Error('invalid operation');
+} catch (error) { process.stderr.write(error.message); process.exitCode = 1; }
+`;

package/dist/runtime/attempt-private-directory.d.ts

@@ -0,0 +1,6 @@
+import type { BigIntStats } from "node:fs";
+/** Validate every existing ancestor before creating anything through a pathname. */
+export declare function assertCanonicalDirectory(target: string, allowMissing?: boolean): Promise<BigIntStats | undefined>;
+export declare function createCanonicalDirectory(target: string): Promise<void>;
+export declare function createPrivateCanonicalDirectory(target: string): Promise<void>;
+export declare function restorePrivateDirectoryMode(target: string): Promise<void>;

package/dist/runtime/attempt-private-directory.js

@@ -0,0 +1,54 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { runAttemptPathOperation } from "./attempt-path-operation.js";
+/** Validate every existing ancestor before creating anything through a pathname. */
+export async function assertCanonicalDirectory(target, allowMissing = false) {
+    const resolved = path.resolve(target);
+    const parent = path.dirname(resolved);
+    if (parent !== resolved)
+        await assertCanonicalDirectory(parent, allowMissing);
+    try {
+        const stat = await fs.lstat(resolved, { bigint: true });
+        const real = await fs.realpath(resolved);
+        const realStat = await fs.lstat(real, { bigint: true });
+        if (stat.isSymbolicLink() || !stat.isDirectory() || !samePath(real, resolved)
+            || stat.dev !== realStat.dev || stat.ino !== realStat.ino) {
+            throw new Error("playwright_runtime_adapter_invalid: writable paths must be canonical, link-free directories.");
+        }
+        return realStat;
+    }
+    catch (error) {
+        if (allowMissing && error.code === "ENOENT")
+            return;
+        throw error;
+    }
+}
+export async function createCanonicalDirectory(target) {
+    if (await assertCanonicalDirectory(target, true))
+        return;
+    const resolved = path.resolve(target);
+    let parent = path.dirname(resolved);
+    let identity = await assertCanonicalDirectory(parent, true);
+    while (!identity) {
+        parent = path.dirname(parent);
+        identity = await assertCanonicalDirectory(parent, true);
+    }
+    await runAttemptPathOperation(parent, identity, { kind: "mkdir", segments: path.relative(parent, resolved).split(path.sep) });
+    await assertCanonicalDirectory(resolved);
+}
+export async function createPrivateCanonicalDirectory(target) {
+    await createCanonicalDirectory(target);
+    await restorePrivateDirectoryMode(target);
+}
+export async function restorePrivateDirectoryMode(target) {
+    if (process.platform === "win32")
+        return;
+    const resolved = path.resolve(target);
+    const parent = path.dirname(resolved);
+    const identity = await assertCanonicalDirectory(parent);
+    await runAttemptPathOperation(parent, identity, { kind: "private-directory-mode", segments: [path.basename(resolved)] });
+    await assertCanonicalDirectory(resolved);
+}
+function samePath(left, right) {
+    return process.platform === "win32" ? left.toLowerCase() === right.toLowerCase() : left === right;
+}

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,97 @@
+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;
+    readonly peakMemoryBytes?: number;
+    readonly memorySampleCount?: number;
+    readonly memorySource?: string;
+    readonly memoryObservedAt?: 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;
+    providerMemoryTelemetry(): AttemptProcessTreeMemoryTelemetry | null;
+    private observeChildReady;
+    private settleChild;
+    private assertFence;
+    private persist;
+}
+export interface AttemptProcessTreeMemoryTelemetry {
+    readonly peakMemoryBytes: number;
+    readonly sampleCount: number;
+    readonly source: string;
+    readonly observedAt: string;
+}