@code-yeongyu/senpi 2026.8.26 → 2026.8.27

package/dist/modes/rpc/host-ensure.js

@@ -0,0 +1,245 @@
+import { spawn } from "node:child_process";
+import { mkdir, open, readFile, rm, writeFile } from "node:fs/promises";
+import { createConnection } from "node:net";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import * as properLockfile from "proper-lockfile";
+import { ENV_AGENT_DIR, getAgentDir, VERSION } from "../../config.js";
+import { parseDaemonPidFile, processMatchesPidFile, waitForStartTime, } from "../app-server/daemon/process.js";
+import { CUSTOM_UNSUPPORTED_CAPABILITY, EXTENSION_EVENTS_CAPABILITY, RPC_CLIENT_CAPABILITIES_ENV, } from "./custom-capability.js";
+import { DEFAULT_HOST_IDLE_EXIT_MS } from "./host-lifecycle.js";
+const lockOptions = { stale: 60_000, retries: { retries: 100, minTimeout: 20, maxTimeout: 100 } };
+const REQUIRED_CAPABILITIES = ["multi_session", EXTENSION_EVENTS_CAPABILITY];
+/**
+ * Every ensured host starts with this installation-wide profile, independent of
+ * the first caller. In particular, extension_events must remain available when
+ * a terminal client starts the shared host before the desktop connects.
+ */
+export const PINNED_HOST_CLIENT_CAPABILITIES = [EXTENSION_EVENTS_CAPABILITY, CUSTOM_UNSUPPORTED_CAPABILITY];
+export function createHostDaemonPaths(agentDir = getAgentDir()) {
+    const dir = join(agentDir, "rpc-host-daemon");
+    return {
+        dir,
+        pidFile: join(dir, "host.pid"),
+        lockFile: join(dir, "daemon.lock"),
+        settingsFile: join(dir, "settings.json"),
+        stderrLog: join(dir, "stderr.log"),
+    };
+}
+export async function ensureHost(options) {
+    const socket = normalizeSocketPath(options.socket);
+    const paths = createHostDaemonPaths(options.agentDir);
+    await mkdir(paths.dir, { recursive: true });
+    const release = await properLockfile.lock(paths.dir, { ...lockOptions, lockfilePath: paths.lockFile });
+    try {
+        return await ensureHostLocked(paths, socket, options.agentDir ?? getAgentDir(), options.policy, options._test);
+    }
+    finally {
+        await release();
+    }
+}
+async function ensureHostLocked(paths, socket, agentDir, policy, testOptions) {
+    const pidFile = await readPidFile(paths);
+    const protocol = await probeProtocolInfo(socket, 1_000);
+    const pidMatches = pidFile ? await processMatchesPidFile(pidFile) : false;
+    if (isCompatible(protocol)) {
+        // A compatible socket is attachable even when another client surface
+        // started it. Only hosts we spawned are eligible for lifecycle management.
+        return { pid: pidFile?.pid ?? 0, socket, reused: true };
+    }
+    if (protocol && !pidMatches) {
+        throw new Error(`RPC socket ${socket} is owned by an unmanaged host`);
+    }
+    if (pidFile && pidMatches) {
+        await stopManagedHost(pidFile, testOptions?.stopTimeoutMs ?? 10_000);
+    }
+    await cleanupState(paths);
+    return startHost(paths, socket, agentDir, policy, testOptions);
+}
+async function startHost(paths, socket, agentDir, policy, testOptions) {
+    // The settings file must exist before the supervisor reads it at boot, so it
+    // records the policy before the spawn instead of beside the pidfile.
+    await writeFile(paths.settingsFile, `${JSON.stringify({
+        socket,
+        capabilities: PINNED_HOST_CLIENT_CAPABILITIES,
+        coldStart: policy?.coldStart ?? "transient",
+        idleExitMs: policy?.idleExitMs ?? DEFAULT_HOST_IDLE_EXIT_MS,
+    })}\n`, { mode: 0o600 });
+    const stderr = await open(paths.stderrLog, "w", 0o600);
+    let pidFile;
+    try {
+        const launch = testOptions?.spawn ?? defaultHostLaunch(socket, testOptions?.hostArgs ?? []);
+        const child = spawn(launch.command, [...launch.args], {
+            detached: true,
+            env: {
+                ...process.env,
+                ...(testOptions?.env ?? {}),
+                [ENV_AGENT_DIR]: agentDir,
+                [RPC_CLIENT_CAPABILITIES_ENV]: PINNED_HOST_CLIENT_CAPABILITIES.join(","),
+            },
+            stdio: ["ignore", "ignore", stderr.fd],
+        });
+        child.unref();
+        if (child.pid === undefined)
+            throw new Error("failed to spawn RPC socket host");
+        pidFile = { pid: child.pid, processStartTime: await waitForStartTime(child.pid, 2_000) };
+        await writeFile(paths.pidFile, `${JSON.stringify(pidFile)}\n`, { mode: 0o600 });
+    }
+    finally {
+        await stderr.close();
+    }
+    const readinessTimeoutMs = testOptions?.readinessTimeoutMs ?? 10_000;
+    const protocol = await pollProtocolInfo(socket, readinessTimeoutMs);
+    if (isCompatible(protocol))
+        return { pid: pidFile.pid, socket, reused: false };
+    await stopManagedHost(pidFile, testOptions?.stopTimeoutMs ?? 10_000);
+    const diagnostic = await appendStderr(paths, `spawned RPC socket host did not answer get_protocol_info within ${readinessTimeoutMs}ms`);
+    await cleanupState(paths);
+    await rm(socket, { force: true });
+    throw new Error(diagnostic);
+}
+async function stopManagedHost(pidFile, termTimeoutMs) {
+    await signalValidated(pidFile, "SIGTERM");
+    if (await waitForGone(pidFile, termTimeoutMs))
+        return;
+    await signalValidated(pidFile, "SIGKILL");
+    if (!(await waitForGone(pidFile, 2_000))) {
+        throw new Error(`RPC socket host pid ${pidFile.pid} remained alive after SIGKILL`);
+    }
+}
+async function signalValidated(pidFile, signal) {
+    if (!(await processMatchesPidFile(pidFile)))
+        return;
+    try {
+        process.kill(pidFile.pid, signal);
+    }
+    catch (error) {
+        if (!isNodeErrorCode(error, "ESRCH"))
+            throw error;
+    }
+}
+async function waitForGone(pidFile, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() <= deadline) {
+        if (!(await processMatchesPidFile(pidFile)))
+            return true;
+        await delay(50);
+    }
+    return false;
+}
+async function pollProtocolInfo(socket, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() <= deadline) {
+        const info = await probeProtocolInfo(socket, Math.min(500, Math.max(1, deadline - Date.now())));
+        if (info)
+            return info;
+        await delay(50);
+    }
+    return undefined;
+}
+function probeProtocolInfo(socketPath, timeoutMs) {
+    return new Promise((resolveProbe) => {
+        const socket = createConnection(socketPath);
+        let buffer = "";
+        let settled = false;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            socket.destroy();
+            resolveProbe(value);
+        };
+        const timeout = setTimeout(() => finish(), timeoutMs);
+        socket.once("connect", () => {
+            socket.write('{"id":"ensure-host-probe","type":"get_protocol_info"}\n');
+        });
+        socket.on("data", (chunk) => {
+            buffer += chunk.toString("utf8");
+            const newline = buffer.indexOf("\n");
+            if (newline === -1)
+                return;
+            finish(readProtocolInfo(buffer.slice(0, newline)));
+        });
+        socket.once("error", () => finish());
+        socket.once("close", () => finish());
+    });
+}
+function readProtocolInfo(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isRecord(parsed) || parsed.id !== "ensure-host-probe" || parsed.success !== true || !isRecord(parsed.data)) {
+        return undefined;
+    }
+    const { serverVersion, capabilities } = parsed.data;
+    if (typeof serverVersion !== "string" || !Array.isArray(capabilities))
+        return undefined;
+    if (!capabilities.every((capability) => typeof capability === "string"))
+        return undefined;
+    return { serverVersion, capabilities };
+}
+function isCompatible(protocol) {
+    return (protocol?.serverVersion === VERSION &&
+        REQUIRED_CAPABILITIES.every((capability) => protocol.capabilities.includes(capability)));
+}
+async function readPidFile(paths) {
+    try {
+        return parseDaemonPidFile(await readFile(paths.pidFile, "utf8"));
+    }
+    catch (error) {
+        if (isNodeErrorCode(error, "ENOENT"))
+            return undefined;
+        throw error;
+    }
+}
+async function cleanupState(paths) {
+    await rm(paths.pidFile, { force: true });
+    await rm(paths.settingsFile, { force: true });
+}
+async function appendStderr(paths, message) {
+    try {
+        const stderr = (await readFile(paths.stderrLog, "utf8")).trim();
+        return stderr ? `${message}\n${stderr}` : message;
+    }
+    catch (error) {
+        if (isNodeErrorCode(error, "ENOENT"))
+            return message;
+        throw error;
+    }
+}
+function normalizeSocketPath(value) {
+    if (value.startsWith("unix://"))
+        return value.slice("unix://".length);
+    return value;
+}
+/**
+ * Default launch: the host-lifecycle supervisor owns the public socket and the
+ * idle-exit policy; it spawns the committed RPC socket host itself. Any extra
+ * hostArgs are forwarded verbatim to the host CLI (e.g. provider pinning).
+ */
+function defaultHostLaunch(socket, hostArgs) {
+    return {
+        command: process.execPath,
+        args: [...process.execArgv, resolveHostLifecycleEntryPath(), "--socket", socket, ...hostArgs],
+    };
+}
+function resolveHostLifecycleEntryPath() {
+    const modulePath = fileURLToPath(import.meta.url);
+    const extension = modulePath.endsWith(".ts") ? ".ts" : ".js";
+    return resolve(dirname(modulePath), `host-lifecycle${extension}`);
+}
+function delay(ms) {
+    return new Promise((resolveDelay) => setTimeout(resolveDelay, ms));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNodeErrorCode(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}
+//# sourceMappingURL=host-ensure.js.map

package/dist/modes/rpc/host-ensure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-ensure.js","sourceRoot":"","sources":["../../../src/modes/rpc/host-ensure.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawn } from \"node:child_process\";\nimport { mkdir, open, readFile, rm, writeFile } from \"node:fs/promises\";\nimport { createConnection } from \"node:net\";\nimport { dirname, join, resolve } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport * as properLockfile from \"proper-lockfile\";\nimport { ENV_AGENT_DIR, getAgentDir, VERSION } from \"../../config.ts\";\nimport {\n\ttype DaemonPidFile,\n\tparseDaemonPidFile,\n\tprocessMatchesPidFile,\n\twaitForStartTime,\n} from \"../app-server/daemon/process.ts\";\nimport {\n\tCUSTOM_UNSUPPORTED_CAPABILITY,\n\tEXTENSION_EVENTS_CAPABILITY,\n\tRPC_CLIENT_CAPABILITIES_ENV,\n} from \"./custom-capability.ts\";\nimport { DEFAULT_HOST_IDLE_EXIT_MS, type HostColdStart, type HostLifecyclePolicyInput } from \"./host-lifecycle.ts\";\n\nexport type { HostColdStart, HostLifecyclePolicyInput };\n\nexport interface HostDaemonPaths {\n\treadonly dir: string;\n\treadonly pidFile: string;\n\treadonly lockFile: string;\n\treadonly settingsFile: string;\n\treadonly stderrLog: string;\n}\n\nexport interface EnsureHostOptions {\n\treadonly socket: string;\n\treadonly agentDir?: string;\n\t/** Host lifecycle policy recorded in settings.json (env overrides win at runtime). */\n\treadonly policy?: HostLifecyclePolicyInput;\n\treadonly _test?: {\n\t\treadonly readinessTimeoutMs?: number;\n\t\treadonly stopTimeoutMs?: number;\n\t\treadonly spawn?: { readonly command: string; readonly args: readonly string[] };\n\t\t/** Extra env merged over process.env for the spawned host (hermetic test/QA wiring). */\n\t\treadonly env?: Readonly<Record<string, string>>;\n\t\t/** Extra CLI args forwarded through the supervisor to the host process. */\n\t\treadonly hostArgs?: readonly string[];\n\t};\n}\n\nexport interface EnsuredHost {\n\treadonly pid: number;\n\treadonly socket: string;\n\treadonly reused: boolean;\n}\n\ntype ProtocolInfo = {\n\treadonly serverVersion: string;\n\treadonly capabilities: readonly string[];\n};\n\nconst lockOptions = { stale: 60_000, retries: { retries: 100, minTimeout: 20, maxTimeout: 100 } } as const;\nconst REQUIRED_CAPABILITIES = [\"multi_session\", EXTENSION_EVENTS_CAPABILITY] as const;\n/**\n * Every ensured host starts with this installation-wide profile, independent of\n * the first caller. In particular, extension_events must remain available when\n * a terminal client starts the shared host before the desktop connects.\n */\nexport const PINNED_HOST_CLIENT_CAPABILITIES = [EXTENSION_EVENTS_CAPABILITY, CUSTOM_UNSUPPORTED_CAPABILITY] as const;\n\nexport function createHostDaemonPaths(agentDir = getAgentDir()): HostDaemonPaths {\n\tconst dir = join(agentDir, \"rpc-host-daemon\");\n\treturn {\n\t\tdir,\n\t\tpidFile: join(dir, \"host.pid\"),\n\t\tlockFile: join(dir, \"daemon.lock\"),\n\t\tsettingsFile: join(dir, \"settings.json\"),\n\t\tstderrLog: join(dir, \"stderr.log\"),\n\t};\n}\n\nexport async function ensureHost(options: EnsureHostOptions): Promise<EnsuredHost> {\n\tconst socket = normalizeSocketPath(options.socket);\n\tconst paths = createHostDaemonPaths(options.agentDir);\n\tawait mkdir(paths.dir, { recursive: true });\n\tconst release = await properLockfile.lock(paths.dir, { ...lockOptions, lockfilePath: paths.lockFile });\n\ttry {\n\t\treturn await ensureHostLocked(paths, socket, options.agentDir ?? getAgentDir(), options.policy, options._test);\n\t} finally {\n\t\tawait release();\n\t}\n}\n\nasync function ensureHostLocked(\n\tpaths: HostDaemonPaths,\n\tsocket: string,\n\tagentDir: string,\n\tpolicy: HostLifecyclePolicyInput | undefined,\n\ttestOptions: EnsureHostOptions[\"_test\"],\n): Promise<EnsuredHost> {\n\tconst pidFile = await readPidFile(paths);\n\tconst protocol = await probeProtocolInfo(socket, 1_000);\n\tconst pidMatches = pidFile ? await processMatchesPidFile(pidFile) : false;\n\tif (isCompatible(protocol)) {\n\t\t// A compatible socket is attachable even when another client surface\n\t\t// started it. Only hosts we spawned are eligible for lifecycle management.\n\t\treturn { pid: pidFile?.pid ?? 0, socket, reused: true };\n\t}\n\tif (protocol && !pidMatches) {\n\t\tthrow new Error(`RPC socket ${socket} is owned by an unmanaged host`);\n\t}\n\tif (pidFile && pidMatches) {\n\t\tawait stopManagedHost(pidFile, testOptions?.stopTimeoutMs ?? 10_000);\n\t}\n\tawait cleanupState(paths);\n\treturn startHost(paths, socket, agentDir, policy, testOptions);\n}\n\nasync function startHost(\n\tpaths: HostDaemonPaths,\n\tsocket: string,\n\tagentDir: string,\n\tpolicy: HostLifecyclePolicyInput | undefined,\n\ttestOptions: EnsureHostOptions[\"_test\"],\n): Promise<EnsuredHost> {\n\t// The settings file must exist before the supervisor reads it at boot, so it\n\t// records the policy before the spawn instead of beside the pidfile.\n\tawait writeFile(\n\t\tpaths.settingsFile,\n\t\t`${JSON.stringify({\n\t\t\tsocket,\n\t\t\tcapabilities: PINNED_HOST_CLIENT_CAPABILITIES,\n\t\t\tcoldStart: policy?.coldStart ?? \"transient\",\n\t\t\tidleExitMs: policy?.idleExitMs ?? DEFAULT_HOST_IDLE_EXIT_MS,\n\t\t})}\\n`,\n\t\t{ mode: 0o600 },\n\t);\n\tconst stderr = await open(paths.stderrLog, \"w\", 0o600);\n\tlet pidFile: DaemonPidFile | undefined;\n\ttry {\n\t\tconst launch = testOptions?.spawn ?? defaultHostLaunch(socket, testOptions?.hostArgs ?? []);\n\t\tconst child = spawn(launch.command, [...launch.args], {\n\t\t\tdetached: true,\n\t\t\tenv: {\n\t\t\t\t...process.env,\n\t\t\t\t...(testOptions?.env ?? {}),\n\t\t\t\t[ENV_AGENT_DIR]: agentDir,\n\t\t\t\t[RPC_CLIENT_CAPABILITIES_ENV]: PINNED_HOST_CLIENT_CAPABILITIES.join(\",\"),\n\t\t\t},\n\t\t\tstdio: [\"ignore\", \"ignore\", stderr.fd],\n\t\t});\n\t\tchild.unref();\n\t\tif (child.pid === undefined) throw new Error(\"failed to spawn RPC socket host\");\n\t\tpidFile = { pid: child.pid, processStartTime: await waitForStartTime(child.pid, 2_000) };\n\t\tawait writeFile(paths.pidFile, `${JSON.stringify(pidFile)}\\n`, { mode: 0o600 });\n\t} finally {\n\t\tawait stderr.close();\n\t}\n\tconst readinessTimeoutMs = testOptions?.readinessTimeoutMs ?? 10_000;\n\tconst protocol = await pollProtocolInfo(socket, readinessTimeoutMs);\n\tif (isCompatible(protocol)) return { pid: pidFile.pid, socket, reused: false };\n\tawait stopManagedHost(pidFile, testOptions?.stopTimeoutMs ?? 10_000);\n\tconst diagnostic = await appendStderr(\n\t\tpaths,\n\t\t`spawned RPC socket host did not answer get_protocol_info within ${readinessTimeoutMs}ms`,\n\t);\n\tawait cleanupState(paths);\n\tawait rm(socket, { force: true });\n\tthrow new Error(diagnostic);\n}\n\nasync function stopManagedHost(pidFile: DaemonPidFile, termTimeoutMs: number): Promise<void> {\n\tawait signalValidated(pidFile, \"SIGTERM\");\n\tif (await waitForGone(pidFile, termTimeoutMs)) return;\n\tawait signalValidated(pidFile, \"SIGKILL\");\n\tif (!(await waitForGone(pidFile, 2_000))) {\n\t\tthrow new Error(`RPC socket host pid ${pidFile.pid} remained alive after SIGKILL`);\n\t}\n}\n\nasync function signalValidated(pidFile: DaemonPidFile, signal: NodeJS.Signals): Promise<void> {\n\tif (!(await processMatchesPidFile(pidFile))) return;\n\ttry {\n\t\tprocess.kill(pidFile.pid, signal);\n\t} catch (error: unknown) {\n\t\tif (!isNodeErrorCode(error, \"ESRCH\")) throw error;\n\t}\n}\n\nasync function waitForGone(pidFile: DaemonPidFile, timeoutMs: number): Promise<boolean> {\n\tconst deadline = Date.now() + timeoutMs;\n\twhile (Date.now() <= deadline) {\n\t\tif (!(await processMatchesPidFile(pidFile))) return true;\n\t\tawait delay(50);\n\t}\n\treturn false;\n}\n\nasync function pollProtocolInfo(socket: string, timeoutMs: number): Promise<ProtocolInfo | undefined> {\n\tconst deadline = Date.now() + timeoutMs;\n\twhile (Date.now() <= deadline) {\n\t\tconst info = await probeProtocolInfo(socket, Math.min(500, Math.max(1, deadline - Date.now())));\n\t\tif (info) return info;\n\t\tawait delay(50);\n\t}\n\treturn undefined;\n}\n\nfunction probeProtocolInfo(socketPath: string, timeoutMs: number): Promise<ProtocolInfo | undefined> {\n\treturn new Promise((resolveProbe) => {\n\t\tconst socket = createConnection(socketPath);\n\t\tlet buffer = \"\";\n\t\tlet settled = false;\n\t\tconst finish = (value?: ProtocolInfo): void => {\n\t\t\tif (settled) return;\n\t\t\tsettled = true;\n\t\t\tclearTimeout(timeout);\n\t\t\tsocket.destroy();\n\t\t\tresolveProbe(value);\n\t\t};\n\t\tconst timeout = setTimeout(() => finish(), timeoutMs);\n\t\tsocket.once(\"connect\", () => {\n\t\t\tsocket.write('{\"id\":\"ensure-host-probe\",\"type\":\"get_protocol_info\"}\\n');\n\t\t});\n\t\tsocket.on(\"data\", (chunk) => {\n\t\t\tbuffer += chunk.toString(\"utf8\");\n\t\t\tconst newline = buffer.indexOf(\"\\n\");\n\t\t\tif (newline === -1) return;\n\t\t\tfinish(readProtocolInfo(buffer.slice(0, newline)));\n\t\t});\n\t\tsocket.once(\"error\", () => finish());\n\t\tsocket.once(\"close\", () => finish());\n\t});\n}\n\nfunction readProtocolInfo(text: string): ProtocolInfo | undefined {\n\tlet parsed: unknown;\n\ttry {\n\t\tparsed = JSON.parse(text);\n\t} catch {\n\t\treturn undefined;\n\t}\n\tif (!isRecord(parsed) || parsed.id !== \"ensure-host-probe\" || parsed.success !== true || !isRecord(parsed.data)) {\n\t\treturn undefined;\n\t}\n\tconst { serverVersion, capabilities } = parsed.data;\n\tif (typeof serverVersion !== \"string\" || !Array.isArray(capabilities)) return undefined;\n\tif (!capabilities.every((capability) => typeof capability === \"string\")) return undefined;\n\treturn { serverVersion, capabilities };\n}\n\nfunction isCompatible(protocol: ProtocolInfo | undefined): boolean {\n\treturn (\n\t\tprotocol?.serverVersion === VERSION &&\n\t\tREQUIRED_CAPABILITIES.every((capability) => protocol.capabilities.includes(capability))\n\t);\n}\n\nasync function readPidFile(paths: HostDaemonPaths): Promise<DaemonPidFile | undefined> {\n\ttry {\n\t\treturn parseDaemonPidFile(await readFile(paths.pidFile, \"utf8\"));\n\t} catch (error: unknown) {\n\t\tif (isNodeErrorCode(error, \"ENOENT\")) return undefined;\n\t\tthrow error;\n\t}\n}\n\nasync function cleanupState(paths: HostDaemonPaths): Promise<void> {\n\tawait rm(paths.pidFile, { force: true });\n\tawait rm(paths.settingsFile, { force: true });\n}\n\nasync function appendStderr(paths: HostDaemonPaths, message: string): Promise<string> {\n\ttry {\n\t\tconst stderr = (await readFile(paths.stderrLog, \"utf8\")).trim();\n\t\treturn stderr ? `${message}\\n${stderr}` : message;\n\t} catch (error: unknown) {\n\t\tif (isNodeErrorCode(error, \"ENOENT\")) return message;\n\t\tthrow error;\n\t}\n}\n\nfunction normalizeSocketPath(value: string): string {\n\tif (value.startsWith(\"unix://\")) return value.slice(\"unix://\".length);\n\treturn value;\n}\n\n/**\n * Default launch: the host-lifecycle supervisor owns the public socket and the\n * idle-exit policy; it spawns the committed RPC socket host itself. Any extra\n * hostArgs are forwarded verbatim to the host CLI (e.g. provider pinning).\n */\nfunction defaultHostLaunch(\n\tsocket: string,\n\thostArgs: readonly string[],\n): {\n\tcommand: string;\n\targs: string[];\n} {\n\treturn {\n\t\tcommand: process.execPath,\n\t\targs: [...process.execArgv, resolveHostLifecycleEntryPath(), \"--socket\", socket, ...hostArgs],\n\t};\n}\n\nfunction resolveHostLifecycleEntryPath(): string {\n\tconst modulePath = fileURLToPath(import.meta.url);\n\tconst extension = modulePath.endsWith(\".ts\") ? \".ts\" : \".js\";\n\treturn resolve(dirname(modulePath), `host-lifecycle${extension}`);\n}\n\nfunction delay(ms: number): Promise<void> {\n\treturn new Promise((resolveDelay) => setTimeout(resolveDelay, ms));\n}\n\nfunction isRecord(value: unknown): value is Readonly<Record<string, unknown>> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction isNodeErrorCode(error: unknown, code: string): boolean {\n\treturn error instanceof Error && \"code\" in error && error.code === code;\n}\n"]}

