@cat-factory/local-server 0.14.2 → 0.16.0

package/dist/LocalProcessRunnerTransport.d.ts

@@ -0,0 +1,63 @@
+import { spawn } from 'node:child_process';
+import type { RunnerDispatchKind, RunnerJobRef, RunnerJobView, RunnerTransport } from '@cat-factory/kernel';
+export interface LocalProcessRunnerTransportOptions {
+    /**
+     * Path to the executor-harness HTTP server entry (its `server.js`/`server.ts`). Spawned
+     * as `node <entry>`; with a `.ts` entry, Node's type-stripping (Node 24+) runs it.
+     */
+    harnessEntry: string;
+    /** Node executable to spawn the harness with. Default `process.execPath`. */
+    nodePath?: string;
+    /** Extra args to pass to node before the entry (e.g. `--experimental-strip-types`). */
+    nodeArgs?: string[];
+    /** Shared secret injected as `HARNESS_SHARED_SECRET` + sent on every call. Default random. */
+    sharedSecret?: string;
+    /** Extra env for the harness process (e.g. GITHUB_ALLOWED_HOSTS). */
+    env?: Record<string, string>;
+    /** Injectable fetch — defaults to the global. */
+    fetchImpl?: typeof fetch;
+    /** Injectable spawn — defaults to node:child_process.spawn (overridable in tests). */
+    spawnImpl?: typeof spawn;
+    /** Injectable free-port picker — defaults to an ephemeral OS port (overridable in tests). */
+    pickPort?: () => Promise<number>;
+    /** How long to wait for the harness `/health` after spawn. Default 30s. */
+    readyTimeoutMs?: number;
+    /** Per-HTTP-call timeout. Default 30s. */
+    requestTimeoutMs?: number;
+}
+export declare class LocalProcessRunnerTransport implements RunnerTransport {
+    private readonly harnessEntry;
+    private readonly nodePath;
+    private readonly nodeArgs;
+    private readonly sharedSecret;
+    private readonly extraEnv;
+    private readonly fetchImpl;
+    private readonly spawnImpl;
+    private readonly pickPort;
+    private readonly readyTimeoutMs;
+    private readonly requestTimeoutMs;
+    /** The single long-lived harness process, started lazily and reused across all runs. */
+    private proc;
+    private starting;
+    constructor(options: LocalProcessRunnerTransportOptions);
+    dispatch(ref: RunnerJobRef, spec: Record<string, unknown>, kind?: RunnerDispatchKind): Promise<void>;
+    poll(ref: RunnerJobRef): Promise<RunnerJobView>;
+    /**
+     * No per-run teardown: the harness host process is long-lived and reused across runs
+     * (the harness already removes each job's ephemeral workspace itself). Provided so the
+     * port contract is satisfied; kept idempotent.
+     */
+    release(): Promise<void>;
+    /** Stop the harness process (for shutdown / tests). Idempotent. */
+    shutdown(): Promise<void>;
+    private ensureProcess;
+    private startProcess;
+    private waitForHealth;
+}
+/**
+ * Build a {@link LocalProcessRunnerTransport} from the environment. Requires
+ * `LOCAL_HARNESS_ENTRY` (the path to the executor-harness server entry to run as a host
+ * process). The native CLIs (`claude` / `codex`) must already be installed on the host.
+ */
+export declare function createLocalProcessTransportFromEnv(env: NodeJS.ProcessEnv): LocalProcessRunnerTransport;
+//# sourceMappingURL=LocalProcessRunnerTransport.d.ts.map

