@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/dist/agent-host/remote-adapter.js

@@ -0,0 +1,283 @@
+/**
+ * The remote adapter: a `HarnessAdapter` (`harness/types.ts`) whose engine
+ * runs in the agent host. The registry, the turn runtime and both
+ * composition roots see the interface they always saw; this module turns
+ * each member into a call over the host's pipe (`protocol.ts`), and each of
+ * the host's calls back into the runtime's sink.
+ *
+ * The runtime keeps everything that needs authority — the persist
+ * chokepoint, the control-plane writes, the artifact store, the memory
+ * selection, the plugin archives — and the host asks for it by turn. Every
+ * value the host sends is the agent's, so what the runner acts on is
+ * checked here, at the one place it enters:
+ *
+ *  - a persist replaces only the adapter-owned status fields, never one the
+ *    runtime owns (`codec.ts`);
+ *  - a harness state bind carries only the id; the runtime records it
+ *    through the session's `bindHarnessState` door;
+ *  - an upload is confined to the turn's own key prefix, the one the
+ *    engines write under (`execute-deep-agent/inline-publisher.ts`);
+ *  - a usage report's counts are clamped to finite, non-negative numbers;
+ *  - a plugin verify names one of the turn's own plugins.
+ *
+ * The turn's lifetime is one pending `runTurn` call. The runtime's stop is
+ * forwarded as a notice; the call is answered when the adapter settles,
+ * with the adapter-owned fields, which replace the runtime's, and the
+ * engine's last CAS snapshot, which the runtime's boundary capture reads
+ * after the call returns. When the host dies first, the call rejects and
+ * the turn settles here: `interrupted` when the runtime had already asked
+ * it to stop, otherwise `failed` on the `internal` surface. Anything the
+ * host sends for a turn after that is dropped (`supervisor.ts`).
+ */
+import { randomBytes, randomUUID } from "node:crypto";
+import { posix } from "node:path";
+import { RunStatusSchema } from "@stigmer/apis/ai/stigmer/agentic/run/v1/api_pb";
+import { executionFingerprintKey } from "../shared/fingerprint-secret.js";
+import { offloadedOutputs } from "../shared/status-offload.js";
+import { activeTraceparent } from "../shared/trace-context.js";
+import { RuntimeFieldTracker, applyAdapterProjection, decodeCasSnapshot, encodeMessage, encodeRunEvents, encodeTurnInput, encodeOffloads } from "./codec.js";
+import { fromWireError } from "./protocol.js";
+import { TurnRowsSchema } from "../gen/turn/ai/stigmer/runner/turn/v1/rows_pb.js";
+/**
+ * The remote stand-in for `local`, the real adapter, which the host runs.
+ * `local` lends only its name and its capabilities: the runtime branches on
+ * them before and after the turn, and they are the adapter's own facts.
+ */
+export function createRemoteAdapter(harness, local, host, turns) {
+    return {
+        name: local.name,
+        capabilities: local.capabilities,
+        boot: (config) => host.boot(harness, config),
+        shutdown: () => host.shutdown(harness),
+        releaseSession: (sessionId) => host.releaseSession(harness, sessionId),
+        runTurn: (input, sink) => runRemoteTurn(harness, host, turns, input, sink),
+    };
+}
+async function runRemoteTurn(harness, host, turns, input, sink) {
+    const turnId = randomUUID();
+    const turn = new RemoteTurn(turnId, input, sink, host);
+    const detach = host.attachTurn(turnId, turn.endpoint);
+    // The turn's own key at the proxy: one host serves every turn with one
+    // token, so this is what keeps a turn's calls to its own execution.
+    const turnKey = randomBytes(32).toString("base64url");
+    const closeTurn = turns.openTurn({ executionId: input.executionId, threadId: input.threadId, turnKey });
+    let stopListener;
+    try {
+        const peer = await host.connection();
+        stopListener = () => peer.notify("stopTurn", { turnId, reason: describeReason(sink.stopSignal.reason) });
+        sink.stopSignal.addEventListener("abort", stopListener, { once: true });
+        const settlement = await peer.call("runTurn", {
+            turnId,
+            harness,
+            input: encodeTurnInput(input),
+            status: encodeMessage(RunStatusSchema, sink.status),
+            rows: encodeMessage(TurnRowsSchema, sink.rows),
+            timing: sink.setupTiming.toWire(),
+            fingerprintKey: executionFingerprintKey(input.executionId).toString("base64"),
+            stopped: sink.stopSignal.aborted ? describeReason(sink.stopSignal.reason) : null,
+            turnKey,
+            traceparent: await activeTraceparent(),
+        });
+        applyAdapterProjection(sink, settlement.projection);
+        confineHostRows(sink, input.executionId, turn.seededKeys);
+        turn.settle(settlement.cas === null ? undefined : confineCasSnapshot(decodeCasSnapshot(settlement.cas)));
+        if (settlement.thrown !== null || settlement.outcome === null) {
+            throw fromWireError(settlement.thrown ?? { name: "Error", message: "the agent host settled with no outcome" });
+        }
+        return fromWireOutcome(settlement.outcome);
+    }
+    catch (err) {
+        if (turn.settled)
+            throw err;
+        turn.settle(undefined);
+        if (sink.stopSignal.aborted)
+            return { kind: "interrupted" };
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`[agent-host] turn lost with the agent host: execution=${input.executionId}, ${message}`);
+        return { kind: "failed", surface: "internal", message: `The agent process stopped before the turn finished: ${message}`, cause: err };
+    }
+    finally {
+        if (stopListener)
+            sink.stopSignal.removeEventListener("abort", stopListener);
+        closeTurn();
+        detach();
+    }
+}
+/** One remote turn's runner side: the handlers the host's calls reach. */
+class RemoteTurn {
+    input;
+    sink;
+    runtimeFields;
+    /** The storage keys the runtime's rows and status held when the turn began: rows the host may keep naming. */
+    seededKeys;
+    finalCas;
+    done = false;
+    endpoint;
+    constructor(turnId, input, sink, host) {
+        this.input = input;
+        this.sink = sink;
+        this.runtimeFields = new RuntimeFieldTracker(sink.status);
+        this.seededKeys = storageKeysOf(sink);
+        const { executionId } = input;
+        this.endpoint = {
+            calls: {
+                persist: async ({ projection }) => {
+                    applyAdapterProjection(sink, projection);
+                    confineHostRows(sink, executionId, this.seededKeys);
+                    await sink.requestPersist();
+                    return { runtime: this.runtimeFields.changes(sink.status), offloads: encodeOffloads(offloadedOutputs(sink.rows)) };
+                },
+                reportProgress: async ({ label }) => {
+                    await sink.reportProgress(label);
+                    return null;
+                },
+                bindHarnessState: async ({ harnessStateId }) => {
+                    await sink.bindHarnessState(harnessStateId);
+                    return null;
+                },
+                selectRecalledMemories: async () => (await input.standing.selectRecalledMemories()) ?? null,
+                uploadArtifact: async ({ key, content, contentType }) => {
+                    const storage = input.artifactStorage;
+                    if (!storage)
+                        throw new Error("this turn has no artifact storage");
+                    assertTurnArtifactKey(key, executionId);
+                    return storage.upload(key, Buffer.from(content, "base64"), contentType ?? undefined);
+                },
+                verifyPlugin: async ({ slug }) => {
+                    const plugin = input.hooks.sources.find((s) => s.plugin?.slug === slug)?.plugin;
+                    if (!plugin)
+                        throw new Error(`plugin '${slug}' is not one of this turn's`);
+                    await plugin.verify();
+                    return null;
+                },
+                readRunEvents: async () => encodeRunEvents(await input.readRunEvents()),
+            },
+            notices: {
+                activity: ({ detail }) => sink.recordActivity(detail ?? undefined),
+                usage: ({ delta }) => sink.reportUsage(clampUsage(delta)),
+                event: ({ event, atWallMs, messageIndex }) => sink.transcript.relayObserved(event, atWallMs - performance.timeOrigin, messageIndex === null ? undefined : { messageIndex }),
+                bindCas: () => sink.bindCasObservations(async () => {
+                    if (this.finalCas)
+                        return this.finalCas;
+                    const peer = await host.connection();
+                    return confineCasSnapshot(decodeCasSnapshot(await peer.call("readCasObservations", { turnId })));
+                }),
+            },
+        };
+    }
+    get settled() {
+        return this.done;
+    }
+    /** The turn is over; the runtime's later CAS reads see the snapshot the host settled with. */
+    settle(cas) {
+        this.done = true;
+        this.finalCas = cas ?? { before: new Map(), blockedSecretPaths: new Set() };
+    }
+}
+/**
+ * Refuse an upload outside the turn's own prefix: the engines write
+ * `artifacts/<executionId>/<file>` (`execute-deep-agent/inline-publisher.ts`),
+ * and the runner's store holds every other turn's objects beside it.
+ */
+export function assertTurnArtifactKey(key, executionId) {
+    if (!isTurnArtifactKey(key, executionId))
+        throw new Error(`artifact key '${key}' is outside this turn's prefix artifacts/${executionId}/`);
+}
+/** Is `key` under the execution's own artifact prefix, with no empty, `.` or `..` segment? */
+export function isTurnArtifactKey(key, executionId) {
+    const prefix = `artifacts/${executionId}/`;
+    const rest = key.startsWith(prefix) ? key.slice(prefix.length) : undefined;
+    const segments = rest?.split("/") ?? [];
+    return !(rest === undefined || rest === "" || key.includes("\\") || segments.some((s) => s === "" || s === "." || s === ".."));
+}
+/** Every storage key the turn names: its artifact rows' and its tool outputs' refs. */
+function storageKeysOf(turn) {
+    const keys = new Set();
+    for (const artifact of turn.status.artifacts)
+        if (artifact.storageKey)
+            keys.add(artifact.storageKey);
+    for (const tc of allToolCallsOf(turn.rows))
+        if (tc.outputRef?.storageKey)
+            keys.add(tc.outputRef.storageKey);
+    return keys;
+}
+function allToolCallsOf(rows) {
+    const calls = [];
+    const lists = [rows.messages, ...rows.subAgentRuns.map((run) => run.messages)];
+    for (const messages of lists)
+        for (const message of messages)
+            calls.push(...message.toolCalls);
+    return calls;
+}
+/**
+ * Keep the host's rows to keys the turn may name: its own prefix, or a key
+ * the runtime's rows or status already held when the turn began. An artifact row
+ * outside both is dropped; a tool output's ref outside both is dropped
+ * (the runtime's offload makes its own on the next persist), so the
+ * console never links another execution's artifact from this turn.
+ */
+function confineHostRows(turn, executionId, seeded) {
+    const allowed = (key) => key === "" || seeded.has(key) || isTurnArtifactKey(key, executionId);
+    const kept = turn.status.artifacts.filter((artifact) => allowed(artifact.storageKey));
+    turn.status.artifacts.splice(0, turn.status.artifacts.length, ...kept);
+    for (const tc of allToolCallsOf(turn.rows)) {
+        if (tc.outputRef !== undefined && !allowed(tc.outputRef.storageKey))
+            tc.outputRef = undefined;
+    }
+}
+/**
+ * Keep a CAS snapshot's paths inside the workspace: the runtime's capture
+ * reads each one under the workspace root, so a path that is absolute or
+ * leaves the root once normalized is dropped, never read.
+ */
+export function confineCasSnapshot(snapshot) {
+    // Separators of either platform, and a drive letter, read as escapes too:
+    // the engine's paths are workspace-relative.
+    const inside = (raw) => {
+        const path = raw.replace(/\\/g, "/");
+        if (path === "" || path.includes("\0") || posix.isAbsolute(path) || /^[A-Za-z]:/.test(path))
+            return false;
+        const normal = posix.normalize(path);
+        return normal !== ".." && !normal.startsWith("../");
+    };
+    return {
+        before: new Map([...snapshot.before].filter(([path]) => inside(path))),
+        blockedSecretPaths: new Set([...snapshot.blockedSecretPaths].filter(inside)),
+    };
+}
+function clampUsage(delta) {
+    const count = (n) => n === undefined ? undefined : Number.isFinite(n) && n > 0 ? n : 0;
+    return {
+        inputTokens: count(delta.inputTokens),
+        outputTokens: count(delta.outputTokens),
+        cacheReadTokens: count(delta.cacheReadTokens),
+        cacheWriteTokens: count(delta.cacheWriteTokens),
+        estimatedCostUsd: count(delta.estimatedCostUsd),
+        ...(typeof delta.model === "string" ? { model: delta.model } : {}),
+        ...(typeof delta.requestedModelParams === "string" ? { requestedModelParams: delta.requestedModelParams } : {}),
+    };
+}
+const SETTLED_KINDS = new Set(["completed", "cancelled", "awaiting_approval", "tool_call_limit", "interrupted"]);
+const FAILURE_SURFACES = new Set(["engine", "actionable", "internal"]);
+/** The host's outcome, taken only in a shape the runtime knows: anything else is an internal failure, never the host's own choice. */
+function fromWireOutcome(wire) {
+    // Read as the host sent it, not as the type promises: the host is the agent's.
+    const raw = wire;
+    if (typeof raw.kind === "string" && SETTLED_KINDS.has(raw.kind))
+        return { kind: raw.kind };
+    if (raw.kind !== "failed" || typeof raw.message !== "string" || typeof raw.surface !== "string" || !FAILURE_SURFACES.has(raw.surface)) {
+        return { kind: "failed", surface: "internal", message: "The agent process answered with an outcome this runner does not know." };
+    }
+    return {
+        kind: "failed",
+        message: raw.message,
+        surface: raw.surface,
+        ...(raw.cause !== undefined ? { cause: fromWireError(raw.cause) } : {}),
+    };
+}
+function describeReason(reason) {
+    if (reason instanceof Error)
+        return reason.message;
+    return typeof reason === "string" ? reason : "stopped";
+}
+//# sourceMappingURL=remote-adapter.js.map