package/dist/modes/rpc/host-lifecycle.d.ts

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+export type HostColdStart = "transient" | "persistent";
+/** Environment override for the cold-start policy: `transient` or `persistent`. */
+export declare const HOST_COLD_START_ENV = "SENPI_RPC_HOST_COLD_START";
+/** Environment override for the idle-exit window in milliseconds. */
+export declare const HOST_IDLE_EXIT_MS_ENV = "SENPI_RPC_HOST_IDLE_EXIT_MS";
+/** Default idle-exit window: 15 minutes of continuous no-connection, no-turn idle. */
+export declare const DEFAULT_HOST_IDLE_EXIT_MS: number;
+/** The policy fields ensureHost() records in rpc-host-daemon/settings.json. */
+export interface HostLifecyclePolicyInput {
+    readonly coldStart?: HostColdStart;
+    readonly idleExitMs?: number;
+}
+export interface HostLifecyclePolicy {
+    readonly coldStart: HostColdStart;
+    readonly idleExitMs: number;
+}
+export declare function parseColdStart(value: string | undefined): HostColdStart | undefined;
+export declare function parseIdleExitMs(value: string | undefined): number | undefined;
+/**
+ * Resolves the effective host policy. Precedence: environment overrides beat
+ * settings.json, which beats the documented defaults (transient, 15 minutes).
+ * Invalid values at either source fall through to the next source.
+ */
+export declare function resolveHostPolicy(settings: unknown, env: Readonly<Record<string, string | undefined>>): HostLifecyclePolicy;
+export interface HostActivity {
+    readonly connections: number;
+    readonly activeTurns: number;
+}
+export type IdleExitDecision = "active" | "idle" | "exit";
+/**
+ * Pure idle-window decision core. `update()` must be called with the CURRENT
+ * activity state; the window only counts continuously idle time and any
+ * activity resets it, so a busy host can never cross the threshold.
+ */
+export declare class IdleExitDecider {
+    private idleSince;
+    private readonly now;
+    readonly idleExitMs: number;
+    constructor(idleExitMs: number, now?: () => number);
+    update(activity: HostActivity): IdleExitDecision;
+}
+export interface SupervisorLaunch {
+    readonly socket: string;
+    readonly hostArgs: readonly string[];
+    /** Optional runtime command used by rebranded/bundled callers. */
+    readonly childCommand?: string;
+    readonly childArgs?: readonly string[];
+    /** Explicit ownership directory for callers whose environment is not yet branded. */
+    readonly agentDir?: string;
+}
+/** `--socket <path>` selects the public socket; every other argument is forwarded to the host CLI. */
+export declare function parseSupervisorArgs(argv: readonly string[]): SupervisorLaunch | undefined;
+/** Resolves the committed CLI entry this supervisor wraps (source tree or built dist). */
+export declare function resolveCliMainPath(): string;
+export declare function runHostSupervisor(launch: SupervisorLaunch): Promise<void>;
+//# sourceMappingURL=host-lifecycle.d.ts.map

