@mjasnikovs/pi-task 0.18.25 → 0.18.26

package/dist/config/config.d.ts

@@ -42,7 +42,36 @@ export interface PiTaskConfig {
      * /task-config, which enumerates the currently installed extensions.
      */
     extensionWhitelist: string[];
+    /**
+     * Wall-clock ceiling (ms) on a SINGLE tool execution in the MAIN session
+     * before the command watchdog cancels it and reminds the model to set its
+     * own timeout. Local models routinely run a command that never returns
+     * (e.g. `godot --headless` with no timeout, a dev server, a hung test) and
+     * the run wedges until the user manually aborts. pi's bash tool has an
+     * OPTIONAL timeout with NO default (bash.js), so a command the model didn't
+     * bound runs forever; this is the missing default, enforced from the host
+     * side via ctx.abort() (which kills the tool's whole process tree) plus an
+     * auto-reminder turn. Tool-agnostic: it arms on any tool execution, though
+     * in practice only bash runs long enough to trip it. 0 = off.
+     * DEFAULT 15 min: long enough for a real build/test suite, short enough that
+     * a true hang doesn't cost half an hour of dead time.
+     */
+    requestTimeoutMs: number;
 }
+/**
+ * The command-watchdog timeout choices offered by /task-config, newest-first in
+ * the cycle order the picker shows. The stored config value is the ms number;
+ * the label is display-only (mirrors the searchProvider label/value split).
+ */
+export declare const COMMAND_TIMEOUT_OPTIONS: ReadonlyArray<{
+    label: string;
+    ms: number;
+}>;
+/**
+ * A hand-edited or stale config could carry any number (or a string); pin it to
+ * one of the offered choices so the watchdog never arms on a nonsense value.
+ */
+export declare function sanitizeRequestTimeoutMs(value: unknown): number;
 /**
  * A hand-edited config can hold anything; keep only string entries so a stray
  * object/number can't reach the child argv as `-e [object Object]`.

package/dist/config/config.js

@@ -3,6 +3,28 @@ import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import { isSearchProvider } from '../workers/search-types.js';
+/**
+ * The command-watchdog timeout choices offered by /task-config, newest-first in
+ * the cycle order the picker shows. The stored config value is the ms number;
+ * the label is display-only (mirrors the searchProvider label/value split).
+ */
+export const COMMAND_TIMEOUT_OPTIONS = [
+    { label: '5 min', ms: 5 * 60_000 },
+    { label: '10 min', ms: 10 * 60_000 },
+    { label: '15 min', ms: 15 * 60_000 },
+    { label: '30 min', ms: 30 * 60_000 },
+    { label: 'off', ms: 0 }
+];
+const DEFAULT_REQUEST_TIMEOUT_MS = 15 * 60_000;
+/**
+ * A hand-edited or stale config could carry any number (or a string); pin it to
+ * one of the offered choices so the watchdog never arms on a nonsense value.
+ */
+export function sanitizeRequestTimeoutMs(value) {
+    return COMMAND_TIMEOUT_OPTIONS.some(o => o.ms === value) ?
+        value
+        : DEFAULT_REQUEST_TIMEOUT_MS;
+}
 const DEFAULTS = {
     remote: true,
     compressReasoning: true,
@@ -15,7 +37,8 @@ const DEFAULTS = {
     // 3/3, 0 collisions; ~14.5s of repeated docs lookups collapse to 0ms on a hit).
     researchCache: true,
     searchProvider: 'exa',
-    extensionWhitelist: []
+    extensionWhitelist: [],
+    requestTimeoutMs: DEFAULT_REQUEST_TIMEOUT_MS
 };
 /**
  * A hand-edited config can hold anything; keep only string entries so a stray
@@ -43,6 +66,7 @@ if (!G.loaded) {
         if (!isSearchProvider(parsed.searchProvider))
             delete parsed.searchProvider;
         parsed.extensionWhitelist = sanitizeExtensionWhitelist(parsed.extensionWhitelist);
+        parsed.requestTimeoutMs = sanitizeRequestTimeoutMs(parsed.requestTimeoutMs);
         G.config = { ...DEFAULTS, ...parsed };
     }
     catch {

package/dist/config/register.js

@@ -1,7 +1,7 @@
 import { SettingsList, visibleWidth } from '@earendil-works/pi-tui';
 import { registerBridgeCommand } from '../remote/bridge.js';
 import { SEARCH_PROVIDERS, SEARCH_PROVIDER_LABELS, providerForLabel } from '../workers/search-types.js';
-import { getConfig, saveConfig } from './config.js';
+import { COMMAND_TIMEOUT_OPTIONS, getConfig, saveConfig } from './config.js';
 import { listInstalledExtensions } from './extension-list.js';
 const CONFIG_TITLE = 'pi-task settings';
 /**
@@ -95,12 +95,28 @@ const ITEMS = [
         description: 'Engine behind web search (pi-worker-search + freshness checks). Exa and DuckDuckGo need no API key; Brave needs BRAVE_SEARCH_API_KEY',
         // Display full engine names; the stored config value stays the short id.
         values: SEARCH_PROVIDERS.map(p => SEARCH_PROVIDER_LABELS[p])
+    },
+    {
+        id: 'requestTimeoutMs',
+        label: 'command timeout',
+        description: 'Cancel a single command that runs longer than this and remind the model to set '
+            + 'its own timeout. Catches a local model that runs a command which never returns '
+            + '(hung build, dev server, no-timeout check) so the run stops itself instead of '
+            + 'waiting for a manual abort. off disables it',
+        // Display human labels; the stored config value stays the ms number.
+        values: COMMAND_TIMEOUT_OPTIONS.map(o => o.label)
     }
 ];
+/** Human label for the stored command-timeout ms (falls back to the raw ms). */
+function timeoutLabel(ms) {
+    return COMMAND_TIMEOUT_OPTIONS.find(o => o.ms === ms)?.label ?? `${ms}ms`;
+}
 /** What /task-config shows for a setting's current value. */
 function displayValue(cfg, id, isEnum) {
     if (id === 'searchProvider')
         return SEARCH_PROVIDER_LABELS[cfg.searchProvider];
+    if (id === 'requestTimeoutMs')
+        return timeoutLabel(cfg.requestTimeoutMs);
     if (isEnum)
         return String(cfg[id]);
     return cfg[id] ? 'on' : 'off';
@@ -173,6 +189,11 @@ async function handleTaskConfig(_args, ctx) {
                 if (provider)
                     cfg.searchProvider = provider;
             }
+            else if (id === 'requestTimeoutMs') {
+                const opt = COMMAND_TIMEOUT_OPTIONS.find(o => o.label === newValue);
+                if (opt)
+                    cfg.requestTimeoutMs = opt.ms;
+            }
             else {
                 ;
                 cfg[id] = newValue === 'on';
@@ -185,7 +206,7 @@ async function handleTaskConfig(_args, ctx) {
 export function registerConfig(pi) {
     registerBridgeCommand(pi, 'task-config', {
         description: 'Configure pi-task settings (remote, compress reasoning, auto-commit, orientation, '
-            + 'enforce guidelines, extension whitelist for child sessions).',
+            + 'enforce guidelines, command timeout, extension whitelist for child sessions).',
         handler: handleTaskConfig
     });
 }

package/dist/index.js

@@ -4,6 +4,7 @@ import { registerTaskAuto } from './task/auto-orchestrator.js';
 import { registerWorkers } from './workers/index.js';
 import { registerRemote } from './remote/register.js';
 import { registerThinkingCompression } from './thinking/compress.js';
+import { registerCommandWatchdog } from './task/command-watchdog.js';
 export default function (pi) {
     registerConfig(pi);
     registerTask(pi);
@@ -11,4 +12,5 @@ export default function (pi) {
     registerWorkers(pi);
     registerRemote(pi);
     registerThinkingCompression(pi);
+    registerCommandWatchdog(pi);
 }

package/dist/task/command-watchdog.d.ts

@@ -0,0 +1,67 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+/**
+ * Command watchdog — cancels a single tool execution that overruns the
+ * configured ceiling and reminds the model to bound its own commands.
+ *
+ * WHY: a local model in the MAIN session routinely runs a command that never
+ * returns — `godot --headless --check-only` with no timeout, a dev server, a
+ * hung test — and the run wedges until the user manually aborts and tells the
+ * model to add a timeout. pi's bash tool takes an OPTIONAL `timeout` with NO
+ * default (see pi-coding-agent tools/bash.js), so any command the model didn't
+ * bound runs forever. This supplies the missing default from the host side.
+ *
+ * HOW: arm a wall-clock timer on `tool_execution_start`, disarm it on
+ * `tool_execution_end`. If it elapses, `ctx.abort()` cancels the in-flight
+ * operation — which fires the tool's AbortSignal, and pi's bash executor kills
+ * the whole process tree on abort — then a follow-up user turn tells the model
+ * what happened so it retries with a timeout instead of hanging again.
+ *
+ * Tool-agnostic: it arms on ANY tool, honouring "any command can run forever",
+ * though in practice only bash runs long enough to trip it. The pure timer
+ * state lives in {@link CommandWatchdog}; all side effects (abort, reminder,
+ * per-call ctx lookup) live in the registration's `onFire`, so the machine is
+ * unit-testable without a real pi session.
+ */
+/** Opaque timer handle — a real `setTimeout` return in production, anything the
+ *  test's fake scheduler hands back under test. */
+export type TimerHandle = unknown;
+export interface WatchdogDeps {
+    /**
+     * The ceiling in ms, read PER command-start so a /task-config change takes
+     * effect on the next command with no reload. 0 (or any non-positive value)
+     * means the watchdog is off and never arms.
+     */
+    getTimeoutMs: () => number;
+    schedule: (fn: () => void, ms: number) => TimerHandle;
+    cancel: (handle: TimerHandle) => void;
+    /** Invoked when a command overruns: the registration aborts + reminds here. */
+    onFire: (toolCallId: string, toolName: string, timeoutMs: number) => void;
+}
+/**
+ * The reminder delivered to the model after its command is cancelled. Kept pure
+ * and exported so a test can assert its shape without driving the whole session.
+ */
+export declare function reminderMessage(toolName: string, timeoutMs: number): string;
+export declare class CommandWatchdog {
+    private readonly deps;
+    /** Armed timers, keyed by the tool call they guard. Tool executions are
+     *  sequential, so this holds at most one entry in normal operation, but the
+     *  map keeps it correct even if pi ever overlaps two calls. */
+    private readonly active;
+    constructor(deps: WatchdogDeps);
+    /** Arm a timer for a starting tool. No-op when the watchdog is off. */
+    onStart(toolCallId: string, toolName: string): void;
+    /** Disarm the timer for a finished tool. */
+    onEnd(toolCallId: string): void;
+    /** Cancel every armed timer — a turn-end / session-shutdown safety net so no
+     *  stray timer can fire into a later, unrelated command. */
+    clearAll(): void;
+    private disarm;
+    private fire;
+}
+/**
+ * Wire the watchdog into the main session. Only ever active in the host session
+ * (children run `--no-extensions`), which is exactly where the observed hangs
+ * happen.
+ */
+export declare function registerCommandWatchdog(pi: ExtensionAPI): void;

package/dist/task/command-watchdog.js

@@ -0,0 +1,114 @@
+import { getConfig } from '../config/config.js';
+/**
+ * The reminder delivered to the model after its command is cancelled. Kept pure
+ * and exported so a test can assert its shape without driving the whole session.
+ */
+export function reminderMessage(toolName, timeoutMs) {
+    const mins = Math.max(1, Math.round(timeoutMs / 60_000));
+    return (`[SYSTEM] Your \`${toolName}\` call ran longer than ${mins} minute`
+        + `${mins === 1 ? '' : 's'} and was automatically cancelled — it looked stuck. `
+        // Anti-fabrication: a live run showed the model react to the cancel by
+        // reporting the killed command as succeeded ("the server is now running").
+        // State plainly that it produced nothing so the model can't claim success.
+        + `The command was killed before it finished and produced NO result, so do not `
+        + `report it as completed or successful, and do not claim that anything it would `
+        + `have started (a server, build, or process) is now running. `
+        + `If it was a genuinely long-running command, you MUST re-run it with an explicit `
+        + `timeout — set the bash tool's \`timeout\` parameter (in seconds) so it cannot hang `
+        + `again — or break it into smaller steps. Do NOT simply retry the same unbounded command.`);
+}
+export class CommandWatchdog {
+    deps;
+    /** Armed timers, keyed by the tool call they guard. Tool executions are
+     *  sequential, so this holds at most one entry in normal operation, but the
+     *  map keeps it correct even if pi ever overlaps two calls. */
+    active = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Arm a timer for a starting tool. No-op when the watchdog is off. */
+    onStart(toolCallId, toolName) {
+        const ms = this.deps.getTimeoutMs();
+        if (!(ms > 0))
+            return;
+        // A duplicate start for the same id must not leak the previous timer.
+        this.disarm(toolCallId);
+        const handle = this.deps.schedule(() => this.fire(toolCallId, toolName, ms), ms);
+        this.active.set(toolCallId, handle);
+    }
+    /** Disarm the timer for a finished tool. */
+    onEnd(toolCallId) {
+        this.disarm(toolCallId);
+    }
+    /** Cancel every armed timer — a turn-end / session-shutdown safety net so no
+     *  stray timer can fire into a later, unrelated command. */
+    clearAll() {
+        for (const handle of this.active.values())
+            this.deps.cancel(handle);
+        this.active.clear();
+    }
+    disarm(toolCallId) {
+        const handle = this.active.get(toolCallId);
+        if (handle !== undefined) {
+            this.deps.cancel(handle);
+            this.active.delete(toolCallId);
+        }
+    }
+    fire(toolCallId, toolName, ms) {
+        // If the tool ended in the same tick the timer fired, its entry is gone
+        // already — never abort a command that has just finished cleanly.
+        if (!this.active.has(toolCallId))
+            return;
+        this.active.delete(toolCallId);
+        this.deps.onFire(toolCallId, toolName, ms);
+    }
+}
+/**
+ * Wire the watchdog into the main session. Only ever active in the host session
+ * (children run `--no-extensions`), which is exactly where the observed hangs
+ * happen.
+ */
+export function registerCommandWatchdog(pi) {
+    // The ctx that owns each in-flight tool's AbortSignal, captured per start so
+    // the timer callback (which fires outside the event handler) aborts the
+    // right operation.
+    const ctxByCall = new Map();
+    const watchdog = new CommandWatchdog({
+        getTimeoutMs: () => getConfig().requestTimeoutMs,
+        schedule: (fn, ms) => {
+            const handle = setTimeout(fn, ms);
+            // Don't let a pending watchdog timer keep the process alive on exit.
+            if (typeof handle.unref === 'function') {
+                ;
+                handle.unref();
+            }
+            return handle;
+        },
+        cancel: handle => clearTimeout(handle),
+        onFire: (toolCallId, toolName, timeoutMs) => {
+            const ctx = ctxByCall.get(toolCallId);
+            ctxByCall.delete(toolCallId);
+            // Cancel the stuck command (kills the tool's whole process tree via
+            // the turn's AbortSignal), then start a fresh turn telling the model
+            // to bound its next attempt.
+            ctx?.abort();
+            pi.sendUserMessage(reminderMessage(toolName, timeoutMs), { deliverAs: 'followUp' });
+        }
+    });
+    pi.on('tool_execution_start', (event, ctx) => {
+        ctxByCall.set(event.toolCallId, ctx);
+        watchdog.onStart(event.toolCallId, event.toolName);
+    });
+    pi.on('tool_execution_end', event => {
+        ctxByCall.delete(event.toolCallId);
+        watchdog.onEnd(event.toolCallId);
+    });
+    // Safety net: nothing should outlive its turn, but if a start ever lacks a
+    // matching end, clear on turn/session teardown so no timer fires stale.
+    const reset = () => {
+        watchdog.clearAll();
+        ctxByCall.clear();
+    };
+    pi.on('turn_end', reset);
+    pi.on('session_shutdown', reset);
+}

package/dist/task/final-gate.js

@@ -383,6 +383,12 @@ export function runBootCheck(cwd, [bin, args], graceMs = 10_000, opts = {}) {
             stdio: ['ignore', 'pipe', 'pipe'],
             env: { ...process.env }
         });
+        // Best-effort cleanup only: killGroup below can silently fail to reap the
+        // process (platform/sandbox-specific — observed on a GH Actions Linux
+        // runner where the group-kill did not take, hanging the whole `bun test
+        // --isolate` run on the leaked child's piped stdio). unref() so a child
+        // we already tried to kill can never itself keep this process alive.
+        child.unref();
         let out = '';
         let err = '';
         let listenerSeen = false;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.18.25",
+    "version": "0.18.26",
     "description": "Deterministic task planning and spec-orchestration for local models — crash-safe /task pipelines with verify/enforce gates, a real-time remote web view, and web/docs/fetch/worker subagent tools.",
     "type": "module",
     "main": "./dist/index.js",