package/dist/agent-host/remote-adapter.js.map

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

package/dist/agent-host/remote-fs.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The runner's side of the agent's file and process operations
+ * (`shared/agent-fs.ts`): an {@link AgentFs} whose every operation is an
+ * `fs` or `exec` call the agent host performs (`fs-service.ts`), with the
+ * agent's rights. `hosting.ts` installs it when the runner starts its host.
+ *
+ * Errors come back as the caller expects them: a filesystem error with its
+ * errno `code`, a failed process as an {@link AgentExecError}. Bodies larger
+ * than one message cross in ranges ({@link FS_CHUNK_BYTES}).
+ */
+import { type AgentFs } from "../shared/agent-fs.js";
+import { type FsRequest, type HostCalls } from "./protocol.js";
+/** What `remoteAgentFs` needs of the host: its two calls. */
+export interface FsHost {
+    fs(request: FsRequest): Promise<HostCalls["fs"]["result"]>;
+    exec(request: HostCalls["exec"]["args"]): Promise<HostCalls["exec"]["result"]>;
+}
+/** The operations, each performed by the host behind `host`. */
+export declare function remoteAgentFs(host: FsHost): AgentFs;

package/dist/agent-host/remote-fs.js

@@ -0,0 +1,120 @@
+/**
+ * The runner's side of the agent's file and process operations
+ * (`shared/agent-fs.ts`): an {@link AgentFs} whose every operation is an
+ * `fs` or `exec` call the agent host performs (`fs-service.ts`), with the
+ * agent's rights. `hosting.ts` installs it when the runner starts its host.
+ *
+ * Errors come back as the caller expects them: a filesystem error with its
+ * errno `code`, a failed process as an {@link AgentExecError}. Bodies larger
+ * than one message cross in ranges ({@link FS_CHUNK_BYTES}).
+ */
+import { AgentExecError, entryFrom, statsFrom, DEFAULT_EXEC_MAX_BUFFER, } from "../shared/agent-fs.js";
+import { FS_CHUNK_BYTES } from "./protocol.js";
+/** The operations, each performed by the host behind `host`. */
+export function remoteAgentFs(host) {
+    const call = async (request) => valueOf(await host.fs(request));
+    const read = async (path) => {
+        const parts = [];
+        let offset = 0;
+        for (;;) {
+            const range = (await call({ op: "read", path, offset, length: FS_CHUNK_BYTES }));
+            const bytes = Buffer.from(range.data, "base64");
+            parts.push(bytes);
+            offset += bytes.length;
+            if (bytes.length === 0 || offset >= range.size)
+                return Buffer.concat(parts);
+        }
+    };
+    const output = async (wire) => {
+        if ("inline" in wire)
+            return Buffer.from(wire.inline, "base64");
+        try {
+            return await read(wire.spill);
+        }
+        finally {
+            await call({ op: "rm", path: wire.spill, recursive: false, force: true });
+        }
+    };
+    return {
+        readFile: read,
+        writeFile: async (path, data, options) => {
+            const bytes = typeof data === "string" ? Buffer.from(data, "utf8") : Buffer.from(data);
+            let offset = 0;
+            do {
+                const chunk = bytes.subarray(offset, offset + FS_CHUNK_BYTES);
+                await call({ op: "write", path, data: chunk.toString("base64"), append: offset > 0, mode: offset > 0 ? null : (options?.mode ?? null) });
+                offset += chunk.length;
+            } while (offset < bytes.length);
+        },
+        mkdir: async (path, options) => {
+            await call({ op: "mkdir", path, recursive: options?.recursive ?? false, mode: options?.mode ?? null });
+        },
+        rm: async (path, options) => {
+            await call({ op: "rm", path, recursive: options?.recursive ?? false, force: options?.force ?? false });
+        },
+        rmdir: async (path) => {
+            await call({ op: "rmdir", path });
+        },
+        unlink: async (path) => {
+            await call({ op: "unlink", path });
+        },
+        rename: async (from, to) => {
+            await call({ op: "rename", from, to });
+        },
+        cp: async (from, to, options) => {
+            await call({
+                op: "cp",
+                from,
+                to,
+                recursive: options?.recursive ?? false,
+                errorOnExist: options?.errorOnExist ?? false,
+                force: options?.force ?? true,
+                verbatimSymlinks: options?.verbatimSymlinks ?? false,
+            });
+        },
+        copyFile: async (from, to) => {
+            await call({ op: "copyFile", from, to });
+        },
+        stat: async (path) => statsFrom((await call({ op: "stat", path }))),
+        lstat: async (path) => statsFrom((await call({ op: "lstat", path }))),
+        readdir: async (path, options) => (await call({ op: "readdir", path, recursive: options?.recursive ?? false })).map(entryFrom),
+        readlink: async (path) => (await call({ op: "readlink", path })),
+        symlink: async (target, path) => {
+            await call({ op: "symlink", target, path });
+        },
+        realpath: async (path) => (await call({ op: "realpath", path })),
+        access: async (path) => {
+            await call({ op: "access", path });
+        },
+        execFile: async (file, args, options) => {
+            const reply = await host.exec({
+                file,
+                args,
+                cwd: options?.cwd ?? null,
+                env: options?.env ?? {},
+                replaceEnv: options?.replaceEnv ?? false,
+                timeoutMs: options?.timeoutMs ?? null,
+                maxBuffer: options?.maxBuffer ?? DEFAULT_EXEC_MAX_BUFFER,
+                input: options?.input === undefined ? null : Buffer.from(options.input).toString("base64"),
+            });
+            const stdout = await output(reply.stdout);
+            const stderr = await output(reply.stderr);
+            if (reply.failure !== null)
+                throw new AgentExecError(reply.failure.message, reply.failure.code, reply.failure.signal, stdout, stderr);
+            return { stdout, stderr };
+        },
+    };
+}
+function valueOf(reply) {
+    if ("ok" in reply)
+        return reply.ok;
+    const err = new Error(reply.error.message);
+    if (reply.error.code !== null)
+        err.code = reply.error.code;
+    if (reply.error.syscall !== null)
+        err.syscall = reply.error.syscall;
+    if (reply.error.path !== null)
+        err.path = reply.error.path;
+    throw err;
+}
+//# sourceMappingURL=remote-fs.js.map

