@emiliosp/pi-maestro 0.0.0-stage → 0.1.0

package/node_modules/pi-subagents/src/runs/background/control-channel.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Cross-OS control channel for async subagent runs.
+ *
+ * Background runs use a detached runner process. Unix detaches it from the parent process.
+ * 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 file inbox is authoritative and
+ * avoids signaling a PID that the extension cannot prove belongs to the runner.
+ */
+import * as fs from "node:fs";
+import { writeAtomicJson } from "../../shared/atomic-json.ts";
+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;
+    targetIndex?: number;
+    childId?: string;
+}
+export type SteerDeliveryMode = "steer" | "follow_up" | "auto";
+export type SteerDeliveryStatus = "delivered" | "queued";
+export interface SteerRequest {
+    type: "steer";
+    id: string;
+    ts: number;
+    message: string;
+    mode?: SteerDeliveryMode;
+    targetIndex?: number;
+    targetIndexes?: number[];
+    source?: string;
+}
+export interface CommandRequest {
+    type: "command";
+    id: string;
+    ownerId: string;
+    operation: "status" | "yield" | "cancel";
+    toolCallId?: string;
+    deadlineAt: number;
+}
+export declare function requestAsyncCommand(dir: string, request: CommandRequest): void;
+export declare const MAX_STEER_QUEUE_SIZE = 20;
+/** 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 stop requests. */
+export declare function stopRequestsDir(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 stopInboxClosedPath(asyncDir: string): string;
+export declare function closeStopInbox(asyncDir: string): void;
+export declare function closeSteerInbox(asyncDir: string, state: string, write?: (filePath: string, payload: object) => void): void;
+export declare function writeSteerRequestToDir(dir: string, request: SteerRequest): string;
+export declare function writeSteerRequestToExistingDir(dir: string, request: SteerRequest): 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;
+    write?: typeof writeAtomicJson;
+}): string;
+export declare function requestAsyncSteer(asyncDir: string, payload: {
+    message: string;
+    mode?: SteerDeliveryMode;
+    targetIndex?: number;
+    targetIndexes?: number[];
+    source?: string;
+    id?: string;
+    ts?: number;
+}, deps?: {
+    now?: () => number;
+    randomId?: () => string;
+}): string;
+export declare function consumeSteerRequestsFromDir(dir: string, fsImpl?: Pick<typeof fs, "existsSync" | "rmSync" | "readdirSync" | "readFileSync">, onError?: (error: unknown) => void): SteerRequest[];
+export declare function consumeSteerRequests(asyncDir: string, fsImpl?: Pick<typeof fs, "existsSync" | "rmSync" | "readdirSync" | "readFileSync">, onError?: (error: unknown) => void): SteerRequest[];
+export declare function queueRevivalBrief(asyncDir: string, request: SteerRequest): string;
+export declare function readRevivalBriefs(asyncDir: string): Array<{
+    request: SteerRequest;
+    path: string;
+}>;
+/**
+ * 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" | "readdirSync" | "readFileSync">): boolean;
+export declare function consumeStopRequestPayloads(asyncDir: string, fsImpl?: Pick<typeof fs, "existsSync" | "rmSync" | "readdirSync" | "readFileSync">, onError?: (error: unknown) => void): StopRequest[];
+export declare function consumeStopRequestPayload(asyncDir: string, fsImpl?: Pick<typeof fs, "existsSync" | "rmSync" | "readdirSync" | "readFileSync">): StopRequest | undefined;
+/** Parent side: write the authoritative portable interrupt request. */
+export declare function deliverInterruptRequest(input: {
+    asyncDir: string;
+    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;
+    targetIndex?: number;
+    childId?: string;
+}): void;
+/**
+ * Active owner: watch and consume only kinds with installed handlers.
+ * Uses `fs.watch` when available and starts interval polling
+ * only when native watching is unavailable or fails. Fires once per distinct
+ * request. Returns a disposer.
+ */
+export declare function watchAsyncControlInbox(asyncDir: string, opts: {
+    onInterrupt?: () => void;
+    onTimeout?: () => void;
+    onStop?: (request: StopRequest) => void;
+    onSteer?: (request: SteerRequest) => void;
+    onCommand?: (request: CommandRequest) => void;
+    onError?: (error: unknown, phase: "install" | "scan" | "callback", request?: SteerRequest) => void;
+    pollIntervalMs?: number;
+    safetyPollIntervalMs?: number;
+    platform?: NodeJS.Platform;
+    fs?: ControlChannelFs;
+    timers?: ControlChannelTimers;
+}): () => void;
+export {};
+//# sourceMappingURL=control-channel.d.ts.map

package/node_modules/pi-subagents/src/runs/background/control-channel.d.ts.map

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