@nylorun/runtime 0.15.2-beta → 0.17.0-beta

package/dist/harness/executors.js

@@ -0,0 +1,96 @@
+/**
+ * A harness's executors (F6.1, F6.2): the model route, the Tool Gate, an MCP pool and a
+ * SandboxManager, injected. They reach no store: a run's routing comes with its `turn.start`,
+ * and the session's MCP discovery is recorded through core (`session.mcp`, `prepare`).
+ *
+ * The in-process harness gets the Tenant's own pool and SandboxManager; a harness process
+ * (`--service harness`, `main.ts`) its own, whose sandbox events it claims from core.
+ */
+import { hashManifest } from "@nylorun/core/define";
+import { toolFixtureModel } from "../core/provider.js";
+import { serversOf } from "../mcp/pool.js";
+import { mcpToolOf } from "../mcp/snapshot.js";
+import { abortOn, callMcpTool, callSandboxTool, invokeModel, isRemoteMcpCall, isSaveArtifactCall, } from "./calls.js";
+/** The Tenant's model of the fixture-model setting. Stateless. */
+const fixture = toolFixtureModel();
+export function harnessExecutors(options) {
+    const recoversMcp = options.toolGate.recovers === true;
+    const remote = (effect, run) => recoversMcp && isRemoteMcpCall(routingOf(run), effect);
+    return {
+        model: (effect, signal, run) => invokeModel(options.model, effect, signal, run.start.options.fixtureModel ? fixture : undefined),
+        tool(effect, signal, run) {
+            const routing = routingOf(run);
+            if (!mcpToolOf(routing.mcpSnapshot, effect))
+                return callSandboxTool(options.sandbox(), routing, effect, signal);
+            // A call at the Tool Gate outlives a shutdown there; a local one finishes and is recorded.
+            const kinds = remote(effect, run) ? ["cancel", "shutdown"] : ["cancel"];
+            return callMcpTool(options.mcp, routing, effect, abortOn(signal, kinds));
+        },
+        recovers: {
+            get model() {
+                return options.model.useVaultModel && options.model.modelGate.recovers === true;
+            },
+            remoteMcp: remote,
+        },
+        async cancelAtGate(effect) {
+            await options.toolGate.cancel?.({
+                tenantId: options.model.tenantId,
+                sessionId: effect.sessionId,
+                effectId: effect.effectId,
+            });
+        },
+        prepare: (run, record) => prepareMcp(options.mcp, run, record),
+    };
+}
+/**
+ * Readies the run's MCP servers (§10.5 step 3): the first segment of a session discovers their
+ * tools and records the snapshot (the first recorded wins); later ones reconnect them and record
+ * what failed. Nothing for a session without MCP servers.
+ */
+export async function prepareMcp(pool, run, record) {
+    const routing = routingOf(run);
+    const manifest = routing.rootManifest;
+    if (serversOf(manifest).length === 0)
+        return undefined;
+    const sessionId = run.grant.sessionId;
+    let answer;
+    if (!routing.mcpSnapshot) {
+        const found = await pool.discover({
+            sessionId,
+            manifest,
+            manifestHash: hashManifest(manifest),
+            pluginRoots: routing.pluginRoots,
+            signal: run.signal,
+        });
+        answer = await record({ snapshot: found.snapshot, diagnostics: found.diagnostics });
+    }
+    else {
+        const diagnostics = await pool.reconnect({
+            sessionId,
+            manifest,
+            pluginRoots: routing.pluginRoots,
+            tools: routing.mcpSnapshot.mcpTools,
+            signal: run.signal,
+        });
+        if (diagnostics.length === 0)
+            return undefined;
+        answer = await record({ diagnostics });
+    }
+    return {
+        sessionTools: answer.sessionTools,
+        ...(answer.snapshot === undefined ? {} : { mcpSnapshot: answer.snapshot }),
+    };
+}
+/** A run's routing, as the call helpers take it. Its sandbox events are claimed for the run. */
+export function routingOf(run) {
+    const { routing } = run.start;
+    return {
+        rootManifest: routing.rootManifest,
+        pluginRoots: routing.pluginRoots,
+        ...(routing.mcpSnapshot ? { mcpSnapshot: routing.mcpSnapshot } : {}),
+        sandboxOwnerId: routing.sandbox?.ownerId ?? run.grant.sessionId,
+        ...(routing.sandbox?.sandboxId === undefined ? {} : { sandboxId: routing.sandbox.sandboxId }),
+        activeTurnId: run.grant.turnId,
+        claim: run.runId,
+    };
+}