package/dist/modes/rpc/host-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-lifecycle.d.ts","sourceRoot":"","sources":["../../../src/modes/rpc/host-lifecycle.ts"],"names":[],"mappings":";AAoDA,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,YAAY,CAAC;AAEvD,mFAAmF;AACnF,eAAO,MAAM,mBAAmB,8BAA8B,CAAC;AAC/D,qEAAqE;AACrE,eAAO,MAAM,qBAAqB,gCAAgC,CAAC;AACnE,sFAAsF;AACtF,eAAO,MAAM,yBAAyB,QAAc,CAAC;AAErD,+EAA+E;AAC/E,MAAM,WAAW,wBAAwB;IACxC,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC;IACnC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC5B;AAuBD,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa,GAAG,SAAS,CAEnF;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAI7E;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAChC,QAAQ,EAAE,OAAO,EACjB,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,GAC/C,mBAAmB,CASrB;AAED,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAE1D;;;;GAIG;AACH,qBAAa,eAAe;IAC3B,OAAO,CAAC,SAAS,CAAqB;IACtC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,UAAU,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,MAAiB;IAK5D,MAAM,CAAC,QAAQ,EAAE,YAAY,GAAG,gBAAgB;CAchD;AAED,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,kEAAkE;IAClE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,qFAAqF;IACrF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,sGAAsG;AACtG,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,gBAAgB,GAAG,SAAS,CAgCzF;AAED,0FAA0F;AAC1F,wBAAgB,kBAAkB,IAAI,MAAM,CAI3C;AAED,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoK/E"}