package/dist/agent-host/remote-fs.js.map

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

package/dist/agent-host/supervisor.d.ts

@@ -0,0 +1,149 @@
+/**
+ * The runner's side of the agent host's lifetime: start it, prove it is the
+ * host this build speaks to, boot the harnesses the runner asked for, route
+ * its calls to the turns they belong to, and start it again when it dies.
+ *
+ * One host per runner process, for the adapters' worker lifetime
+ * (`harness/types.ts`); the manager mode's session workers share it, as
+ * they share one adapter object in-process. The remote adapters
+ * (`remote-adapter.ts`) are this module's only callers.
+ *
+ * Starting is a {@link HostStarter}: production spawns the runner's own
+ * entry in its agent-host mode with the channel on fd 3
+ * ({@link processHostStarter}); the tests serve a host in this process over
+ * a loopback channel. Each start mints a fresh host token and authorizes it
+ * at the local proxy (`agent-proxy/`), so a token from a host that died is
+ * worth nothing.
+ *
+ * Restart: a host that exits while the runner still needs it is started
+ * again after a delay that starts at one second and doubles to thirty, the
+ * backoff the attach waiter supervises the runner with
+ * (`attach/waiter.ts`); a host that served longer than the longest delay
+ * restarts promptly. A restarted host is booted with every harness the
+ * runner booted, in the same order, before it serves a turn. A turn that
+ * was running on the host that died settles at once (its pending call
+ * rejects, `remote-adapter.ts`), and the next turn waits for the restart.
+ *
+ * Stopping: once every booted harness has been shut down, the channel is
+ * closed and no restart follows. The host exits on its channel's end, as
+ * the manager exits on its stdin's (`main.ts`), so a runner that is killed
+ * outright leaves no host behind either.
+ */
+import { type ChildProcess } from "node:child_process";
+import type { Config } from "../config.js";
+import type { HarnessName } from "../harness/registry.js";
+import { type AgentIdentity } from "../shared/agent-identity.js";
+import { Peer, type LineChannel } from "./channel.js";
+import { type HostCalls, type HostNotices, type RunnerCalls, type RunnerNotices } from "./protocol.js";
+/** The runner's side of the pipe. */
+export type RunnerPeer = Peer<HostCalls, RunnerCalls, RunnerNotices, HostNotices>;
+/** A started host: its channel, and how to end it if the channel's close does not. */
+export interface StartedHost {
+    readonly channel: LineChannel;
+    readonly kill: () => void;
+}
+export type HostStarter = () => StartedHost | Promise<StartedHost>;
+/** What the supervisor needs of the local proxy (`agent-proxy/server.ts`). */
+export interface AgentProxyGate {
+    /** `http://127.0.0.1:<port>`. */
+    readonly endpoint: string;
+    /** The Cursor lane, `https://2130706433:<port>`, 127.0.0.1 written as one number so the Cursor SDK keeps certificate checks on (`agent-proxy/cursor-lane.ts`). */
+    readonly cursorEndpoint: string;
+    /** Make `token` the one host token the proxy accepts. */
+    authorizeHost(token: string): void;
+}
+/**
+ * The runner's handlers for one remote turn: what the host may ask while
+ * the turn runs. `remote-adapter.ts` implements it.
+ */
+export interface RemoteTurnEndpoint {
+    readonly calls: {
+        readonly [M in keyof RunnerCalls]: (args: RunnerCalls[M]["args"]) => Promise<RunnerCalls[M]["result"]>;
+    };
+    readonly notices: {
+        readonly [M in keyof HostNotices]: (args: HostNotices[M]) => void;
+    };
+}
+export interface AgentHostSupervisorOptions {
+    readonly start: HostStarter;
+    readonly proxy: AgentProxyGate;
+    readonly firstRestartDelayMs?: number;
+    readonly maxRestartDelayMs?: number;
+    /** How long a started host has to announce itself. */
+    readonly helloTimeoutMs?: number;
+    readonly log?: (message: string) => void;
+}
+export declare class AgentHostSupervisor {
+    private readonly options;
+    private readonly booted;
+    private readonly turns;
+    private live;
+    private starting;
+    private restartTimer;
+    private stopping;
+    private nextDelay;
+    private readonly firstDelay;
+    private readonly maxDelay;
+    private readonly log;
+    constructor(options: AgentHostSupervisorOptions);
+    /** Boot `harness` in the host, starting the host first if it is not running. */
+    boot(harness: HarnessName, config: Config): Promise<void>;
+    /** Shut `harness` down in the host; the last one stops the host. */
+    shutdown(harness: HarnessName): Promise<void>;
+    releaseSession(harness: HarnessName, sessionId: string): Promise<void>;
+    /** Ask the host to warm the Cursor SDK's stores (an idle pool member's head start); nothing to warm when Cursor is not booted. */
+    warmCursorSdk(): Promise<HostCalls["warmCursorSdk"]["result"]>;
+    /** The live host, started (and booted) first when it is not running. */
+    connection(): Promise<RunnerPeer>;
+    /** Route the host's calls and notices for `turnId` to `endpoint` until the returned release runs. */
+    attachTurn(turnId: string, endpoint: RemoteTurnEndpoint): () => void;
+    private connectReporting;
+    private startHost;
+    private awaitHello;
+    /** Install the dispatch of every host call and notice to the turn it names. */
+    private route;
+    /** The live host's channel closed. A host stopped on purpose is no longer live when its channel closes (`stop`), so this never restarts one. */
+    private onHostGone;
+    private scheduleRestart;
+    private stop;
+    private wireConfig;
+}
+/**
+ * Start the host as a child process: this runner's own entry in its
+ * agent-host mode (`main.ts`), on the same Node, with the channel on fd 3.
+ * The host's stdout and stderr are relayed line by line through this
+ * process's console, so its log lines read as the runner's always did and
+ * never reach a stdout that carries the manager's protocol (`main.ts`
+ * sends `console.log` to stderr in that mode).
+ *
+ * `env` is what the host and every process it starts see (`environment.ts`).
+ */
+export declare function processHostStarter(env: () => NodeJS.ProcessEnv): HostStarter;
+/** How long a host whose pipe has closed has to exit before it is killed: its own shutdown grace (`entry.ts`), and a margin. */
+export declare const HOST_KILL_GRACE_MS = 15000;
+/**
+ * Spawn one host process with its channel on fd 3 and its output relayed
+ * (`processHostStarter` says how). The child is handed back beside the
+ * started host for the spawned-host tests, which kill it mid-turn.
+ */
+export declare function spawnHostProcess(command: string, args: readonly string[], env: NodeJS.ProcessEnv, killGraceMs?: number): {
+    readonly started: StartedHost;
+    readonly child: ChildProcess;
+};
+/**
+ * The command that runs this build's entry in its agent-host mode, and what
+ * its environment needs for that runtime: under Electron (a library
+ * embedder's), `process.execPath` is the Electron binary, which runs a script
+ * as Node only with `ELECTRON_RUN_AS_NODE` (the hook script's precedent,
+ * `activities/execute-cursor/hook-script.ts`). The host drops it again at
+ * start (`entry.ts`), so an Electron app an agent runs behaves as usual.
+ *
+ * A separating runner (`shared/agent-identity.ts`) starts it through
+ * `setpriv` as the agent user, with the agent's home as `HOME`: the one
+ * place the runner drops privilege. Everything the host starts inherits it.
+ */
+export declare function agentHostCommand(versions?: NodeJS.ProcessVersions, identity?: AgentIdentity | null): {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly env: Readonly<Record<string, string>>;
+};