package/dist/harness/main.d.ts

@@ -0,0 +1,6 @@
+import type { StackConfig } from "../host/stack-config.js";
+/**
+ * `baseline` is the allowlisted environment of MCP stdio servers (`baselineEnvironment`), read
+ * by `host/main.ts`: nothing here reads the process environment.
+ */
+export declare function runHarness(stack: StackConfig, baseline: Readonly<Record<string, string>>): Promise<void>;

package/dist/harness/main.js

@@ -0,0 +1,103 @@
+/**
+ * The harness service (`--service harness`, F6.2): the process that runs the Tenant's agent
+ * segments, MCP servers and sandboxes, apart from core. It holds one credential, the harness
+ * token, for core's Harness API; its model and MCP calls present the run token of the run they
+ * belong to (from the `lease` answer and each renewal), never the gates' credential. It opens no
+ * database, no Restate, no keys.
+ *
+ * Its files live under `NYLORUN_HARNESS_ROOT` (`/harness`): `sandboxes/` (workspaces and their
+ * records), `plugin-data/`, and `home/` and `tmp/` for MCP stdio servers. `/health` answers on
+ * 127.0.0.1 only.
+ *
+ * In a pod sandbox (`NYLORUN_SANDBOX_KIND=pod`, F7.2) it is that sandbox's engine: it first waits
+ * until the pod's NetworkPolicy is in force (`awaitNetworkPolicy`), then joins with the
+ * pod's join token instead of a harness token (`pod.ts`), and runs its sandbox's tools in the
+ * pod itself (the `local` backend), with egress through egress-gate. SIGTERM (tini forwards
+ * it; the pod's grace is 10 s by default) gives its runs back and exits.
+ */
+import { mkdirSync } from "node:fs";
+import { createServer } from "node:http";
+import { join } from "node:path";
+import { httpModelGate } from "../gates/http-client.js";
+import { httpToolGate } from "../gates/tool-client.js";
+import { createHostLogger } from "../host/logger.js";
+import { RUNTIME_VERSION } from "../version.js";
+import { localBackend } from "../adapters/sandbox/local.js";
+import { awaitNetworkPolicy } from "../sandbox/pods/network-gate.js";
+import { podHost } from "./pod.js";
+import { harnessRunTokens } from "./run-tokens.js";
+import { startHarnessService } from "./service.js";
+/**
+ * `baseline` is the allowlisted environment of MCP stdio servers (`baselineEnvironment`), read
+ * by `host/main.ts`: nothing here reads the process environment.
+ */
+export async function runHarness(stack, baseline) {
+    const config = stack.harness;
+    const logger = createHostLogger();
+    const paths = {
+        sandboxes: join(config.root, "sandboxes"),
+        pluginData: join(config.root, "plugin-data"),
+        home: join(config.root, "home"),
+        tmp: join(config.root, "tmp"),
+    };
+    for (const dir of Object.values(paths))
+        mkdirSync(dir, { recursive: true });
+    logger.info("host_stack_config", { services: [...stack.services], harness: config.url, gates: config.gatesUrl });
+    // A pod's engine trusts the network only once its NetworkPolicy blocks what it must.
+    let pod;
+    if (config.pod) {
+        const { waitedMs } = await awaitNetworkPolicy({
+            addresses: config.pod.blocked,
+            log: (message, fields) => logger.info(message, fields),
+        });
+        logger.info("sandbox_network_policy_in_force", { sandboxId: config.pod.sandboxId, waitedMs });
+        pod = podHost(config.pod, logger, { volumeFile: join(config.root, "volume-id") });
+    }
+    const token = pod ? () => pod.token() : config.token;
+    if (token === undefined)
+        throw new Error("--service harness needs NYLORUN_HARNESS_TOKEN");
+    const runTokens = harnessRunTokens();
+    const service = startHarnessService({
+        url: config.url,
+        token,
+        ...(pod ? { sandboxBackends: [localBackend({ env: baseline, proxyEnv: () => pod.proxyEnv() })] } : {}),
+        paths,
+        childEnv: { ...baseline, HOME: paths.home, TMPDIR: paths.tmp },
+        modelGate: httpModelGate({ url: config.gatesUrl, runTokens }),
+        useVaultModel: true,
+        toolGate: httpToolGate({ url: config.gatesUrl, runTokens }),
+        logger,
+        name: pod ? `sandbox ${config.pod.sandboxId}` : "harness",
+        version: RUNTIME_VERSION,
+        onGrant: (grant) => runTokens.grant(grant),
+    });
+    const health = createServer((request, response) => {
+        if (request.url !== "/health") {
+            response.writeHead(404).end();
+            return;
+        }
+        response.writeHead(200, { "content-type": "application/json" });
+        response.end(JSON.stringify({ status: "ok", service: "nylorun-harness", connected: service.client.connected }));
+    });
+    await new Promise((resolve, reject) => {
+        health.once("error", reject);
+        health.listen(config.healthPort, "127.0.0.1", () => resolve());
+    });
+    logger.info("harness_ready", { health: `http://127.0.0.1:${config.healthPort}/health` });
+    let stopping = false;
+    for (const signal of ["SIGINT", "SIGTERM"])
+        process.on(signal, () => {
+            if (stopping)
+                return;
+            stopping = true;
+            // Runs are given back (core resumes them in its next advance), then MCP and sandboxes stop.
+            pod?.stop();
+            void service
+                .stop(pod ? 7_000 : 10_000)
+                .catch((error) => logger.warn("harness_stop_failed", { message: error instanceof Error ? error.message : String(error) }))
+                .finally(() => {
+                health.close();
+                process.exit(0);
+            });
+        });
+}