package/dist/LocalProcessRunnerTransport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocalProcessRunnerTransport.d.ts","sourceRoot":"","sources":["../src/LocalProcessRunnerTransport.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,EAAE,MAAM,oBAAoB,CAAA;AAG7D,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,aAAa,EACb,eAAe,EAChB,MAAM,qBAAqB,CAAA;AA0B5B,MAAM,WAAW,kCAAkC;IACjD;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAA;IACpB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,uFAAuF;IACvF,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,8FAA8F;IAC9F,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,qEAAqE;IACrE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5B,iDAAiD;IACjD,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;IACxB,sFAAsF;IACtF,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;IACxB,6FAA6F;IAC7F,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;IAChC,2EAA2E;IAC3E,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,0CAA0C;IAC1C,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B;AAeD,qBAAa,2BAA4B,YAAW,eAAe;IACjE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAwB;IACjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuB;IAChD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAQ;IACvC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAQ;IAEzC,wFAAwF;IACxF,OAAO,CAAC,IAAI,CAAoE;IAChF,OAAO,CAAC,QAAQ,CAA6E;IAE7F,YAAY,OAAO,EAAE,kCAAkC,EAWtD;IAEK,QAAQ,CACZ,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,IAAI,GAAE,kBAA4B,GACjC,OAAO,CAAC,IAAI,CAAC,CAYf;IAEK,IAAI,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CAapD;IAED;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAE7B;IAED,mEAAmE;IAC7D,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAK9B;YAIa,aAAa;YAWb,YAAY;IAoC1B,OAAO,CAAC,aAAa;CAYtB;AAED;;;;GAIG;AACH,wBAAgB,kCAAkC,CAChD,GAAG,EAAE,MAAM,CAAC,UAAU,GACrB,2BAA2B,CAmB7B"}

package/dist/LocalProcessRunnerTransport.js

