@ashx-j/lunr 0.1.0

package/dist/builtin-extensions/pi-subagents/src/runs/background/control-channel.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Cross-OS control channel for async subagent runs.
+ *
+ * Background runs are detached OS processes. The original control path delivered
+ * an interrupt with `process.kill(pid, SIGUSR2|SIGBREAK)`, but Windows cannot
+ * deliver those signals cross-process via `process.kill` and throws `ENOSYS`,
+ * which left async runs uninterruptible (no stop, no live steer) on Windows.
+ *
+ * This module adds a portable, file-based control inbox inside the run directory.
+ * The parent drops an interrupt request file; the runner watches the inbox and
+ * routes the request into its existing graceful `interruptRunner()` (pause +
+ * resumable), identically on every platform. The OS signal is kept only as an
+ * opportunistic fast-path; its failure is non-fatal because the file inbox is
+ * authoritative.
+ */
+import * as fs from "node:fs";
+/**
+ * Opportunistic fast-path interrupt signal. On Unix `SIGUSR2` is trapped by the
+ * runner; on Windows `process.kill(pid, "SIGBREAK")` is not deliverable
+ * cross-process and throws `ENOSYS`, so the file inbox below is the real channel.
+ */
+export declare const INTERRUPT_SIGNAL: NodeJS.Signals;
+export type ControlChannelFs = Pick<typeof fs, "mkdirSync" | "existsSync" | "rmSync" | "watch" | "readdirSync" | "readFileSync" | "realpathSync">;
+export type ControlChannelTimers = {
+    setInterval: typeof setInterval;
+    clearInterval: typeof clearInterval;
+};
+type KillFn = (pid: number, signal?: NodeJS.Signals | 0) => unknown;
+export interface InterruptRequest {
+    type: "interrupt";
+    ts?: number;
+    source?: string;
+    reason?: string;
+}
+export interface TimeoutRequest {
+    type: "timeout";
+    ts?: number;
+    source?: string;
+    reason?: string;
+}
+export interface StopRequest {
+    type: "stop";
+    ts?: number;
+    source?: string;
+    reason?: string;
+}
+export interface SteerRequest {
+    type: "steer";
+    id: string;
+    ts: number;
+    message: string;
+    targetIndex?: number;
+    targetIndexes?: number[];
+    source?: string;
+}
+export interface SteerCapability {
+    type: "steer-capability";
+    protocolVersion: 1;
+    index: number;
+    pid: number;
+    readyAt: number;
+    supported: boolean;
+}
+export interface SteerAck {
+    type: "steer-ack";
+    protocolVersion: 1;
+    requestId: string;
+    index: number;
+    ts: number;
+    state: "delivered" | "failed";
+    message: string;
+}
+/** Control inbox directory inside an async run dir. */
+export declare function controlInboxDir(asyncDir: string): string;
+/** Path of the portable interrupt request file. */
+export declare function interruptRequestPath(asyncDir: string): string;
+/** Path of the portable timeout request file. */
+export declare function timeoutRequestPath(asyncDir: string): string;
+/** Path of the portable manual stop request file. */
+export declare function stopRequestPath(asyncDir: string): string;
+/** Directory of parent-to-runner steering requests. */
+export declare function steerRequestsDir(asyncDir: string): string;
+export declare function steerInboxClosedPath(asyncDir: string): string;
+export declare function closeSteerInbox(asyncDir: string, state: string): void;
+/** Per-child inbox consumed by the child prompt runtime inside the Pi process. */
+export declare function stepSteerInboxDir(asyncDir: string, index: number): string;
+export declare function steerCapabilitiesDir(asyncDir: string): string;
+export declare function steerCapabilityPath(asyncDir: string, index: number): string;
+export declare function steerAcksDir(asyncDir: string, index: number): string;
+export declare function steerAckPathFromDir(dir: string, requestId: string): string;
+export declare function writeSteerRequestToDir(dir: string, request: SteerRequest): string;
+export declare function writeSteerCapabilityAt(filePath: string, capability: Omit<SteerCapability, "type" | "protocolVersion">): string;
+export declare function writeSteerCapability(asyncDir: string, capability: Omit<SteerCapability, "type" | "protocolVersion">): string;
+export declare function writeSteerAckAt(filePath: string, ack: Omit<SteerAck, "type" | "protocolVersion">): string;
+export declare function writeSteerAck(asyncDir: string, ack: Omit<SteerAck, "type" | "protocolVersion">): string;
+/**
+ * Parent side: drop a portable interrupt request the runner's inbox watcher will
+ * pick up regardless of OS. Written atomically (temp + rename), dir auto-created.
+ */
+export declare function requestAsyncInterrupt(asyncDir: string, payload?: Omit<InterruptRequest, "type">, deps?: {
+    now?: () => number;
+}): string;
+export declare function requestAsyncTimeout(asyncDir: string, payload?: Omit<TimeoutRequest, "type">, deps?: {
+    now?: () => number;
+}): string;
+export declare function requestAsyncStop(asyncDir: string, payload?: Omit<StopRequest, "type">, deps?: {
+    now?: () => number;
+}): string;
+export declare function requestAsyncSteer(asyncDir: string, payload: {
+    message: string;
+    targetIndex?: number;
+    targetIndexes?: number[];
+    source?: string;
+    id?: string;
+    ts?: number;
+}, deps?: {
+    now?: () => number;
+    randomId?: () => string;
+}): string;
+export declare function enqueueStepSteer(asyncDir: string, index: number, request: SteerRequest): string;
+export declare function readSteerCapability(asyncDir: string, index: number): SteerCapability | undefined;
+export declare function consumeSteerCapabilities(asyncDir: string, fsImpl?: Pick<typeof fs, "existsSync" | "readdirSync" | "readFileSync">): SteerCapability[];
+export declare function consumeSteerAcks(asyncDir: string, fsImpl?: Pick<typeof fs, "existsSync" | "readdirSync" | "readFileSync" | "rmSync">): SteerAck[];
+export declare function consumeSteerRequestsFromDir(dir: string, fsImpl?: Pick<typeof fs, "existsSync" | "rmSync" | "readdirSync" | "readFileSync">): SteerRequest[];
+export declare function consumeSteerRequests(asyncDir: string, fsImpl?: Pick<typeof fs, "existsSync" | "rmSync" | "readdirSync" | "readFileSync">): SteerRequest[];
+/**
+ * Runner side: consume a pending interrupt request. Idempotent — removes the file
+ * so each distinct request fires exactly once. Returns whether one was pending.
+ */
+export declare function consumeInterruptRequest(asyncDir: string, fsImpl?: Pick<typeof fs, "existsSync" | "rmSync">): boolean;
+export declare function consumeTimeoutRequest(asyncDir: string, fsImpl?: Pick<typeof fs, "existsSync" | "rmSync">): boolean;
+export declare function consumeStopRequest(asyncDir: string, fsImpl?: Pick<typeof fs, "existsSync" | "rmSync">): boolean;
+/**
+ * Parent side: portable interrupt = authoritative file request + best-effort OS
+ * signal. The signal is only a latency optimization on Unix; ENOSYS on Windows
+ * is swallowed because the file inbox is authoritative there. Other signal
+ * failures are surfaced because they usually mean the runner is not alive to
+ * consume the request.
+ */
+export declare function deliverInterruptRequest(input: {
+    asyncDir: string;
+    pid?: number;
+    kill?: KillFn;
+    signal?: NodeJS.Signals;
+    now?: () => number;
+    source?: string;
+}): void;
+export declare function deliverTimeoutRequest(input: {
+    asyncDir: string;
+    pid?: number;
+    kill?: KillFn;
+    signal?: NodeJS.Signals;
+    now?: () => number;
+    source?: string;
+}): void;
+export declare function deliverStopRequest(input: {
+    asyncDir: string;
+    pid?: number;
+    kill?: KillFn;
+    signal?: NodeJS.Signals;
+    now?: () => number;
+    source?: string;
+}): void;
+/**
+ * Runner side: watch the control inbox and route interrupt requests into
+ * `onInterrupt`. Uses `fs.watch` when available plus an interval poll as a
+ * portable safety net (covers filesystems/platforms where `fs.watch` is
+ * unreliable). Fires once per distinct request. Returns a disposer.
+ */
+export declare function watchAsyncControlInbox(asyncDir: string, opts: {
+    onInterrupt: () => void;
+    onTimeout?: () => void;
+    onStop?: () => void;
+    onSteer?: (request: SteerRequest) => void;
+    onSteerCapability?: (capability: SteerCapability) => void;
+    onSteerAck?: (ack: SteerAck) => void;
+    pollIntervalMs?: number;
+    fs?: ControlChannelFs;
+    timers?: ControlChannelTimers;
+}): () => void;
+export {};
+//# sourceMappingURL=control-channel.d.ts.map