package/dist/harness/pod.d.ts

@@ -0,0 +1,21 @@
+import type { PodHostConfig } from "../host/stack-config.js";
+/** How often the host and egress tokens are renewed. */
+export declare const RENEW_MS: number;
+export interface PodHost {
+    /** A current host token, for the next connection. Throws when neither renewal nor join works. */
+    token(): Promise<string>;
+    /** `HTTPS_PROXY` and friends with the current egress token; none before the first join. */
+    proxyEnv(): Record<string, string>;
+    /** The host epoch of the tokens held. */
+    readonly epoch: number | undefined;
+    stop(): void;
+}
+export declare function podHost(config: PodHostConfig, logger: {
+    info(message: string, fields?: Record<string, unknown>): void;
+    warn(message: string, fields?: Record<string, unknown>): void;
+}, options?: {
+    fetch?: typeof fetch;
+    renewMs?: number;
+    /** Where the engine keeps the volume's id (on the volume): a new volume gets a new one. */
+    volumeFile?: string;
+}): PodHost;

package/dist/harness/pod.js

@@ -0,0 +1,119 @@
+/**
+ * The engine in a pod sandbox (F7.2, D42): its credentials. It holds no harness token. Before
+ * each connection to the Harness API it renews its host token (`host/renew`), or, with none or
+ * one refused (its epoch moved), exchanges the join token mounted in the pod (`host/join`,
+ * read afresh each time: a reset writes a new one). The egress token minted with the host token
+ * is the password of the proxy every command gets (`proxyEnv`); both are renewed every
+ * `RENEW_MS`, well inside their 15-minute life.
+ */
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+/** How often the host and egress tokens are renewed. */
+export const RENEW_MS = 5 * 60_000;
+class Refused extends Error {
+}
+export function podHost(config, logger, options = {}) {
+    const call = options.fetch ?? fetch;
+    let held;
+    const post = async (path, init) => {
+        const response = await call(`${config.httpUrl}/nylorun/harness/v1/host/${path}`, {
+            method: "POST",
+            headers: {
+                ...(init.body === undefined ? {} : { "content-type": "application/json" }),
+                ...(init.bearer ? { authorization: `Bearer ${init.bearer}` } : {}),
+            },
+            ...(init.body === undefined ? {} : { body: JSON.stringify(init.body) }),
+            signal: AbortSignal.timeout(15_000),
+        });
+        const text = await response.text();
+        if (response.status === 401 || response.status === 400)
+            throw new Refused(`host/${path} refused: ${response.status}`);
+        if (!response.ok)
+            throw new Error(`host/${path} answered ${response.status}`);
+        const body = JSON.parse(text);
+        return {
+            hostToken: body.hostToken,
+            egressToken: body.egressToken,
+            epoch: body.epoch,
+            expiresAt: Date.parse(body.expiresAt),
+        };
+    };
+    /** The volume's id, created on a volume that has none. */
+    const volumeId = async () => {
+        const file = options.volumeFile;
+        if (!file)
+            return undefined;
+        try {
+            return (await readFile(file, "utf8")).trim();
+        }
+        catch {
+            const id = randomUUID();
+            await mkdir(dirname(file), { recursive: true });
+            await writeFile(file, `${id}\n`, { mode: 0o600 });
+            return id;
+        }
+    };
+    const join = async () => {
+        const joinToken = (await readFile(config.joinFile, "utf8")).trim();
+        const volume = await volumeId();
+        held = await post("join", {
+            body: {
+                sandboxId: config.sandboxId,
+                podUid: config.podUid,
+                joinToken,
+                ...(volume === undefined ? {} : { volumeId: volume }),
+            },
+        });
+        logger.info("sandbox_host_joined", { sandboxId: config.sandboxId, epoch: held.epoch });
+        return held;
+    };
+    const renew = async () => {
+        if (!held)
+            return undefined;
+        try {
+            held = await post("renew", { bearer: held.hostToken });
+            return held;
+        }
+        catch (error) {
+            if (error instanceof Refused) {
+                logger.warn("sandbox_host_renew_refused", { sandboxId: config.sandboxId, epoch: held.epoch });
+                held = undefined;
+                return undefined;
+            }
+            throw error;
+        }
+    };
+    const timer = setInterval(() => {
+        void renew().catch((error) => logger.warn("sandbox_host_renew_failed", { message: error instanceof Error ? error.message : String(error) }));
+    }, options.renewMs ?? RENEW_MS);
+    timer.unref();
+    return {
+        async token() {
+            const current = (await renew()) ?? (await join());
+            return current.hostToken;
+        },
+        proxyEnv() {
+            if (!config.egressProxy || !held)
+                return {};
+            const url = new URL(config.egressProxy);
+            url.username = "nylorun";
+            url.password = held.egressToken;
+            const proxy = url.toString().replace(/\/$/, "");
+            return {
+                HTTPS_PROXY: proxy,
+                HTTP_PROXY: proxy,
+                https_proxy: proxy,
+                http_proxy: proxy,
+                NO_PROXY: "localhost,127.0.0.1",
+                no_proxy: "localhost,127.0.0.1",
+            };
+        },
+        get epoch() {
+            return held?.epoch;
+        },
+        stop() {
+            clearInterval(timer);
+        },
+    };
+}