@@ -0,0 +1,188 @@
+import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { createServer } from 'node:net';
+import { EVICTION_ERROR, pollHarnessJob, postHarnessJob, waitForHarnessHealth, } from './harnessHttp.js';
+// The NATIVE local runner backend (opt-in via `LOCAL_NATIVE_AGENTS`): instead of a Docker
+// container per run, it runs the SAME executor-harness as a long-lived HOST PROCESS on
+// 127.0.0.1 and drives it through the harness's existing HTTP API. So all the harness
+// machinery — git clone/push/PR, structured-output, watchdogs, the JobRegistry, progress —
+// is reused unchanged; the only difference from the container transport is WHERE the harness
+// runs (a host `node` process vs a container) and that the agent uses the developer's OWN
+// installed `claude` / `codex` CLI with its ambient login (the executor sets `ambientAuth`
+// on the job, so no credential is leased). This bypasses Docker entirely.
+//
+// SECURITY: the agent runs as a plain host subprocess with the developer's full shell/file
+// access and their personal subscription — no container sandbox, no spend metering, no
+// model-locking. Acceptable ONLY because local mode is the developer's own machine; it is
+// therefore opt-in (default off) and reachable only from `buildLocalContainer`.
+/** The harness is always on loopback for the native host-process transport. */
+const endpointFor = (port) => ({ host: '127.0.0.1', port });
+/** An ephemeral free localhost port (best-effort; a tiny TOCTOU window is fine for dev). */
+function ephemeralPort() {
+    return new Promise((resolve, reject) => {
+        const srv = createServer();
+        srv.on('error', reject);
+        srv.listen(0, '127.0.0.1', () => {
+            const addr = srv.address();
+            const port = typeof addr === 'object' && addr ? addr.port : 0;
+            srv.close(() => (port ? resolve(port) : reject(new Error('could not pick a free port'))));
+        });
+    });
+}
+export class LocalProcessRunnerTransport {
+    harnessEntry;
+    nodePath;
+    nodeArgs;
+    sharedSecret;
+    extraEnv;
+    fetchImpl;
+    spawnImpl;
+    pickPort;
+    readyTimeoutMs;
+    requestTimeoutMs;
+    /** The single long-lived harness process, started lazily and reused across all runs. */
+    proc;
+    starting;
+    constructor(options) {
+        this.harnessEntry = options.harnessEntry;
+        this.nodePath = options.nodePath ?? process.execPath;
+        this.nodeArgs = options.nodeArgs ?? [];
+        this.sharedSecret = options.sharedSecret ?? randomBytes(24).toString('hex');
+        this.extraEnv = options.env ?? {};
+        this.fetchImpl = options.fetchImpl ?? fetch;
+        this.spawnImpl = options.spawnImpl ?? spawn;
+        this.pickPort = options.pickPort ?? ephemeralPort;
+        this.readyTimeoutMs = options.readyTimeoutMs ?? 30_000;
+        this.requestTimeoutMs = options.requestTimeoutMs ?? 30_000;
+    }
+    async dispatch(ref, spec, kind = 'agent') {
+        const proc = await this.ensureProcess();
+        // The harness keys jobs by the per-step `ref.jobId` in the body; a re-dispatch
+        // (durable-driver replay) re-POSTs, which the JobRegistry treats as a re-attach.
+        await postHarnessJob({
+            fetchImpl: this.fetchImpl,
+            endpoint: endpointFor(proc.port),
+            secret: this.sharedSecret,
+            body: { ...spec, kind },
+            timeoutMs: this.requestTimeoutMs,
+            label: 'Native harness',
+        });
+    }
+    async poll(ref) {
+        const proc = this.proc;
+        // The process died (or was never started) → report an eviction so the run can recover.
+        if (!proc || proc.exited)
+            return { state: 'failed', error: EVICTION_ERROR };
+        return pollHarnessJob({
+            fetchImpl: this.fetchImpl,
+            endpoint: endpointFor(proc.port),
+            jobId: ref.jobId,
+            secret: this.sharedSecret,
+            timeoutMs: this.requestTimeoutMs,
+            label: 'Native harness',
+            isDead: () => proc.exited,
+        });
+    }
+    /**
+     * No per-run teardown: the harness host process is long-lived and reused across runs
+     * (the harness already removes each job's ephemeral workspace itself). Provided so the
+     * port contract is satisfied; kept idempotent.
+     */
+    async release() {
+        // intentionally a no-op
+    }
+    /** Stop the harness process (for shutdown / tests). Idempotent. */
+    async shutdown() {
+        const proc = this.proc;
+        this.proc = undefined;
+        this.starting = undefined;
+        if (proc && !proc.exited)
+            proc.child.kill();
+    }
+    // --- internals ----------------------------------------------------------
+    async ensureProcess() {
+        if (this.proc && !this.proc.exited)
+            return this.proc;
+        this.starting ??= this.startProcess();
+        try {
+            this.proc = await this.starting;
+            return this.proc;
+        }
+        finally {
+            this.starting = undefined;
+        }
+    }
+    async startProcess() {
+        const port = await this.pickPort();
+        const child = this.spawnImpl(this.nodePath, [...this.nodeArgs, this.harnessEntry], {
+            env: {
+                ...process.env,
+                ...this.extraEnv,
+                PORT: String(port),
+                HARNESS_SHARED_SECRET: this.sharedSecret,
+                // The harness only auto-listens when NODE_ENV !== 'test'.
+                NODE_ENV: 'production',
+            },
+            stdio: 'ignore',
+        });
+        const handle = { child, port, exited: false };
+        // The harness child is long-lived and not detached, but Node does NOT auto-kill a
+        // child when the parent exits — without this, every dev restart orphans a `node
+        // <harness>` process still bound to its port (and possibly mid-run on the developer's
+        // live Claude/Codex login). `shutdown()` covers the graceful path; this `exit` hook is
+        // the backstop for SIGTERM/SIGINT/uncaught exits that reach `process.exit` directly.
+        const killOnParentExit = () => {
+            try {
+                child.kill();
+            }
+            catch {
+                // best-effort
+            }
+        };
+        process.once('exit', killOnParentExit);
+        child.on('exit', () => {
+            handle.exited = true;
+            process.removeListener('exit', killOnParentExit);
+            if (this.proc === handle)
+                this.proc = undefined;
+        });
+        await this.waitForHealth(port, handle);
+        return handle;
+    }
+    waitForHealth(port, handle) {
+        return waitForHarnessHealth({
+            fetchImpl: this.fetchImpl,
+            endpoint: endpointFor(port),
+            readyTimeoutMs: this.readyTimeoutMs,
+            requestTimeoutMs: this.requestTimeoutMs,
+            intervalMs: 200,
+            isDead: () => handle.exited,
+            deadError: 'the native harness process exited before becoming healthy',
+            timeoutError: `Timed out waiting for the native harness on 127.0.0.1:${port} to become healthy`,
+        });
+    }
+}
+/**
+ * Build a {@link LocalProcessRunnerTransport} from the environment. Requires
+ * `LOCAL_HARNESS_ENTRY` (the path to the executor-harness server entry to run as a host
+ * process). The native CLIs (`claude` / `codex`) must already be installed on the host.
+ */
+export function createLocalProcessTransportFromEnv(env) {
+    const harnessEntry = env.LOCAL_HARNESS_ENTRY?.trim();
+    if (!harnessEntry) {
+        throw new Error('LOCAL_HARNESS_ENTRY is required for native local mode (LOCAL_NATIVE_AGENTS): set it to ' +
+            'the executor-harness server entry path (its built server.js, or src/server.ts run via ' +
+            'Node type-stripping).');
+    }
+    const nodeArgs = env.LOCAL_HARNESS_NODE_ARGS?.trim()
+        ? env.LOCAL_HARNESS_NODE_ARGS.trim().split(/\s+/)
+        : undefined;
+    const allowedHosts = env.GITHUB_ALLOWED_HOSTS?.trim();
+    return new LocalProcessRunnerTransport({
+        harnessEntry,
+        ...(nodeArgs ? { nodeArgs } : {}),
+        sharedSecret: env.HARNESS_SHARED_SECRET?.trim() || undefined,
+        ...(allowedHosts ? { env: { GITHUB_ALLOWED_HOSTS: allowedHosts } } : {}),
+    });
+}
+//# sourceMappingURL=LocalProcessRunnerTransport.js.map

