hoomanjs 1.46.0 → 1.47.0

package/dist/core/modes/definitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../../src/core/modes/definitions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../../src/core/modes/definitions.ts"],"names":[],"mappings":"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"}

package/dist/core/prompts/static/shell.md

@@ -1,6 +1,6 @@
 ## Shell
 
-You have access to a `shell` tool for local command execution.
+You have access to a `shell` tool for local command execution, plus `shell_output` and `shell_stop` for managing background jobs.
 
 - Use `shell` when local command execution is the most direct way to inspect, verify, or operate on the environment.
 - Prefer dedicated file and search tools when the task is fundamentally about files or text.
@@ -9,3 +9,23 @@ You have access to a `shell` tool for local command execution.
 - Use sensible timeouts, use `ignore_errors` only when partial success is acceptable, and prefer commands or flags with naturally bounded output.
 - Summarize important command output instead of echoing long logs back to the user.
 - Avoid destructive or risky commands unless they are clearly necessary and appropriate, and be careful with package managers, process control, and commands that affect the wider system.
+
+### Background jobs
+
+For long-running processes (dev servers, watchers, monitors, builds that should keep going):
+
+- Set `run_in_background: true` with a short `description` (required). The tool returns a `job_id` immediately while the process keeps running.
+- Or use `block_until_ms: 0` (same as immediate background) / a positive `block_until_ms` to wait up to that long before detaching.
+- Use `notify_on_output: { pattern }` to block until a regex matches output, then return a `job_id` while the process continues (e.g. wait for a log line).
+- Use `ready: { pattern?, port?, timeout_ms? }` to wait until a readiness probe succeeds (regex and/or local TCP port) before returning.
+- Background mode supports a **single** command only (not command arrays) and does not support `stdin`.
+
+Managing jobs (for you — do not explain these tools to the user unless they ask):
+
+- `shell_output` — read output; by default blocks until exit. Pass `block: false` for a snapshot, or `pattern` to wait for a new match. Prefer one wait with a reasonable `timeout_ms` over tight polling loops.
+- `shell_stop` — kill the job by `job_id`.
+- Do not start a second copy of a server that is already running as a background job; use `shell_output` / `shell_stop` instead.
+- Job completion is also surfaced as a notification; you do not need to poll continuously.
+- The UI shows active background jobs and a Stop control; the user can also ask you to stop a job in plain language.
+
+When you start a background job, reply in one or two short sentences (what is running). Do **not** dump `job_id`, tool names, parameter recipes, or “how to use shell_output / shell_stop” unless the user asks how to manage it.

package/dist/core/shell/index.d.ts

@@ -0,0 +1,7 @@
+export type { HostTerminalHandle, NotifyOnOutput, ReadyProbe, ShellJobEvent, ShellJobInfo, ShellJobListener, ShellJobOutputSnapshot, ShellJobStartOptions, ShellJobStatus, ShellJobWaitOptions, } from "./types.js";
+export { OutputBuffer, RING_CAPACITY_BYTES, WATCHDOG_MAX_BYTES, } from "./output-buffer.js";
+export { ShellJobManager } from "./manager.js";
+export { clearShellJobManager, getShellJobManager, peekShellJobManager, } from "./registry.js";
+export type { TerminalBackend, TerminalOutputSnapshot, TerminalRunRequest, TerminalRunResult, TerminalSpawnResult, } from "./terminal-backend.js";
+export { getTerminalBackend, setTerminalBackend } from "./terminal-backend.js";
+export { createShellTools, SHELL_OUTPUT_TOOL_NAME, SHELL_STOP_TOOL_NAME, SHELL_TOOL_NAME, } from "./shell.js";

package/dist/core/shell/index.js

@@ -0,0 +1,6 @@
+export { OutputBuffer, RING_CAPACITY_BYTES, WATCHDOG_MAX_BYTES, } from "./output-buffer.js";
+export { ShellJobManager } from "./manager.js";
+export { clearShellJobManager, getShellJobManager, peekShellJobManager, } from "./registry.js";
+export { getTerminalBackend, setTerminalBackend } from "./terminal-backend.js";
+export { createShellTools, SHELL_OUTPUT_TOOL_NAME, SHELL_STOP_TOOL_NAME, SHELL_TOOL_NAME, } from "./shell.js";
+//# sourceMappingURL=index.js.map