package/dist/harness/run-tokens.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The run tokens of a harness process (F5, F6.2): the credential of its model and MCP calls at
+ * the gates. Each comes with a run (the `lease` answer's grant) or a renewal (`lease.renew`);
+ * the HTTP gate clients read a session's token on every request (`RunTokens`).
+ *
+ * A session's last token is kept after its run ends, so a pooled MCP connection closed later
+ * (idle, or at shutdown) still presents one: a close the gate refuses is ignored, and the
+ * gateway's own idle timeout closes the rest. A harness never holds `NYLORUN_GATES_TOKEN`.
+ */
+import type { RunGrant } from "@nylorun/core/harness-api";
+export interface HarnessRunTokens {
+    /** The latest run token of `sessionId`, if a run of it was ever leased here. */
+    token(sessionId: string): string | undefined;
+    /** Keeps a run's grant: `createHarness({ onGrant })`. */
+    grant(grant: RunGrant): void;
+}
+/** Remembers the last token of at most `limit` sessions (least recently granted dropped first). */
+export declare function harnessRunTokens(limit?: number): HarnessRunTokens;

package/dist/harness/run-tokens.js

@@ -0,0 +1,15 @@
+/** Remembers the last token of at most `limit` sessions (least recently granted dropped first). */
+export function harnessRunTokens(limit = 10_000) {
+    const tokens = new Map();
+    return {
+        token: (sessionId) => tokens.get(sessionId),
+        grant(grant) {
+            if (!grant.token)
+                return;
+            tokens.delete(grant.sessionId);
+            tokens.set(grant.sessionId, grant.token);
+            if (tokens.size > limit)
+                tokens.delete(tokens.keys().next().value);
+        },
+    };
+}

package/dist/harness/service.d.ts

@@ -0,0 +1,46 @@
+import type { HarnessOptions } from "@nylorun/harness/api";
+import type { ModelProvider } from "../core/provider.js";
+import type { ModelGate } from "../gates/model-gate.js";
+import type { ToolGate } from "../gates/tool-gate.js";
+import { McpPool } from "../mcp/pool.js";
+import type { SandboxBackend } from "../sandbox/types.js";
+import { type HarnessClient, type HarnessClientOptions } from "./ws-client.js";
+export interface HarnessServiceOptions {
+    readonly url: string;
+    readonly token: HarnessClientOptions["token"];
+    /** Where workspaces (and their records) live, and the plugins' data. */
+    readonly paths: {
+        readonly sandboxes: string;
+        readonly pluginData: string;
+    };
+    /** The environment of MCP stdio servers: the allowlisted base, with HOME and TMPDIR. */
+    readonly childEnv: Readonly<Record<string, string>>;
+    /** Vault-backed model calls (the gates service's client). */
+    readonly modelGate: ModelGate;
+    /** Models served without the vault; a harness process has none (`useVaultModel`). */
+    readonly modelProvider?: ModelProvider;
+    readonly useVaultModel: boolean;
+    /** Remote MCP servers (`openMcp`) and keyed cancels; the gates service's client. */
+    readonly toolGate: Pick<ToolGate, "recovers" | "cancel" | "openMcp">;
+    /**
+     * Authorizes a remote MCP server opened in this process. A harness process has no vault: it
+     * opens remote servers through the Tool Gate, and refuses them without one.
+     */
+    readonly authorize?: ConstructorParameters<typeof McpPool>[0]["authorize"];
+    /** Default: the virtual backend under `paths.sandboxes`. */
+    readonly sandboxBackends?: readonly SandboxBackend[];
+    /** Delete the workspaces on stop (an ephemeral Runtime's loopback harness). */
+    readonly ephemeral?: boolean;
+    readonly logger: HarnessClientOptions["logger"];
+    readonly name?: string;
+    readonly version?: string;
+    readonly onGrant?: HarnessOptions["onGrant"];
+    readonly backoff?: HarnessClientOptions["backoff"];
+    readonly liveness?: HarnessClientOptions["liveness"];
+}
+export interface HarnessService {
+    readonly client: HarnessClient;
+    /** Stops leasing and gives runs back (at most `waitMs`), then closes MCP and sandboxes. */
+    stop(waitMs?: number): Promise<void>;
+}
+export declare function startHarnessService(options: HarnessServiceOptions): HarnessService;

package/dist/harness/service.js

@@ -0,0 +1,179 @@
+/**
+ * A harness service (F6.2): a harness that runs the Tenant's segments and serves its workspaces
+ * over the Harness API, with its own MCP pool and SandboxManager, and no store. `main.ts` runs
+ * one as `--service harness`; a Tenant opened with `harness: "ws"` (tests) runs one in its own
+ * process over a loopback WebSocket.
+ *
+ * It learns its Tenant and the sandbox backend preference from core's answer to `hello`, and
+ * only then creates its SandboxManager: workspace keys are scoped by the Tenant. The manager
+ * keeps its compute records in `<sandboxes>/records.json` and claims its events from core
+ * (`event`): for the run that made the call, or the workspace request core sent.
+ */
+import { join } from "node:path";
+import { HarnessApiError, } from "@nylorun/core/harness-api";
+import { McpPool } from "../mcp/pool.js";
+import { SandboxManager } from "../sandbox/manager.js";
+import { fileSandboxRecords, workspacePrefix } from "../sandbox/records.js";
+import { defaultSandboxBackends } from "../sandbox/select.js";
+import { harnessExecutors } from "./executors.js";
+import { connectHarness } from "./ws-client.js";
+/** Which request runs each sandbox tool. */
+const METHODS = {
+    bash: "workspace.exec",
+    read: "workspace.read",
+    grep: "workspace.read",
+    glob: "workspace.read",
+    write: "workspace.write",
+    edit: "workspace.write",
+};
+/** How often the harness closes MCP connections idle past their timeout. */
+const MCP_SWEEP_MS = 60_000;
+/** The SandboxManager's view of the session a workspace request acts for. */
+function refOf(session) {
+    return {
+        id: session.ownerId,
+        activeTurnId: session.activeTurnId,
+        ...(session.sandboxId === undefined ? {} : { sandboxId: session.sandboxId }),
+    };
+}
+const noModel = async () => {
+    throw new Error("This harness calls models only through the gates service");
+};
+export function startHarnessService(options) {
+    const { logger } = options;
+    const backends = options.sandboxBackends ?? defaultSandboxBackends({ root: options.paths.sandboxes });
+    let tenantId = "";
+    let manager;
+    let client;
+    const sandbox = () => {
+        if (!manager)
+            throw new HarnessApiError("unavailable", "The harness has not said hello yet");
+        return manager;
+    };
+    const pool = new McpPool({
+        pluginData: options.paths.pluginData,
+        childEnv: options.childEnv,
+        authorize: options.authorize ??
+            (async () => {
+                throw new Error("This harness opens remote MCP servers only through the gates service");
+            }),
+        ...(options.toolGate.openMcp ? { openRemote: (server) => options.toolGate.openMcp(server) } : {}),
+    });
+    const sweep = setInterval(() => void pool.sweep().catch(() => undefined), MCP_SWEEP_MS);
+    sweep.unref();
+    const executors = harnessExecutors({
+        model: {
+            get tenantId() {
+                return tenantId;
+            },
+            modelGate: options.modelGate,
+            modelProvider: options.modelProvider ?? noModel,
+            useVaultModel: options.useVaultModel,
+        },
+        toolGate: options.toolGate,
+        mcp: pool,
+        sandbox,
+    });
+    const serve = async (method, params, signal) => {
+        switch (method) {
+            case "workspace.read":
+            case "workspace.write":
+            case "workspace.exec": {
+                if (method === "workspace.read" && "list" in params) {
+                    const call = params;
+                    return sandbox().listFiles(refOf(call.session), { id: "sandbox", type: "agent", sandbox: call.spec, tools: [] }, call.list.dir, call.list.maxEntries, signal);
+                }
+                if (method === "workspace.read" && "bytes" in params) {
+                    const call = params;
+                    const read = await sandbox().readBytes(refOf(call.session), { id: "sandbox", type: "agent", sandbox: call.spec, tools: [] }, call.bytes.path, call.bytes.maxBytes, signal);
+                    return read.kind === "read"
+                        ? { kind: "read", path: read.path, base64: Buffer.from(read.bytes).toString("base64") }
+                        : read;
+                }
+                const call = params;
+                if (METHODS[call.tool] !== method)
+                    throw new HarnessApiError("invalid", `${method} does not run ${call.tool}`);
+                return sandbox().run(refOf(call.session), { id: "sandbox", type: "agent", sandbox: call.spec, tools: [] }, call.tool, call.input, signal);
+            }
+            case "workspace.report":
+                return sandbox().report();
+            case "workspace.sweep": {
+                const { now } = params;
+                await sandbox().stopIdle(now);
+                return { workspaces: await sandbox().workspaces() };
+            }
+            case "workspace.remove": {
+                const { keys, sandboxIds, all } = params;
+                const workspaces = sandbox();
+                if (all) {
+                    await workspaces.reconcile(() => false, () => false);
+                    for (const record of await workspaces.workspaces())
+                        await workspaces.remove(record.key);
+                }
+                for (const key of keys ?? []) {
+                    if (!key.startsWith(workspacePrefix(tenantId)))
+                        throw new HarnessApiError("invalid", `${key} is not a workspace of this Tenant`);
+                    await workspaces.remove(key);
+                }
+                for (const id of sandboxIds ?? [])
+                    await workspaces.removeSandbox(id);
+                return {};
+            }
+            default:
+                throw new HarnessApiError("invalid", `Unknown request ${method}`);
+        }
+    };
+    client = connectHarness({
+        url: options.url,
+        token: options.token,
+        logger,
+        executors,
+        serve,
+        name: options.name ?? "harness",
+        ...(options.version ? { version: options.version } : {}),
+        capabilities: { workspace: { backends: backends.map((backend) => backend.name) } },
+        onHello(answer) {
+            tenantId = answer.tenantId;
+            manager ??= new SandboxManager({
+                scope: answer.tenantId,
+                records: fileSandboxRecords(join(options.paths.sandboxes, "records.json")),
+                backends,
+                preference: answer.sandbox.backend ?? "auto",
+                ephemeral: options.ephemeral === true,
+                // A claim core refuses (its run ended, the session is gone) is dropped, as core's own
+                // SandboxManager drops an event it cannot write.
+                emit: async (sessionId, turnId, type, payload, meta) => {
+                    const channel = client.channel();
+                    if (!channel)
+                        return;
+                    await channel
+                        .request("event", {
+                        ...(meta.claim === undefined ? {} : { runId: meta.claim }),
+                        sessionId,
+                        turnId,
+                        type,
+                        payload,
+                        ...(meta.record ? { record: meta.record } : {}),
+                    })
+                        .catch((error) => logger.warn("harness sandbox event not claimed", {
+                        sessionId,
+                        type,
+                        message: error instanceof Error ? error.message : String(error),
+                    }));
+                },
+            });
+        },
+        ...(options.onGrant ? { onGrant: options.onGrant } : {}),
+        ...(options.backoff ? { backoff: options.backoff } : {}),
+        ...(options.liveness ? { liveness: options.liveness } : {}),
+    });
+    return {
+        client,
+        async stop(waitMs) {
+            clearInterval(sweep);
+            await client.stop(waitMs);
+            await pool.close();
+            await manager?.close();
+        },
+    };
+}

package/dist/harness/ws-client.d.ts

@@ -0,0 +1,43 @@
+/**
+ * A harness's connection to core (F6.2): a WebSocket to the Harness API listener, with the
+ * harness credential (`Authorization: Bearer`, `NYLORUN_HARNESS_TOKEN`) and the API version
+ * header. Each connection runs one `createHarness`: it says `hello`, leases runs, and answers
+ * core's `workspace.*` requests (`serve`). When the connection is lost its runs stop (core gives
+ * their segments to the next advance, which resumes them by replay) and the client connects
+ * again after a jittered backoff of 0.5 to 10 s.
+ */
+import { type HarnessChannel, type RequestHandler } from "@nylorun/core/harness-api";
+import { type HarnessOptions } from "@nylorun/harness/api";
+import { type WsPortOptions } from "./ws-port.js";
+export interface HarnessClientOptions extends Omit<HarnessOptions, "channel" | "logger"> {
+    /** The Harness API, e.g. `ws://runtime:4200/nylorun/harness/v1` (`NYLORUN_HARNESS_URL`). */
+    readonly url: string;
+    /**
+     * `NYLORUN_HARNESS_TOKEN`, or, for a pod sandbox's engine (F7.2), a function that answers
+     * a current host token before each connection (it renews, or joins again).
+     */
+    readonly token: string | (() => Promise<string>);
+    readonly logger: {
+        info(message: string, fields?: Record<string, unknown>): void;
+        warn(message: string, fields?: Record<string, unknown>): void;
+    };
+    /** Answers core's requests (`workspace.*`). */
+    readonly serve?: RequestHandler;
+    /** Reconnect backoff bounds. Default 500 ms to 10 s. */
+    readonly backoff?: {
+        readonly minMs: number;
+        readonly maxMs: number;
+    };
+    readonly liveness?: Omit<WsPortOptions, "ping">;
+}
+export interface HarnessClient {
+    /** Resolves once the first connection's `hello` is answered. */
+    readonly ready: Promise<void>;
+    /** Connected, and `hello` answered. */
+    readonly connected: boolean;
+    /** The current connection's channel, while there is one. */
+    channel(): HarnessChannel | undefined;
+    /** Stops leasing, gives its runs back (at most `waitMs`), and closes the connection. */
+    stop(waitMs?: number): Promise<void>;
+}
+export declare function connectHarness(options: HarnessClientOptions): HarnessClient;