package/dist/LocalProcessRunnerTransport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocalProcessRunnerTransport.js","sourceRoot":"","sources":["../src/LocalProcessRunnerTransport.ts"],"names":[],"mappings":"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"}

package/dist/NativeRoutingRunnerTransport.d.ts

@@ -0,0 +1,20 @@
+import type { RunnerDispatchKind, RunnerDispatchOptions, RunnerJobRef, RunnerJobView, RunnerTransport } from '@cat-factory/kernel';
+export declare class NativeRoutingRunnerTransport implements RunnerTransport {
+    /** Host-process transport for ambient (native CLI) steps — built lazily, cached. */
+    private readonly ambient;
+    /** Per-run container transport for everything else — built lazily, cached (the
+     * container transport resolves its pool config from the DB, so this may be async). */
+    private readonly managed;
+    /** ref → the transport that handled its dispatch, so poll/release hit the same backend. */
+    private readonly routed;
+    constructor(
+    /** Host-process transport for ambient (native CLI) steps — built lazily, cached. */
+    ambient: () => RunnerTransport | Promise<RunnerTransport>, 
+    /** Per-run container transport for everything else — built lazily, cached (the
+     * container transport resolves its pool config from the DB, so this may be async). */
+    managed: () => RunnerTransport | Promise<RunnerTransport>);
+    dispatch(ref: RunnerJobRef, spec: Record<string, unknown>, kind?: RunnerDispatchKind, options?: RunnerDispatchOptions): Promise<void>;
+    poll(ref: RunnerJobRef): Promise<RunnerJobView>;
+    release(ref: RunnerJobRef): Promise<void>;
+}
+//# sourceMappingURL=NativeRoutingRunnerTransport.d.ts.map

package/dist/NativeRoutingRunnerTransport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NativeRoutingRunnerTransport.d.ts","sourceRoot":"","sources":["../src/NativeRoutingRunnerTransport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,qBAAqB,EACrB,YAAY,EACZ,aAAa,EACb,eAAe,EAChB,MAAM,qBAAqB,CAAA;AAqB5B,qBAAa,4BAA6B,YAAW,eAAe;IAKhE,oFAAoF;IACpF,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB;0FACsF;IACtF,OAAO,CAAC,QAAQ,CAAC,OAAO;IAR1B,2FAA2F;IAC3F,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqC;IAE5D;IACE,oFAAoF;IACnE,OAAO,EAAE,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;IAC1E;0FACsF;IACrE,OAAO,EAAE,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,EACxE;IAEE,QAAQ,CACZ,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,IAAI,GAAE,kBAA4B,EAClC,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,IAAI,CAAC,CAIf;IAEK,IAAI,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CAMpD;IAEK,OAAO,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAI9C;CACF"}

