@astralyn/pi 0.84.4 → 0.84.6

package/dist/extensions/background/registry.d.ts

@@ -0,0 +1,220 @@
+/**
+ * Background task registry: process lifecycle, output capture, completion
+ * notification. Pure logic — no UI imports, dependencies injected for tests.
+ *
+ * Discipline (mirrors the reference implementation this extension distills):
+ * - Output streams straight to a file; memory holds only a byte counter.
+ * - Finalization is idempotent and strictly ordered: flush stream, set
+ *   terminal state, then notify. A notification is only sent once the output
+ *   file holds the complete truth.
+ * - Kill goes through AbortController; the shared bash operations kill the
+ *   whole process tree cross-platform.
+ */
+import type { BashOperations } from "../../core/tools/bash.ts";
+export declare const DEFAULT_MAX_OUTPUT_BYTES: number;
+export declare const DEFAULT_MAX_RUNNING_TASKS = 8;
+export declare const DEFAULT_NOTIFY_TAIL_BYTES: number;
+/** Wait-window bounds shared by execution and the pending-call renderer. */
+export declare const BG_WAIT_DEFAULT_MS = 20000;
+export declare const BG_WAIT_MIN_MS = 1000;
+export declare const BG_WAIT_MAX_MS = 60000;
+/** Stall watchdog defaults, matching Claude Code's CC-1175 tuning. */
+export declare const STALL_POLL_INTERVAL_MS = 5000;
+export declare const STALL_THRESHOLD_MS = 45000;
+export declare const STALL_TAIL_BYTES = 1024;
+export declare function looksLikePrompt(tail: string): boolean;
+export type BgTaskStatus = "running" | "completed" | "failed" | "killed" | "timeout";
+export interface BgTask {
+    id: string;
+    command: string;
+    /** Optional model-provided label (e.g. "dev server") shown in /bg and notifications. */
+    description?: string;
+    cwd: string;
+    status: BgTaskStatus;
+    startedAt: number;
+    endedAt?: number;
+    /** True when the stall watchdog flagged this task as waiting for input. */
+    stalled: boolean;
+    /** Process exit code; null when reaped by a signal, undefined while running or when spawn failed. */
+    exitCode: number | null | undefined;
+    outputPath: string;
+    /** Bytes accepted into the output file (excludes the overflow notice). */
+    outputBytes: number;
+    /** True when output hit the byte limit and the task was killed for it. */
+    outputTruncated: boolean;
+    error?: string;
+    timeoutSeconds?: number;
+    notified: boolean;
+}
+export interface BgTaskNotification {
+    task: BgTask;
+    /** Sanitized tail of the output file; empty when unavailable. */
+    tailText: string;
+    tailBytes: number;
+    totalBytes: number;
+    tailTruncated: boolean;
+    tailStartsMidLine: boolean;
+    /** Set when the output file could not be read; the notification still fires. */
+    tailError?: string;
+}
+/** One-shot signal that a running task appears blocked on interactive input. */
+export interface BgStallNotification {
+    task: BgTask;
+    tailText: string;
+    tailBytes: number;
+    totalBytes: number;
+    tailTruncated: boolean;
+    tailStartsMidLine: boolean;
+    tailError?: string;
+}
+export interface OutputSlice {
+    text: string;
+    sliceBytes: number;
+    totalBytes: number;
+    /** True when the file holds more bytes than the slice. */
+    truncated: boolean;
+    /** True in tail mode when the slice starts mid-line. */
+    startsMidLine: boolean;
+}
+/** Outcome of a bounded wait: terminal delivery, or the wait window expiring. */
+export type WaitOutcome = {
+    outcome: "terminal";
+    task: BgTask;
+} | {
+    outcome: "timeout";
+    task: BgTask;
+};
+/**
+ * Read a bounded slice from the head or tail of a file via positioned reads —
+ * never the whole file. Tail reads skip UTF-8 continuation bytes so the text
+ * starts on a codepoint boundary.
+ */
+export declare function readOutputSlice(filePath: string, options: {
+    mode: "head" | "tail";
+    maxBytes: number;
+}): Promise<OutputSlice>;
+/**
+ * Read the last `maxBytes` of a file starting no earlier than `fromByte` — the
+ * bounded delta since an offset, tail-aligned so the outcome (at the end of
+ * the output) is always included. `fromByte` is clamped into the file; the
+ * returned `fromByte` is where the slice actually starts.
+ */
+export declare function readOutputSince(filePath: string, fromByte: number, maxBytes: number): Promise<OutputSlice & {
+    fromByte: number;
+}>;
+export interface BackgroundRegistryOptions {
+    operations: BashOperations;
+    /** Directory for task output files. Defaults to the system temp directory. */
+    outputDir?: string;
+    maxOutputBytes?: number;
+    maxRunningTasks?: number;
+    notifyTailBytes?: number;
+    /** Called once per finished task; a synchronous throw rolls back `notified`. */
+    onNotify: (notification: BgTaskNotification) => void;
+    /** Called at most once per task when its output stalls on an interactive-looking prompt. */
+    onStall?: (notification: BgStallNotification) => void;
+    /** Stall watchdog tuning (tests inject short windows); defaults follow Claude Code's CC-1175. */
+    stall?: {
+        pollIntervalMs?: number;
+        thresholdMs?: number;
+        tailBytes?: number;
+    };
+    /** Called whenever a task starts or reaches a terminal state. */
+    onChange: () => void;
+    now?: () => number;
+}
+export type ResolveTaskResult = {
+    ok: true;
+    task: BgTask;
+} | {
+    ok: false;
+    reason: "not-found" | "ambiguous";
+    candidates: BgTask[];
+};
+export declare class BackgroundTaskRegistry {
+    private readonly operations;
+    private readonly outputDir;
+    private readonly maxOutputBytes;
+    private readonly maxRunningTasks;
+    private readonly notifyTailBytes;
+    private readonly onNotify;
+    private readonly onStall;
+    private readonly stallPollIntervalMs;
+    private readonly stallThresholdMs;
+    private readonly stallTailBytes;
+    private readonly onChange;
+    private readonly now;
+    private readonly tasks;
+    private readonly runtimes;
+    private shuttingDown;
+    constructor(options: BackgroundRegistryOptions);
+    get isShuttingDown(): boolean;
+    startTask(input: {
+        command: string;
+        cwd: string;
+        description?: string;
+        timeoutSeconds?: number;
+        env?: NodeJS.ProcessEnv;
+    }): BgTask;
+    getTask(id: string): BgTask | undefined;
+    /** Running tasks first (oldest first), then finished tasks (newest first). */
+    listTasks(): BgTask[];
+    /** Resolve a task by id or unique id prefix; the "bg-" prefix may be omitted. */
+    resolveTask(idPrefix: string): ResolveTaskResult;
+    killTask(id: string): {
+        killed: true;
+    } | {
+        killed: false;
+        reason: "not-found" | "not-running";
+    };
+    counts(): Record<BgTaskStatus, number> & {
+        total: number;
+        stalled: number;
+    };
+    /** Resolves once the task has finalized, including its notification attempt. */
+    waitForTask(id: string): Promise<BgTask>;
+    /**
+     * Bounded model-facing wait with the claim protocol: a waiter registered
+     * when the task finalizes takes over delivery — finalize sees waiters > 0
+     * and suppresses the followUp notification, so the completion is delivered
+     * exactly once, inline here. If the window expires first, the followUp
+     * notification is left untouched and fires as usual.
+     *
+     * All interleavings are deterministic on JS's single thread: a waiter that
+     * registers before finalize's synchronous claim check claims delivery; one
+     * that arrives after sees a terminal status and returns it immediately
+     * (the followUp may also arrive — an idempotent repeat, not a lie).
+     */
+    waitForResult(id: string, timeoutMs: number): Promise<WaitOutcome>;
+    /**
+     * Mute notifications, refuse new tasks, abort every running task, and wait
+     * (bounded) for their finalization.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Stall watchdog (Claude Code CC-1175): poll the output file; when output
+     * stops growing past the threshold AND the tail looks like an interactive
+     * prompt, flag the task and fire a one-shot notification. Merely-slow tasks
+     * never match; recovery clears the flag (the notification never re-fires).
+     */
+    private armStallWatchdog;
+    private clearStallWatchdog;
+    private checkStall;
+    private probeStallTail;
+    private newTaskId;
+    private run;
+    private handleData;
+    private finalize;
+    private classifyOutcome;
+    private notifyCompletion;
+}
+/**
+ * Create an empty output file exclusively ('wx'): fails on any existing path,
+ * including a symlink, so creation can never truncate what the path points at.
+ */
+export declare function createOutputFileExclusively(path: string): void;
+/** First non-empty line of a command, trimmed — for one-line task labels. */
+export declare function firstCommandLine(command: string): string;
+/** Compact duration like Pi's own timers: 12s, 3m05s, 1h02m. */
+export declare function formatDuration(ms: number): string;
+//# sourceMappingURL=registry.d.ts.map

package/dist/extensions/background/registry.d.ts.map

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