package/dist/core/shell/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/shell/index.ts"],"names":[],"mappings":"AAYA,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAQvB,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,oBAAoB,EACpB,eAAe,GAChB,MAAM,YAAY,CAAC"}

package/dist/core/shell/manager.d.ts

@@ -0,0 +1,23 @@
+import type { ShellJobInfo, ShellJobListener, ShellJobOutputSnapshot, ShellJobStartOptions, ShellJobWaitOptions } from "./types.js";
+/**
+ * Session-scoped manager for background (and early-return) shell jobs.
+ * Local spawn uses child_process; when a TerminalBackend with `spawn` is
+ * registered, jobs are hosted by the ACP client instead.
+ */
+export declare class ShellJobManager {
+    #private;
+    constructor(agent: object);
+    on(listener: ShellJobListener): () => void;
+    list(): ShellJobInfo[];
+    listActive(): ShellJobInfo[];
+    get(jobId: string): ShellJobInfo | undefined;
+    /**
+     * Start a job. Returns a snapshot once the block condition is met
+     * (immediate BG, notify/ready match, block_until deadline, or exit).
+     */
+    start(options: ShellJobStartOptions): Promise<ShellJobOutputSnapshot>;
+    output(jobId: string, opts?: ShellJobWaitOptions): Promise<ShellJobOutputSnapshot>;
+    stop(jobId: string): Promise<ShellJobOutputSnapshot>;
+    /** Kill all active jobs (session teardown). */
+    clear(): Promise<void>;
+}

package/dist/core/shell/manager.js