package/dist/NativeRoutingRunnerTransport.js

@@ -0,0 +1,50 @@
+// NATIVE-MODE transport router (local facade, `LOCAL_NATIVE_AGENTS`): native mode runs the
+// developer's OWN `claude` / `codex` CLI as a host process (no sandbox), which is only
+// appropriate for the steps that actually use that ambient login. The executor flags such a
+// step with `ambientAuth: true` on its job body; everything else (a proxy/`pi` model, or a
+// non-native vendor reusing the claude-code harness) MUST still run in a sandboxed per-run
+// container, exactly as the README promises ("proxy-only models still need the container
+// path"). Previously native mode sent EVERY dispatch to the host process, silently running
+// proxy-model steps unsandboxed.
+//
+// So this routes per JOB (not per run — a single run legitimately mixes an ambient Claude
+// step with a proxy step): `ambientAuth` jobs → the host-process transport; the rest → the
+// container transport (built lazily, so a native deployment that only runs Claude/Codex
+// never needs LOCAL_HARNESS_IMAGE; a proxy step without an image fails loudly there). The
+// chosen transport is remembered per ref so poll/release reach the same backend.
+const EVICTION_ERROR = 'Job not found (container evicted or crashed)';
+const refKey = (ref) => `${ref.runId}:${ref.jobId}`;
+export class NativeRoutingRunnerTransport {
+    ambient;
+    managed;
+    /** ref → the transport that handled its dispatch, so poll/release hit the same backend. */
+    routed = new Map();
+    constructor(
+    /** Host-process transport for ambient (native CLI) steps — built lazily, cached. */
+    ambient, 
+    /** Per-run container transport for everything else — built lazily, cached (the
+     * container transport resolves its pool config from the DB, so this may be async). */
+    managed) {
+        this.ambient = ambient;
+        this.managed = managed;
+    }
+    async dispatch(ref, spec, kind = 'agent', options) {
+        const transport = await (spec.ambientAuth === true ? this.ambient() : this.managed());
+        this.routed.set(refKey(ref), transport);
+        await transport.dispatch(ref, spec, kind, options);
+    }
+    async poll(ref) {
+        // Unknown ref (a fresh process after a durable replay): report an eviction so the
+        // sweeper re-drives — the re-dispatch (idempotent) re-populates the routing map.
+        const transport = this.routed.get(refKey(ref));
+        if (!transport)
+            return { state: 'failed', error: EVICTION_ERROR };
+        return transport.poll(ref);
+    }
+    async release(ref) {
+        const transport = this.routed.get(refKey(ref));
+        this.routed.delete(refKey(ref));
+        await transport?.release?.(ref);
+    }
+}
+//# sourceMappingURL=NativeRoutingRunnerTransport.js.map