package/dist/builtin-extensions/pi-subagents/src/runs/background/control-channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-channel.d.ts","sourceRoot":"","sources":["../../../../../../src/builtin-extensions/pi-subagents/src/runs/background/control-channel.ts"],"names":[],"mappings":"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","sourcesContent":["// @ts-nocheck\n/**\n * Cross-OS control channel for async subagent runs.\n *\n * Background runs are detached OS processes. The original control path delivered\n * an interrupt with `process.kill(pid, SIGUSR2|SIGBREAK)`, but Windows cannot\n * deliver those signals cross-process via `process.kill` and throws `ENOSYS`,\n * which left async runs uninterruptible (no stop, no live steer) on Windows.\n *\n * This module adds a portable, file-based control inbox inside the run directory.\n * The parent drops an interrupt request file; the runner watches the inbox and\n * routes the request into its existing graceful `interruptRunner()` (pause +\n * resumable), identically on every platform. The OS signal is kept only as an\n * opportunistic fast-path; its failure is non-fatal because the file inbox is\n * authoritative.\n */\n\nimport { randomUUID } from \"node:crypto\";\nimport * as fs from \"node:fs\";\nimport * as path from \"node:path\";\nimport { writeAtomicJson } from \"../../shared/atomic-json.ts\";\nimport { POLL_INTERVAL_MS } from \"../../shared/types.ts\";\nimport { resolveWatchPath } from \"../../shared/utils.ts\";\n\n/**\n * Opportunistic fast-path interrupt signal. On Unix `SIGUSR2` is trapped by the\n * runner; on Windows `process.kill(pid, \"SIGBREAK\")` is not deliverable\n * cross-process and throws `ENOSYS`, so the file inbox below is the real channel.\n */\nexport const INTERRUPT_SIGNAL: NodeJS.Signals = process.platform === \"win32\" ? \"SIGBREAK\" : \"SIGUSR2\";\n\nexport type ControlChannelFs = Pick<typeof fs, \"mkdirSync\" | \"existsSync\" | \"rmSync\" | \"watch\" | \"readdirSync\" | \"readFileSync\" | \"realpathSync\">;\nexport type ControlChannelTimers = { setInterval: typeof setInterval; clearInterval: typeof clearInterval };\ntype KillFn = (pid: number, signal?: NodeJS.Signals | 0) => unknown;\n\nexport interface InterruptRequest {\n\ttype: \"interrupt\";\n\tts?: number;\n\tsource?: string;\n\treason?: string;\n}\n\nexport interface TimeoutRequest {\n\ttype: \"timeout\";\n\tts?: number;\n\tsource?: string;\n\treason?: string;\n}\n\nexport interface StopRequest {\n\ttype: \"stop\";\n\tts?: number;\n\tsource?: string;\n\treason?: string;\n}\n\nexport interface SteerRequest {\n\ttype: \"steer\";\n\tid: string;\n\tts: number;\n\tmessage: string;\n\ttargetIndex?: number;\n\ttargetIndexes?: number[];\n\tsource?: string;\n}\n\nexport interface SteerCapability {\n\ttype: \"steer-capability\";\n\tprotocolVersion: 1;\n\tindex: number;\n\tpid: number;\n\treadyAt: number;\n\tsupported: boolean;\n}\n\nexport interface SteerAck {\n\ttype: \"steer-ack\";\n\tprotocolVersion: 1;\n\trequestId: string;\n\tindex: number;\n\tts: number;\n\tstate: \"delivered\" | \"failed\";\n\tmessage: string;\n}\n\nconst STEER_REQUESTS_DIR = \"steer-requests\";\nconst STEER_TARGETS_DIR = \"steer-targets\";\nconst STEER_CAPABILITIES_DIR = \"steer-capabilities\";\nconst STEER_ACKS_DIR = \"steer-acks\";\nconst STEER_INBOX_CLOSED_FILE = \"steer-inbox-closed.json\";\nconst MAX_STEER_MESSAGE_BYTES = 128 * 1024;\nconst MAX_STEER_REQUEST_ID_LENGTH = 256;\n\n/** Control inbox directory inside an async run dir. */\nexport function controlInboxDir(asyncDir: string): string {\n\treturn path.join(asyncDir, \"control\");\n}\n\n/** Path of the portable interrupt request file. */\nexport function interruptRequestPath(asyncDir: string): string {\n\treturn path.join(controlInboxDir(asyncDir), \"interrupt.json\");\n}\n\n/** Path of the portable timeout request file. */\nexport function timeoutRequestPath(asyncDir: string): string {\n\treturn path.join(controlInboxDir(asyncDir), \"timeout.json\");\n}\n\n/** Path of the portable manual stop request file. */\nexport function stopRequestPath(asyncDir: string): string {\n\treturn path.join(controlInboxDir(asyncDir), \"stop.json\");\n}\n\n/** Directory of parent-to-runner steering requests. */\nexport function steerRequestsDir(asyncDir: string): string {\n\treturn path.join(controlInboxDir(asyncDir), STEER_REQUESTS_DIR);\n}\n\nexport function steerInboxClosedPath(asyncDir: string): string {\n\treturn path.join(controlInboxDir(asyncDir), STEER_INBOX_CLOSED_FILE);\n}\n\nexport function closeSteerInbox(asyncDir: string, state: string): void {\n\twriteAtomicJson(steerInboxClosedPath(asyncDir), { version: 1, closedAt: Date.now(), state });\n}\n\n/** Per-child inbox consumed by the child prompt runtime inside the Pi process. */\nexport function stepSteerInboxDir(asyncDir: string, index: number): string {\n\tassertChildIndex(index);\n\treturn path.join(controlInboxDir(asyncDir), STEER_TARGETS_DIR, String(index));\n}\n\nexport function steerCapabilitiesDir(asyncDir: string): string {\n\treturn path.join(controlInboxDir(asyncDir), STEER_CAPABILITIES_DIR);\n}\n\nexport function steerCapabilityPath(asyncDir: string, index: number): string {\n\tassertChildIndex(index);\n\treturn path.join(steerCapabilitiesDir(asyncDir), `${index}.json`);\n}\n\nexport function steerAcksDir(asyncDir: string, index: number): string {\n\tassertChildIndex(index);\n\treturn path.join(controlInboxDir(asyncDir), STEER_ACKS_DIR, String(index));\n}\n\nfunction steerAckFileName(requestId: string): string {\n\treturn `${Buffer.from(requestId).toString(\"base64url\")}.json`;\n}\n\nexport function steerAckPathFromDir(dir: string, requestId: string): string {\n\tif (!/^[^\\s]+$/.test(requestId) || requestId.length > 256) throw new Error(\"steer acknowledgment requestId is invalid.\");\n\treturn path.join(dir, steerAckFileName(requestId));\n}\n\nfunction assertChildIndex(index: number): void {\n\tif (!Number.isInteger(index) || index < 0 || index > 1_000_000) throw new Error(\"steer child index must be a non-negative integer.\");\n}\n\nfunction steerRequestFileName(request: SteerRequest): string {\n\treturn `${String(request.ts).padStart(13, \"0\")}-${Buffer.from(request.id).toString(\"base64url\")}.json`;\n}\n\nfunction validSteerRequest(request: Partial<SteerRequest>): request is SteerRequest {\n\treturn request.type === \"steer\"\n\t\t&& typeof request.id === \"string\"\n\t\t&& /^[^\\s]+$/.test(request.id)\n\t\t&& request.id.length <= MAX_STEER_REQUEST_ID_LENGTH\n\t\t&& typeof request.ts === \"number\"\n\t\t&& Number.isFinite(request.ts)\n\t\t&& request.ts > 0\n\t\t&& typeof request.message === \"string\"\n\t\t&& Boolean(request.message.trim())\n\t\t&& Buffer.byteLength(request.message, \"utf8\") <= MAX_STEER_MESSAGE_BYTES\n\t\t&& (request.targetIndex === undefined || (Number.isInteger(request.targetIndex) && request.targetIndex >= 0 && request.targetIndex <= 1_000_000))\n\t\t&& (request.targetIndexes === undefined || (\n\t\t\trequest.targetIndex === undefined\n\t\t\t&& Array.isArray(request.targetIndexes)\n\t\t\t&& request.targetIndexes.length > 0\n\t\t\t&& request.targetIndexes.length <= 1_000\n\t\t\t&& request.targetIndexes.every((index) => Number.isInteger(index) && index >= 0 && index <= 1_000_000)\n\t\t\t&& new Set(request.targetIndexes).size === request.targetIndexes.length\n\t\t))\n\t\t&& (request.source === undefined || (typeof request.source === \"string\" && Boolean(request.source.trim()) && request.source.length <= 256));\n}\n\nexport function writeSteerRequestToDir(dir: string, request: SteerRequest): string {\n\tif (!validSteerRequest(request)) throw new Error(\"steer request is malformed or exceeds transport limits.\");\n\tconst requestPath = path.join(dir, steerRequestFileName(request));\n\twriteAtomicJson(requestPath, request);\n\treturn requestPath;\n}\n\nexport function writeSteerCapabilityAt(filePath: string, capability: Omit<SteerCapability, \"type\" | \"protocolVersion\">): string {\n\tassertChildIndex(capability.index);\n\tif (!Number.isInteger(capability.pid) || capability.pid <= 0) throw new Error(\"steer capability pid must be a positive integer.\");\n\tif (!Number.isFinite(capability.readyAt) || capability.readyAt <= 0) throw new Error(\"steer capability readyAt must be a finite timestamp.\");\n\tconst record: SteerCapability = { type: \"steer-capability\", protocolVersion: 1, ...capability };\n\twriteAtomicJson(filePath, record);\n\treturn filePath;\n}\n\nexport function writeSteerCapability(asyncDir: string, capability: Omit<SteerCapability, \"type\" | \"protocolVersion\">): string {\n\treturn writeSteerCapabilityAt(steerCapabilityPath(asyncDir, capability.index), capability);\n}\n\nexport function writeSteerAckAt(filePath: string, ack: Omit<SteerAck, \"type\" | \"protocolVersion\">): string {\n\tassertChildIndex(ack.index);\n\tif (!/^[^\\s]+$/.test(ack.requestId) || ack.requestId.length > 256) throw new Error(\"steer acknowledgment requestId is invalid.\");\n\tif (!Number.isFinite(ack.ts) || ack.ts <= 0) throw new Error(\"steer acknowledgment ts must be a finite timestamp.\");\n\tif (!ack.message.trim() || ack.message.length > 1000) throw new Error(\"steer acknowledgment message is invalid.\");\n\tconst record: SteerAck = { type: \"steer-ack\", protocolVersion: 1, ...ack, message: ack.message.trim() };\n\twriteAtomicJson(filePath, record);\n\treturn filePath;\n}\n\nexport function writeSteerAck(asyncDir: string, ack: Omit<SteerAck, \"type\" | \"protocolVersion\">): string {\n\treturn writeSteerAckAt(path.join(steerAcksDir(asyncDir, ack.index), steerAckFileName(ack.requestId)), ack);\n}\n\n/**\n * Parent side: drop a portable interrupt request the runner's inbox watcher will\n * pick up regardless of OS. Written atomically (temp + rename), dir auto-created.\n */\nexport function requestAsyncInterrupt(\n\tasyncDir: string,\n\tpayload: Omit<InterruptRequest, \"type\"> = {},\n\tdeps: { now?: () => number } = {},\n): string {\n\tconst requestPath = interruptRequestPath(asyncDir);\n\tconst request: InterruptRequest = { ...payload, ts: payload.ts ?? deps.now?.() ?? Date.now(), type: \"interrupt\" };\n\twriteAtomicJson(requestPath, request);\n\treturn requestPath;\n}\n\nexport function requestAsyncTimeout(\n\tasyncDir: string,\n\tpayload: Omit<TimeoutRequest, \"type\"> = {},\n\tdeps: { now?: () => number } = {},\n): string {\n\tconst requestPath = timeoutRequestPath(asyncDir);\n\tconst request: TimeoutRequest = { ...payload, ts: payload.ts ?? deps.now?.() ?? Date.now(), type: \"timeout\" };\n\twriteAtomicJson(requestPath, request);\n\treturn requestPath;\n}\n\nexport function requestAsyncStop(\n\tasyncDir: string,\n\tpayload: Omit<StopRequest, \"type\"> = {},\n\tdeps: { now?: () => number } = {},\n): string {\n\tconst requestPath = stopRequestPath(asyncDir);\n\tconst request: StopRequest = { ...payload, ts: payload.ts ?? deps.now?.() ?? Date.now(), type: \"stop\" };\n\twriteAtomicJson(requestPath, request);\n\treturn requestPath;\n}\n\nexport function requestAsyncSteer(\n\tasyncDir: string,\n\tpayload: { message: string; targetIndex?: number; targetIndexes?: number[]; source?: string; id?: string; ts?: number },\n\tdeps: { now?: () => number; randomId?: () => string } = {},\n): string {\n\tconst message = payload.message.trim();\n\tif (!message) throw new Error(\"steer message must not be empty.\");\n\tif (Buffer.byteLength(message, \"utf8\") > MAX_STEER_MESSAGE_BYTES) throw new Error(`steer message exceeds ${MAX_STEER_MESSAGE_BYTES} UTF-8 bytes.`);\n\tif (payload.targetIndex !== undefined && (!Number.isInteger(payload.targetIndex) || payload.targetIndex < 0 || payload.targetIndex > 1_000_000)) {\n\t\tthrow new Error(\"steer targetIndex must be an integer between 0 and 1000000.\");\n\t}\n\tif (payload.targetIndexes !== undefined && (\n\t\t!Array.isArray(payload.targetIndexes)\n\t\t|| payload.targetIndex !== undefined\n\t\t|| payload.targetIndexes.length === 0\n\t\t|| payload.targetIndexes.length > 1_000\n\t\t|| payload.targetIndexes.some((index) => !Number.isInteger(index) || index < 0 || index > 1_000_000)\n\t\t|| new Set(payload.targetIndexes).size !== payload.targetIndexes.length\n\t)) {\n\t\tthrow new Error(\"steer targetIndexes must contain 1-1000 unique non-negative integers and cannot be combined with targetIndex.\");\n\t}\n\tconst closedPath = steerInboxClosedPath(asyncDir);\n\tif (fs.existsSync(closedPath)) throw new Error(\"Async run no longer accepts steering requests.\");\n\tconst request: SteerRequest = {\n\t\ttype: \"steer\",\n\t\tid: payload.id ?? deps.randomId?.() ?? randomUUID(),\n\t\tts: payload.ts ?? deps.now?.() ?? Date.now(),\n\t\tmessage,\n\t\t...(payload.targetIndex !== undefined ? { targetIndex: payload.targetIndex } : {}),\n\t\t...(payload.targetIndexes !== undefined ? { targetIndexes: [...payload.targetIndexes] } : {}),\n\t\t...(payload.source ? { source: payload.source } : {}),\n\t};\n\tconst requestPath = writeSteerRequestToDir(steerRequestsDir(asyncDir), request);\n\tif (fs.existsSync(closedPath)) {\n\t\tfs.rmSync(requestPath, { force: true });\n\t\tthrow new Error(\"Async run stopped accepting steering before the request was committed.\");\n\t}\n\treturn requestPath;\n}\n\nexport function enqueueStepSteer(asyncDir: string, index: number, request: SteerRequest): string {\n\tassertChildIndex(index);\n\tconst { targetIndexes: _targetIndexes, ...singleTargetRequest } = request;\n\treturn writeSteerRequestToDir(stepSteerInboxDir(asyncDir, index), { ...singleTargetRequest, targetIndex: index, type: \"steer\" });\n}\n\nfunction parseSteerCapability(raw: unknown): SteerCapability | undefined {\n\tif (!raw || typeof raw !== \"object\" || Array.isArray(raw)) return undefined;\n\tconst input = raw as Partial<SteerCapability>;\n\tif (input.type !== \"steer-capability\" || input.protocolVersion !== 1) return undefined;\n\tif (!Number.isInteger(input.index) || input.index < 0 || input.index > 1_000_000) return undefined;\n\tif (!Number.isInteger(input.pid) || input.pid <= 0 || !Number.isFinite(input.readyAt) || input.readyAt <= 0 || typeof input.supported !== \"boolean\") return undefined;\n\treturn { type: \"steer-capability\", protocolVersion: 1, index: input.index, pid: input.pid, readyAt: input.readyAt, supported: input.supported };\n}\n\nfunction parseSteerAck(raw: unknown): SteerAck | undefined {\n\tif (!raw || typeof raw !== \"object\" || Array.isArray(raw)) return undefined;\n\tconst input = raw as Partial<SteerAck>;\n\tif (input.type !== \"steer-ack\" || input.protocolVersion !== 1 || typeof input.requestId !== \"string\" || !/^[^\\s]+$/.test(input.requestId) || input.requestId.length > 256) return undefined;\n\tif (!Number.isInteger(input.index) || input.index < 0 || input.index > 1_000_000 || !Number.isFinite(input.ts) || input.ts <= 0) return undefined;\n\tif (input.state !== \"delivered\" && input.state !== \"failed\") return undefined;\n\tif (typeof input.message !== \"string\" || !input.message.trim() || input.message.length > 1000) return undefined;\n\treturn { type: \"steer-ack\", protocolVersion: 1, requestId: input.requestId, index: input.index, ts: input.ts, state: input.state, message: input.message.trim() };\n}\n\nexport function readSteerCapability(asyncDir: string, index: number): SteerCapability | undefined {\n\ttry {\n\t\treturn parseSteerCapability(JSON.parse(fs.readFileSync(steerCapabilityPath(asyncDir, index), \"utf-8\")));\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\nexport function consumeSteerCapabilities(asyncDir: string, fsImpl: Pick<typeof fs, \"existsSync\" | \"readdirSync\" | \"readFileSync\"> = fs): SteerCapability[] {\n\tconst dir = steerCapabilitiesDir(asyncDir);\n\tif (!fsImpl.existsSync(dir)) return [];\n\tconst capabilities: SteerCapability[] = [];\n\tfor (const entry of fsImpl.readdirSync(dir).filter((name) => /^\\d+\\.json$/.test(name)).sort()) {\n\t\ttry {\n\t\t\tconst capability = parseSteerCapability(JSON.parse(fsImpl.readFileSync(path.join(dir, entry), \"utf-8\")));\n\t\t\tif (capability) capabilities.push(capability);\n\t\t} catch {\n\t\t\t// A partially written or malformed capability is ignored until a valid one arrives.\n\t\t}\n\t}\n\treturn capabilities;\n}\n\nexport function consumeSteerAcks(asyncDir: string, fsImpl: Pick<typeof fs, \"existsSync\" | \"readdirSync\" | \"readFileSync\" | \"rmSync\"> = fs): SteerAck[] {\n\tconst root = path.join(controlInboxDir(asyncDir), STEER_ACKS_DIR);\n\tif (!fsImpl.existsSync(root)) return [];\n\tconst acks: SteerAck[] = [];\n\tlet indexNames: string[];\n\ttry { indexNames = fsImpl.readdirSync(root).filter((name) => /^\\d+$/.test(name)); } catch { return []; }\n\tfor (const indexName of indexNames) {\n\t\tconst dir = path.join(root, indexName);\n\t\tlet entries: string[];\n\t\ttry { entries = fsImpl.readdirSync(dir).filter((name) => name.endsWith(\".json\")).sort(); } catch { continue; }\n\t\tfor (const entry of entries) {\n\t\t\tconst target = path.join(dir, entry);\n\t\t\tlet ack: SteerAck | undefined;\n\t\t\ttry { ack = parseSteerAck(JSON.parse(fsImpl.readFileSync(target, \"utf-8\"))); } catch { ack = undefined; }\n\t\t\ttry { fsImpl.rmSync(target, { force: true }); } catch { continue; }\n\t\t\tif (ack) acks.push(ack);\n\t\t}\n\t}\n\treturn acks;\n}\n\nfunction parseSteerRequest(raw: unknown): SteerRequest | undefined {\n\tif (!raw || typeof raw !== \"object\" || Array.isArray(raw)) return undefined;\n\tconst input = raw as Partial<SteerRequest>;\n\tif (!validSteerRequest(input)) return undefined;\n\treturn {\n\t\ttype: \"steer\",\n\t\tid: input.id.trim(),\n\t\tts: input.ts,\n\t\tmessage: input.message.trim(),\n\t\t...(input.targetIndex !== undefined ? { targetIndex: input.targetIndex } : {}),\n\t\t...(input.targetIndexes !== undefined ? { targetIndexes: [...input.targetIndexes] } : {}),\n\t\t...(typeof input.source === \"string\" && input.source.trim() ? { source: input.source } : {}),\n\t};\n}\n\nexport function consumeSteerRequestsFromDir(dir: string, fsImpl: Pick<typeof fs, \"existsSync\" | \"rmSync\" | \"readdirSync\" | \"readFileSync\"> = fs): SteerRequest[] {\n\tif (!fsImpl.existsSync(dir)) return [];\n\tconst requests: SteerRequest[] = [];\n\tfor (const entry of fsImpl.readdirSync(dir).filter((name) => name.endsWith(\".json\")).sort()) {\n\t\tconst requestPath = path.join(dir, entry);\n\t\tlet parsed: SteerRequest | undefined;\n\t\ttry {\n\t\t\tparsed = parseSteerRequest(JSON.parse(fsImpl.readFileSync(requestPath, \"utf-8\")));\n\t\t} catch {\n\t\t\tparsed = undefined;\n\t\t}\n\t\ttry {\n\t\t\tfsImpl.rmSync(requestPath, { recursive: true });\n\t\t} catch {\n\t\t\t// Already removed by a concurrent check — do not execute it twice.\n\t\t\tcontinue;\n\t\t}\n\t\tif (parsed) requests.push(parsed);\n\t}\n\treturn requests.sort((left, right) => left.ts - right.ts || left.id.localeCompare(right.id));\n}\n\nexport function consumeSteerRequests(asyncDir: string, fsImpl: Pick<typeof fs, \"existsSync\" | \"rmSync\" | \"readdirSync\" | \"readFileSync\"> = fs): SteerRequest[] {\n\treturn consumeSteerRequestsFromDir(steerRequestsDir(asyncDir), fsImpl);\n}\n\n/**\n * Runner side: consume a pending interrupt request. Idempotent — removes the file\n * so each distinct request fires exactly once. Returns whether one was pending.\n */\nexport function consumeInterruptRequest(\n\tasyncDir: string,\n\tfsImpl: Pick<typeof fs, \"existsSync\" | \"rmSync\"> = fs,\n): boolean {\n\tconst requestPath = interruptRequestPath(asyncDir);\n\tif (!fsImpl.existsSync(requestPath)) return false;\n\ttry {\n\t\tfsImpl.rmSync(requestPath, { force: true, recursive: true });\n\t} catch {\n\t\t// Already removed by a concurrent check — still counts as consumed.\n\t}\n\treturn true;\n}\n\nexport function consumeTimeoutRequest(\n\tasyncDir: string,\n\tfsImpl: Pick<typeof fs, \"existsSync\" | \"rmSync\"> = fs,\n): boolean {\n\tconst requestPath = timeoutRequestPath(asyncDir);\n\tif (!fsImpl.existsSync(requestPath)) return false;\n\ttry {\n\t\tfsImpl.rmSync(requestPath, { force: true, recursive: true });\n\t} catch {\n\t\t// Already removed by a concurrent check — still counts as consumed.\n\t}\n\treturn true;\n}\n\nexport function consumeStopRequest(\n\tasyncDir: string,\n\tfsImpl: Pick<typeof fs, \"existsSync\" | \"rmSync\"> = fs,\n): boolean {\n\tconst requestPath = stopRequestPath(asyncDir);\n\tif (!fsImpl.existsSync(requestPath)) return false;\n\ttry {\n\t\tfsImpl.rmSync(requestPath, { force: true, recursive: true });\n\t} catch {\n\t\t// Already removed by a concurrent check — still counts as consumed.\n\t}\n\treturn true;\n}\n\n/**\n * Parent side: portable interrupt = authoritative file request + best-effort OS\n * signal. The signal is only a latency optimization on Unix; ENOSYS on Windows\n * is swallowed because the file inbox is authoritative there. Other signal\n * failures are surfaced because they usually mean the runner is not alive to\n * consume the request.\n */\nexport function deliverInterruptRequest(input: {\n\tasyncDir: string;\n\tpid?: number;\n\tkill?: KillFn;\n\tsignal?: NodeJS.Signals;\n\tnow?: () => number;\n\tsource?: string;\n}): void {\n\tconst requestPath = requestAsyncInterrupt(input.asyncDir, input.source ? { source: input.source } : {}, { now: input.now });\n\tif (typeof input.pid === \"number\" && input.pid > 0) {\n\t\ttry {\n\t\t\t(input.kill ?? process.kill)(input.pid, input.signal ?? INTERRUPT_SIGNAL);\n\t\t} catch (error) {\n\t\t\tif ((error as NodeJS.ErrnoException | undefined)?.code === \"ENOSYS\") {\n\t\t\t\t// File inbox is authoritative when custom cross-process signals are unavailable.\n\t\t\t\treturn;\n\t\t\t}\n\t\t\ttry {\n\t\t\t\tfs.rmSync(requestPath, { force: true });\n\t\t\t} catch {\n\t\t\t\t// Best effort cleanup; the caller still gets the signal failure.\n\t\t\t}\n\t\t\tthrow error;\n\t\t}\n\t}\n}\n\nexport function deliverTimeoutRequest(input: {\n\tasyncDir: string;\n\tpid?: number;\n\tkill?: KillFn;\n\tsignal?: NodeJS.Signals;\n\tnow?: () => number;\n\tsource?: string;\n}): void {\n\trequestAsyncTimeout(input.asyncDir, input.source ? { source: input.source } : {}, { now: input.now });\n}\n\nexport function deliverStopRequest(input: {\n\tasyncDir: string;\n\tpid?: number;\n\tkill?: KillFn;\n\tsignal?: NodeJS.Signals;\n\tnow?: () => number;\n\tsource?: string;\n}): void {\n\trequestAsyncStop(input.asyncDir, input.source ? { source: input.source } : {}, { now: input.now });\n}\n\n/**\n * Runner side: watch the control inbox and route interrupt requests into\n * `onInterrupt`. Uses `fs.watch` when available plus an interval poll as a\n * portable safety net (covers filesystems/platforms where `fs.watch` is\n * unreliable). Fires once per distinct request. Returns a disposer.\n */\nexport function watchAsyncControlInbox(\n\tasyncDir: string,\n\topts: {\n\t\tonInterrupt: () => void;\n\t\tonTimeout?: () => void;\n\t\tonStop?: () => void;\n\t\tonSteer?: (request: SteerRequest) => void;\n\t\tonSteerCapability?: (capability: SteerCapability) => void;\n\t\tonSteerAck?: (ack: SteerAck) => void;\n\t\tpollIntervalMs?: number;\n\t\tfs?: ControlChannelFs;\n\t\ttimers?: ControlChannelTimers;\n\t},\n): () => void {\n\tconst fsImpl = opts.fs ?? fs;\n\tconst timers = opts.timers ?? { setInterval, clearInterval };\n\tconst dir = controlInboxDir(asyncDir);\n\ttry {\n\t\tfsImpl.mkdirSync(dir, { recursive: true });\n\t} catch {\n\t\t// Best effort — the poll/watch below tolerates a missing dir.\n\t}\n\n\tlet disposed = false;\n\tconst check = (): void => {\n\t\tif (disposed) return;\n\t\ttry {\n\t\t\tif (consumeStopRequest(asyncDir, fsImpl)) opts.onStop?.();\n\t\t\tif (consumeTimeoutRequest(asyncDir, fsImpl)) opts.onTimeout?.();\n\t\t\tif (consumeInterruptRequest(asyncDir, fsImpl)) opts.onInterrupt();\n\t\t\tfor (const request of consumeSteerRequests(asyncDir, fsImpl)) opts.onSteer?.(request);\n\t\t\tfor (const capability of consumeSteerCapabilities(asyncDir, fsImpl)) opts.onSteerCapability?.(capability);\n\t\t\tfor (const ack of consumeSteerAcks(asyncDir, fsImpl)) opts.onSteerAck?.(ack);\n\t\t} catch {\n\t\t\t// Never let inbox errors crash the runner.\n\t\t}\n\t};\n\n\t// Handle a request that may have arrived before the watcher started.\n\tcheck();\n\n\tlet watcher: fs.FSWatcher | undefined;\n\ttry {\n\t\twatcher = fsImpl.watch(resolveWatchPath(dir, fsImpl.realpathSync.native), () => check());\n\t\twatcher.on?.(\"error\", () => {\n\t\t\t// fs.watch can emit on transient FS errors; the interval poll keeps us live.\n\t\t});\n\t} catch {\n\t\twatcher = undefined;\n\t}\n\n\tconst interval = timers.setInterval(check, opts.pollIntervalMs ?? POLL_INTERVAL_MS);\n\tinterval.unref?.();\n\n\treturn () => {\n\t\tif (disposed) return;\n\t\tdisposed = true;\n\t\ttry {\n\t\t\twatcher?.close();\n\t\t} catch {\n\t\t\t// ignore\n\t\t}\n\t\ttimers.clearInterval(interval);\n\t};\n}\n"]}