@@ -0,0 +1,604 @@
+import { spawn } from "node:child_process";
+import { createConnection } from "node:net";
+import { randomBytes } from "node:crypto";
+import { setTimeout as sleep } from "node:timers/promises";
+import { getTerminalBackend, } from "./terminal-backend.js";
+import { OutputBuffer } from "./output-buffer.js";
+const SIGKILL_TIMEOUT_MS = 200;
+const PORT_PROBE_INTERVAL_MS = 250;
+const DEFAULT_READY_TIMEOUT_MS = 30_000;
+const DEFAULT_WAIT_TIMEOUT_MS = 30_000;
+const ACTIVE_STATUSES = new Set([
+    "starting",
+    "running",
+    "ready",
+]);
+function newJobId() {
+    return `job-${randomBytes(4).toString("hex")}`;
+}
+function compileRegex(pattern) {
+    return new RegExp(pattern, "m");
+}
+async function killTree(proc, opts) {
+    const pid = proc.pid;
+    if (!pid || opts?.exited?.()) {
+        return;
+    }
+    if (process.platform === "win32") {
+        await new Promise((resolve) => {
+            const killer = spawn("taskkill", ["/pid", String(pid), "/f", "/t"], {
+                stdio: "ignore",
+                windowsHide: true,
+            });
+            killer.once("exit", () => resolve());
+            killer.once("error", () => resolve());
+        });
+        return;
+    }
+    try {
+        process.kill(-pid, "SIGTERM");
+        await sleep(SIGKILL_TIMEOUT_MS);
+        if (!opts?.exited?.()) {
+            process.kill(-pid, "SIGKILL");
+        }
+    }
+    catch {
+        proc.kill("SIGTERM");
+        await sleep(SIGKILL_TIMEOUT_MS);
+        if (!opts?.exited?.()) {
+            proc.kill("SIGKILL");
+        }
+    }
+}
+function probePort(port) {
+    return new Promise((resolve) => {
+        const socket = createConnection({ host: "127.0.0.1", port }, () => {
+            socket.destroy();
+            resolve(true);
+        });
+        socket.on("error", () => {
+            socket.destroy();
+            resolve(false);
+        });
+        socket.setTimeout(500, () => {
+            socket.destroy();
+            resolve(false);
+        });
+    });
+}
+/**
+ * Session-scoped manager for background (and early-return) shell jobs.
+ * Local spawn uses child_process; when a TerminalBackend with `spawn` is
+ * registered, jobs are hosted by the ACP client instead.
+ */
+export class ShellJobManager {
+    #jobs = new Map();
+    #listeners = new Set();
+    #agent;
+    constructor(agent) {
+        this.#agent = agent;
+    }
+    on(listener) {
+        this.#listeners.add(listener);
+        return () => {
+            this.#listeners.delete(listener);
+        };
+    }
+    list() {
+        return [...this.#jobs.values()].map((j) => ({ ...j.info }));
+    }
+    listActive() {
+        return this.list().filter((j) => ACTIVE_STATUSES.has(j.status));
+    }
+    get(jobId) {
+        const job = this.#jobs.get(jobId);
+        return job ? { ...job.info } : undefined;
+    }
+    /**
+     * Start a job. Returns a snapshot once the block condition is met
+     * (immediate BG, notify/ready match, block_until deadline, or exit).
+     */
+    async start(options) {
+        const id = newJobId();
+        const backend = getTerminalBackend(this.#agent);
+        const useHost = Boolean(backend?.spawn);
+        const info = {
+            id,
+            description: options.description,
+            command: [options.command, ...options.args].join(" "),
+            cwd: options.cwd,
+            status: "starting",
+            ready: false,
+            toolUseId: options.toolUseId,
+            exitCode: null,
+            signal: null,
+            startedAt: Date.now(),
+            outputTruncated: false,
+        };
+        const job = {
+            info,
+            buffer: new OutputBuffer(id, {
+                onWatchdog: () => {
+                    if (!job.watchdogFired) {
+                        job.watchdogFired = true;
+                        void this.stop(id);
+                    }
+                },
+            }),
+            exited: false,
+            readOffset: 0,
+            exitWaiters: [],
+            patternWaiters: [],
+            notifyDebounceMs: options.notifyOnOutput?.debounce_ms ?? 0,
+            lastNotifyCheckAt: 0,
+            watchdogFired: false,
+            stopRequested: false,
+            syncInFlight: false,
+            backend: useHost ? backend : undefined,
+        };
+        if (options.notifyOnOutput?.pattern) {
+            job.notifyPattern = compileRegex(options.notifyOnOutput.pattern);
+        }
+        if (options.ready?.pattern) {
+            job.readyPattern = compileRegex(options.ready.pattern);
+        }
+        if (options.ready?.port !== undefined) {
+            job.readyPort = options.ready.port;
+        }
+        this.#jobs.set(id, job);
+        this.#emit({ type: "started", job: { ...info } });
+        try {
+            if (useHost && backend?.spawn) {
+                await this.#startHost(job, options, backend);
+            }
+            else {
+                this.#startLocal(job, options);
+            }
+        }
+        catch (error) {
+            job.info.status = "failed";
+            job.info.endedAt = Date.now();
+            job.exited = true;
+            const message = error instanceof Error ? error.message : String(error);
+            this.#emit({ type: "failed", job: { ...job.info }, error: message });
+            return this.#snapshot(job);
+        }
+        job.info.status = "running";
+        if (options.timeoutMs && options.timeoutMs > 0) {
+            job.timeoutTimer = setTimeout(() => {
+                void this.stop(id);
+            }, options.timeoutMs);
+        }
+        if (job.readyPort !== undefined) {
+            this.#startPortProbe(job, options.ready?.timeout_ms);
+        }
+        // Immediate background: block_until_ms === 0 and no notify/ready wait.
+        const blockUntil = options.blockUntilMs !== undefined
+            ? options.blockUntilMs
+            : options.notifyOnOutput || options.ready
+                ? (options.ready?.timeout_ms ?? DEFAULT_READY_TIMEOUT_MS)
+                : undefined;
+        if (blockUntil === 0) {
+            return this.#snapshot(job);
+        }
+        // Foreground-style wait for exit when no early-return condition.
+        if (blockUntil === undefined && !options.notifyOnOutput && !options.ready) {
+            await this.#waitForExit(job, options.cancelSignal);
+            return this.#snapshot(job);
+        }
+        // Wait for notify/ready or deadline, then return while process continues.
+        const deadline = blockUntil ?? DEFAULT_READY_TIMEOUT_MS;
+        await this.#waitForEarlyReturn(job, deadline, options.cancelSignal);
+        return this.#snapshot(job);
+    }
+    async output(jobId, opts) {
+        const job = this.#require(jobId);
+        await this.#syncHostOutput(job);
+        const block = opts?.block ?? true;
+        const timeoutMs = opts?.timeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS;
+        const pattern = opts?.pattern ? compileRegex(opts.pattern) : undefined;
+        if (!block && !pattern) {
+            return this.#snapshot(job, opts?.tailLines);
+        }
+        if (pattern) {
+            const since = job.readOffset;
+            const matched = await this.#waitForPattern(job, pattern, since, timeoutMs, opts?.cancelSignal);
+            const snap = this.#snapshot(job, opts?.tailLines);
+            snap.matched = matched;
+            job.readOffset = job.buffer.readAll().length;
+            return snap;
+        }
+        // Block until exit.
+        if (ACTIVE_STATUSES.has(job.info.status)) {
+            await Promise.race([
+                this.#waitForExit(job, opts?.cancelSignal),
+                sleep(timeoutMs).then(() => undefined),
+            ]);
+            await this.#syncHostOutput(job);
+        }
+        return this.#snapshot(job, opts?.tailLines);
+    }
+    async stop(jobId) {
+        const job = this.#require(jobId);
+        job.stopRequested = true;
+        // Stop polling before kill so we don't pile terminal/output RPCs on top
+        // of the kill path (chatty jobs like `top` make that expensive).
+        this.#clearTimers(job);
+        if (job.info.status === "stopped") {
+            return this.#snapshot(job);
+        }
+        // Kill the host/local process. Under ACP this nests `terminal/kill` under
+        // the caller (stop_shell_job / shell_stop) — same concurrent-request
+        // pattern as terminal/* during session/prompt.
+        if (ACTIVE_STATUSES.has(job.info.status) || !job.exited) {
+            if (job.terminalId && job.backend?.kill) {
+                await job.backend.kill(job.terminalId).catch(() => undefined);
+            }
+            else if (job.child) {
+                await killTree(job.child, { exited: () => job.exited });
+            }
+        }
+        if (!job.exited) {
+            this.#markEnded(job, "stopped", null, null);
+        }
+        else if (job.info.status === "completed") {
+            job.info.status = "stopped";
+            this.#emit({ type: "stopped", job: { ...job.info } });
+        }
+        return this.#snapshot(job);
+    }
+    /** Kill all active jobs (session teardown). */
+    async clear() {
+        const ids = [...this.#jobs.keys()];
+        await Promise.all(ids.map((id) => this.stop(id).catch(() => undefined)));
+        for (const job of this.#jobs.values()) {
+            this.#clearTimers(job);
+        }
+        this.#jobs.clear();
+        this.#listeners.clear();
+    }
+    #require(jobId) {
+        const job = this.#jobs.get(jobId);
+        if (!job) {
+            throw new Error(`Unknown shell job "${jobId}"`);
+        }
+        return job;
+    }
+    #snapshot(job, tailLines) {
+        job.info.outputTruncated = job.buffer.truncated;
+        const output = tailLines !== undefined
+            ? job.buffer.readTailLines(tailLines)
+            : job.buffer.readTail();
+        return {
+            jobId: job.info.id,
+            output,
+            truncated: job.buffer.truncated,
+            status: job.info.status,
+            ready: job.info.ready,
+            exitCode: job.info.exitCode,
+            signal: job.info.signal,
+        };
+    }
+    #emit(event) {
+        for (const listener of this.#listeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // Listeners must not break the manager.
+            }
+        }
+    }
+    #startLocal(job, options) {
+        const child = spawn(options.command, options.args, {
+            cwd: options.cwd,
+            env: process.env,
+            detached: process.platform !== "win32",
+            stdio: "pipe",
+            windowsHide: true,
+        });
+        job.child = child;
+        job.info.pid = child.pid;
+        const onData = (chunk) => {
+            this.#appendOutput(job, chunk.toString());
+        };
+        child.stdout?.on("data", onData);
+        child.stderr?.on("data", onData);
+        child.stdin?.end();
+        child.once("error", (error) => {
+            this.#appendOutput(job, `\n${error.message}`);
+            this.#markEnded(job, "failed", 1, null);
+        });
+        child.once("close", (code, signal) => {
+            const status = job.stopRequested ? "stopped" : "completed";
+            this.#markEnded(job, status, code, signal ? String(signal) : null);
+        });
+        // Foreground-only: turn cancellation must not kill background jobs.
+        const detachAsBackground = options.blockUntilMs === 0 ||
+            options.notifyOnOutput !== undefined ||
+            options.ready !== undefined;
+        if (options.cancelSignal && !detachAsBackground) {
+            const onAbort = () => {
+                void this.stop(job.info.id);
+            };
+            if (options.cancelSignal.aborted) {
+                onAbort();
+            }
+            else {
+                options.cancelSignal.addEventListener("abort", onAbort, { once: true });
+            }
+        }
+    }
+    async #startHost(job, options, backend) {
+        const spawned = await backend.spawn({
+            toolUseId: options.toolUseId,
+            command: options.command,
+            args: options.args,
+            cwd: options.cwd,
+            timeoutMs: options.timeoutMs ?? 0,
+            outputByteLimit: options.outputByteLimit,
+            cancelSignal: options.cancelSignal,
+            jobId: job.info.id,
+        });
+        job.terminalId = spawned.terminalId;
+        job.info.terminalId = spawned.terminalId;
+        // Poll host output while the job is active.
+        job.pollTimer = setInterval(() => {
+            void this.#syncHostOutput(job);
+        }, 300);
+    }
+    async #syncHostOutput(job) {
+        if (!job.terminalId || !job.backend?.readOutput || job.syncInFlight) {
+            return;
+        }
+        job.syncInFlight = true;
+        try {
+            const snap = await job.backend.readOutput(job.terminalId);
+            const current = job.buffer.readAll();
+            if (snap.output.length > current.length) {
+                this.#appendOutput(job, snap.output.slice(current.length));
+            }
+            else if (snap.output !== current && snap.output.length > 0) {
+                // Host may have truncated from the front; replace buffer content.
+                // Append only the delta suffix if possible.
+                const idx = snap.output.indexOf(current.slice(-200));
+                if (idx >= 0) {
+                    this.#appendOutput(job, snap.output.slice(idx + 200));
+                }
+            }
+            if (snap.exitCode !== null || snap.signal !== null) {
+                if (!job.exited) {
+                    const status = job.stopRequested ? "stopped" : "completed";
+                    this.#markEnded(job, status, snap.exitCode, snap.signal);
+                }
+            }
+        }
+        catch {
+            // Host may have released the terminal.
+        }
+        finally {
+            job.syncInFlight = false;
+        }
+    }
+    #appendOutput(job, chunk) {
+        if (!chunk) {
+            return;
+        }
+        job.buffer.append(chunk);
+        this.#emit({ type: "output", job: { ...job.info }, chunk });
+        this.#checkPatterns(job);
+    }
+    #checkPatterns(job) {
+        const text = job.buffer.readAll();
+        if (!job.info.ready && job.readyPattern && job.readyPattern.test(text)) {
+            this.#markReady(job);
+        }
+        if (job.notifyPattern) {
+            const now = Date.now();
+            if (now - job.lastNotifyCheckAt >= job.notifyDebounceMs) {
+                job.lastNotifyCheckAt = now;
+                if (job.notifyPattern.test(text)) {
+                    for (const waiter of job.patternWaiters.splice(0)) {
+                        if (waiter.regex === job.notifyPattern || waiter.regex.test(text)) {
+                            waiter.resolve(true);
+                        }
+                        else {
+                            job.patternWaiters.push(waiter);
+                        }
+                    }
+                }
+            }
+        }
+        const remaining = [];
+        for (const waiter of job.patternWaiters) {
+            const slice = text.slice(waiter.since);
+            if (waiter.regex.test(slice) || waiter.regex.test(text)) {
+                waiter.resolve(true);
+            }
+            else {
+                remaining.push(waiter);
+            }
+        }
+        job.patternWaiters = remaining;
+    }
+    #markReady(job) {
+        if (job.info.ready) {
+            return;
+        }
+        job.info.ready = true;
+        if (job.info.status === "running" || job.info.status === "starting") {
+            job.info.status = "ready";
+        }
+        this.#clearPortProbe(job);
+        this.#emit({ type: "ready", job: { ...job.info } });
+        // Resolve pattern waiters that were waiting for ready.
+        for (const waiter of job.patternWaiters.splice(0)) {
+            waiter.resolve(true);
+        }
+    }
+    #startPortProbe(job, readyTimeoutMs) {
+        const port = job.readyPort;
+        if (port === undefined) {
+            return;
+        }
+        const deadline = Date.now() + (readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS);
+        job.portProbeTimer = setInterval(() => {
+            if (job.info.ready || job.exited || Date.now() > deadline) {
+                this.#clearPortProbe(job);
+                return;
+            }
+            void probePort(port).then((ok) => {
+                if (ok && !job.info.ready && !job.exited) {
+                    this.#markReady(job);
+                }
+            });
+        }, PORT_PROBE_INTERVAL_MS);
+    }
+    #clearPortProbe(job) {
+        if (job.portProbeTimer) {
+            clearInterval(job.portProbeTimer);
+            job.portProbeTimer = undefined;
+        }
+    }
+    #clearTimers(job) {
+        if (job.pollTimer) {
+            clearInterval(job.pollTimer);
+            job.pollTimer = undefined;
+        }
+        if (job.timeoutTimer) {
+            clearTimeout(job.timeoutTimer);
+            job.timeoutTimer = undefined;
+        }
+        this.#clearPortProbe(job);
+    }
+    #markEnded(job, status, exitCode, signal) {
+        if (job.exited && job.info.status !== "starting") {
+            // Already ended; allow stop to override completed → stopped.
+            if (!(status === "stopped" && job.info.status === "completed")) {
+                return;
+            }
+        }
+        job.exited = true;
+        job.info.status = status;
+        job.info.exitCode = exitCode;
+        job.info.signal = signal;
+        job.info.endedAt = Date.now();
+        this.#clearTimers(job);
+        for (const waiter of job.exitWaiters.splice(0)) {
+            waiter();
+        }
+        for (const waiter of job.patternWaiters.splice(0)) {
+            waiter.resolve(false);
+        }
+        if (status === "stopped") {
+            this.#emit({ type: "stopped", job: { ...job.info } });
+        }
+        else if (status === "failed") {
+            this.#emit({
+                type: "failed",
+                job: { ...job.info },
+                error: "process failed",
+            });
+        }
+        else {
+            this.#emit({ type: "completed", job: { ...job.info } });
+        }
+    }
+    #waitForExit(job, cancelSignal) {
+        if (job.exited) {
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            job.exitWaiters.push(resolve);
+            if (cancelSignal) {
+                const onAbort = () => {
+                    void this.stop(job.info.id).finally(resolve);
+                };
+                if (cancelSignal.aborted) {
+                    onAbort();
+                }
+                else {
+                    cancelSignal.addEventListener("abort", onAbort, { once: true });
+                }
+            }
+        });
+    }
+    #waitForPattern(job, regex, since, timeoutMs, cancelSignal) {
+        const text = job.buffer.readAll();
+        if (regex.test(text.slice(since)) || regex.test(text)) {
+            return Promise.resolve(true);
+        }
+        if (job.exited) {
+            return Promise.resolve(false);
+        }
+        return new Promise((resolve) => {
+            let settled = false;
+            const settle = (matched) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                clearTimeout(timer);
+                resolve(matched);
+            };
+            job.patternWaiters.push({ regex, since, resolve: settle });
+            const timer = setTimeout(() => settle(false), timeoutMs);
+            if (cancelSignal) {
+                const onAbort = () => settle(false);
+                if (cancelSignal.aborted) {
+                    onAbort();
+                }
+                else {
+                    cancelSignal.addEventListener("abort", onAbort, { once: true });
+                }
+            }
+        });
+    }
+    async #waitForEarlyReturn(job, deadlineMs, cancelSignal) {
+        if (job.exited || job.info.ready) {
+            return;
+        }
+        const patterns = [];
+        if (job.notifyPattern) {
+            patterns.push(job.notifyPattern);
+        }
+        if (job.readyPattern) {
+            patterns.push(job.readyPattern);
+        }
+        if (patterns.length === 0 && job.readyPort === undefined) {
+            // Just wait for the deadline, then detach.
+            await Promise.race([
+                this.#waitForExit(job, cancelSignal),
+                sleep(deadlineMs),
+            ]);
+            return;
+        }
+        const since = 0;
+        const waiters = patterns.map((regex) => this.#waitForPattern(job, regex, since, deadlineMs, cancelSignal));
+        // Also resolve early when ready via port.
+        const readyWait = job.readyPort !== undefined
+            ? new Promise((resolve) => {
+                const check = () => {
+                    if (job.info.ready) {
+                        resolve(true);
+                        return;
+                    }
+                    if (job.exited) {
+                        resolve(false);
+                        return;
+                    }
+                    setTimeout(check, 100);
+                };
+                check();
+                setTimeout(() => resolve(job.info.ready), deadlineMs);
+            })
+            : null;
+        await Promise.race([
+            ...waiters,
+            ...(readyWait ? [readyWait] : []),
+            this.#waitForExit(job, cancelSignal),
+            sleep(deadlineMs),
+        ]);
+    }
+}
+//# sourceMappingURL=manager.js.map