package/dist/NativeRoutingRunnerTransport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NativeRoutingRunnerTransport.js","sourceRoot":"","sources":["../src/NativeRoutingRunnerTransport.ts"],"names":[],"mappings":"AAQA,2FAA2F;AAC3F,uFAAuF;AACvF,4FAA4F;AAC5F,2FAA2F;AAC3F,2FAA2F;AAC3F,yFAAyF;AACzF,2FAA2F;AAC3F,iCAAiC;AACjC,EAAE;AACF,0FAA0F;AAC1F,2FAA2F;AAC3F,wFAAwF;AACxF,0FAA0F;AAC1F,iFAAiF;AAEjF,MAAM,cAAc,GAAG,8CAA8C,CAAA;AAErE,MAAM,MAAM,GAAG,CAAC,GAAiB,EAAU,EAAE,CAAC,GAAG,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,KAAK,EAAE,CAAA;AAEzE,MAAM,OAAO,4BAA4B;IAMpB,OAAO;IAGP,OAAO;IAR1B,2FAA2F;IAC1E,MAAM,GAAG,IAAI,GAAG,EAA2B,CAAA;IAE5D;IACE,oFAAoF;IACnE,OAAyD;IAC1E;0FACsF;IACrE,OAAyD;uBAHzD,OAAO;uBAGP,OAAO;IACvB,CAAC;IAEJ,KAAK,CAAC,QAAQ,CACZ,GAAiB,EACjB,IAA6B,EAC7B,IAAI,GAAuB,OAAO,EAClC,OAA+B;QAE/B,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,WAAW,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAA;QACrF,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,SAAS,CAAC,CAAA;QACvC,MAAM,SAAS,CAAC,QAAQ,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,CAAA;IACpD,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,GAAiB;QAC1B,kFAAkF;QAClF,iFAAiF;QACjF,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAA;QAC9C,IAAI,CAAC,SAAS;YAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,cAAc,EAAE,CAAA;QACjE,OAAO,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IAC5B,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,GAAiB;QAC7B,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAA;QAC9C,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAA;QAC/B,MAAM,SAAS,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,CAAA;IACjC,CAAC;CACF"}

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAgBpD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,CAuB5E;AAED,qEAAqE;AACrE,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,SAAS,CAEjE"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAgBpD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,CA6B5E;AAED,qEAAqE;AACrE,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,SAAS,CAEjE"}

package/dist/config.js

@@ -38,6 +38,12 @@ export function applyLocalDefaults(env) {
         // alias routes back to this service on the host. The docker-family transport
         // publishes that alias on Linux via `--add-host=<alias>:host-gateway`.
         PUBLIC_URL: env.PUBLIC_URL?.trim() || `http://${hostAlias}:${port}`,
+        // Assemble the ephemeral-environment module by default so the Tester's "delegate test
+        // environments to a provider" opt-in works once a developer registers a provider — the
+        // module is inert (and the local default stays host DinD) until they connect one AND
+        // flip the toggle, so defaulting it on has no behavioural cost. Set ENVIRONMENTS_ENABLED
+        // explicitly to override.
+        ENVIRONMENTS_ENABLED: env.ENVIRONMENTS_ENABLED?.trim() || 'true',
     };
 }
 /** The shared {@link AppConfig} with local-mode defaults applied. */

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAEzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAEtD,mFAAmF;AACnF,mFAAmF;AACnF,gDAAgD;AAChD,iFAAiF;AACjF,+DAA+D;AAC/D,uFAAuF;AACvF,6EAA6E;AAC7E,oFAAoF;AACpF,yDAAyD;AACzD,wEAAwE;AAExE,MAAM,YAAY,GAAG,MAAM,CAAA;AAE3B;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAsB;IACvD,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,YAAY,CAAA;IAC7C,gFAAgF;IAChF,qFAAqF;IACrF,qFAAqF;IACrF,MAAM,SAAS,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAA;IACvC,OAAO;QACL,GAAG,GAAG;QACN,oFAAoF;QACpF,sFAAsF;QACtF,aAAa,EAAE,GAAG,CAAC,aAAa,EAAE,IAAI,EAAE,IAAI,MAAM;QAClD,+EAA+E;QAC/E,mBAAmB,EAAE,GAAG,CAAC,mBAAmB,EAAE,IAAI,EAAE,IAAI,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC;QACvF,mFAAmF;QACnF,qFAAqF;QACrF,sFAAsF;QACtF,gFAAgF;QAChF,cAAc,EAAE,GAAG,CAAC,cAAc,EAAE,IAAI,EAAE,IAAI,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAChF,qFAAqF;QACrF,6EAA6E;QAC7E,uEAAuE;QACvE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,IAAI,EAAE,IAAI,UAAU,SAAS,IAAI,IAAI,EAAE;KACpE,CAAA;AACH,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,eAAe,CAAC,GAAsB;IACpD,OAAO,cAAc,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAA;AAChD,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAEzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAEtD,mFAAmF;AACnF,mFAAmF;AACnF,gDAAgD;AAChD,iFAAiF;AACjF,+DAA+D;AAC/D,uFAAuF;AACvF,6EAA6E;AAC7E,oFAAoF;AACpF,yDAAyD;AACzD,wEAAwE;AAExE,MAAM,YAAY,GAAG,MAAM,CAAA;AAE3B;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAsB;IACvD,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,YAAY,CAAA;IAC7C,gFAAgF;IAChF,qFAAqF;IACrF,qFAAqF;IACrF,MAAM,SAAS,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAA;IACvC,OAAO;QACL,GAAG,GAAG;QACN,oFAAoF;QACpF,sFAAsF;QACtF,aAAa,EAAE,GAAG,CAAC,aAAa,EAAE,IAAI,EAAE,IAAI,MAAM;QAClD,+EAA+E;QAC/E,mBAAmB,EAAE,GAAG,CAAC,mBAAmB,EAAE,IAAI,EAAE,IAAI,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC;QACvF,mFAAmF;QACnF,qFAAqF;QACrF,sFAAsF;QACtF,gFAAgF;QAChF,cAAc,EAAE,GAAG,CAAC,cAAc,EAAE,IAAI,EAAE,IAAI,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAChF,qFAAqF;QACrF,6EAA6E;QAC7E,uEAAuE;QACvE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,IAAI,EAAE,IAAI,UAAU,SAAS,IAAI,IAAI,EAAE;QACnE,sFAAsF;QACtF,uFAAuF;QACvF,qFAAqF;QACrF,yFAAyF;QACzF,0BAA0B;QAC1B,oBAAoB,EAAE,GAAG,CAAC,oBAAoB,EAAE,IAAI,EAAE,IAAI,MAAM;KACjE,CAAA;AACH,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,eAAe,CAAC,GAAsB;IACpD,OAAO,cAAc,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAA;AAChD,CAAC"}

package/dist/container.d.ts

@@ -1,4 +1,17 @@
 import type { NodeContainerOptions } from '@cat-factory/node-server';
 import type { ServerContainer } from '@cat-factory/server';
+import type { HarnessKind } from '@cat-factory/kernel';
 export declare function buildLocalContainer(options: NodeContainerOptions): ServerContainer;
+/**
+ * Parse `LOCAL_NATIVE_AGENTS` into the set of subscription harnesses to run natively. The
+ * documented form is a comma-separated list of harness ids (`claude-code,codex`); `claude`
+ * is accepted as an alias for `claude-code`. Blank/unset OR an explicit off value
+ * (`false`/`0`/`off`/`no`/`none`/`disabled`) ⇒ off (`[]`) — so disabling native mode never
+ * accidentally enables it. An affirmative value naming no harness (`true`/`1`/`on`/…) ⇒ BOTH
+ * native harnesses. Only `claude-code` / `codex` are ever native; any other unrecognised
+ * token is ignored. A value with neither a recognised harness nor an affirmative keyword
+ * (e.g. a typo) ⇒ off, so an unintelligible setting fails safe rather than enabling an
+ * unsandboxed, unmetered mode.
+ */
+export declare function parseNativeHarnesses(raw: string | undefined): HarnessKind[];
 //# sourceMappingURL=container.d.ts.map

package/dist/container.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"container.d.ts","sourceRoot":"","sources":["../src/container.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAA;AACpE,OAAO,KAAK,EAAqC,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAyB7F,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,eAAe,CAiFlF"}
+{"version":3,"file":"container.d.ts","sourceRoot":"","sources":["../src/container.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAA;AAIpE,OAAO,KAAK,EAAqC,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAG7F,OAAO,KAAK,EAAE,WAAW,EAAmB,MAAM,qBAAqB,CAAA;AAuCvE,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,eAAe,CA2RlF;AAOD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,WAAW,EAAE,CAc3E"}