@caupulican/pi-adaptative 0.81.38 → 0.81.40

package/dist/core/tools/shell-session.js

@@ -0,0 +1,432 @@
+/**
+ * Persistent shell sessions for the bash tool.
+ *
+ * One long-lived shell process per agent (keyed registry) replaces process-per-command spawning.
+ * On Windows every command previously paid a full PowerShell boot; a persistent session pays it
+ * once. Shell state (current directory, environment variables) persists across an agent's
+ * commands; each key gets an isolated session so concurrently running agents never share state.
+ *
+ * Protocol: commands stream to the session over stdin and are terminated by a per-command
+ * sentinel carrying a random nonce and the exit code. Bash wraps commands in an eval of a quoted
+ * heredoc (arbitrary content stays data; syntax errors stay contained in eval); PowerShell runs a
+ * ReadLine loop decoding base64 lines (no external binaries involved). On bash, command stderr is
+ * merged into stdout at the shell so sentinel ordering is guaranteed on one pipe.
+ *
+ * PowerShell runs each command as a bare `Invoke-Expression`, NOT piped into `Out-Default`: piping
+ * a native command's output into another pipeline stage forces PowerShell's NativeCommandProcessor
+ * to capture that child's stdout/stderr into an internal pipe and read it to EOF before the
+ * pipeline completes. A detached grandchild that inherited those handles (e.g. `start /b` holding
+ * stdio open) then keeps that internal pipe's write end open, so the sentinel — written after the
+ * pipeline "completes" — waits for the grandchild to die instead of the direct child. The bare
+ * invocation lets a native command's stdout/stderr handles be inherited directly by the child
+ * process; the direct child's own exit is what unblocks the sentinel line, exactly like the
+ * per-command backend and like bash's stdio inheritance above. The bounded consequence: a native
+ * command's stderr no longer merges into the session's stdout pipe (there is no capturing pipeline
+ * stage to merge it) — it arrives on the session's own stderr pipe instead, forwarded via
+ * `onStderr` -> `onData` same as the shell's own diagnostics. PowerShell 5.1's habit of wrapping
+ * redirected stderr text in a `NativeCommandError` record also disappears, which is an accuracy
+ * improvement (the raw stderr bytes are reported, not a wrapped/duplicated rendering of them).
+ *
+ * Kill semantics: timeout/abort/silence kill the WHOLE session process tree (a hung foreground
+ * command cannot be killed individually without job control) and the next exec respawns a fresh
+ * session, losing accumulated shell state by design. A command that exits the shell itself
+ * (`exit 3`) reports the shell's exit code and also respawns lazily afterwards.
+ */
+import { randomBytes } from "node:crypto";
+import { basename } from "node:path";
+import { createSilenceWatchdog } from "@caupulican/pi-agent-core";
+import { spawn } from "child_process";
+import { getShellConfig, getShellEnv, killProcessTree, trackDetachedChildPid, untrackDetachedChildPid, } from "../../utils/shell.js";
+const SENTINEL_BYTE = 0x1e;
+/** Longest possible sentinel: "\n" + 0x1e + 16-hex nonce + ":" + exit code digits + 0x1e. */
+const SENTINEL_HOLDBACK_BYTES = 64;
+function escapeSingleQuotesPosix(value) {
+    return value.replace(/'/g, "'\\''");
+}
+function escapeSingleQuotesPowerShell(value) {
+    return value.replace(/'/g, "''");
+}
+/**
+ * The whole command is heredoc-quoted data: eval keeps syntax errors contained (a raw syntax
+ * error on the session's stdin would abort the shell), and the random delimiter makes content
+ * collisions with agent output practically impossible. `< /dev/null` gives commands the same
+ * EOF-stdin the per-command backend's `stdio: ["ignore", ...]` provided.
+ */
+export function buildBashWire(command, nonce, cdTo) {
+    const body = cdTo ? `command cd -- '${escapeSingleQuotesPosix(cdTo)}' && {\n${command}\n}` : command;
+    return [
+        `{ eval "$(cat <<'PI_EOF_${nonce}'`,
+        body,
+        `PI_EOF_${nonce}`,
+        `)"; } < /dev/null 2>&1`,
+        `printf '\\n\\036%s:%s\\036' '${nonce}' "$?"`,
+        "",
+    ].join("\n");
+}
+/** One protocol line: `<nonce> <base64(utf8 command)>`. Base64 keeps arbitrary multi-line commands line-safe. */
+export function buildPowerShellWire(command, nonce, cdTo) {
+    const body = cdTo
+        ? `Set-Location -LiteralPath '${escapeSingleQuotesPowerShell(cdTo)}' -ErrorAction Stop\n${command}`
+        : command;
+    return `${nonce} ${Buffer.from(body, "utf8").toString("base64")}\n`;
+}
+/**
+ * PowerShell 5.1-compatible REPL bootstrap. Exit code mirrors `-Command` semantics as closely as
+ * a loop can: a native command's $LASTEXITCODE wins, a terminating error forces 1, otherwise 0.
+ * Passed via -EncodedCommand so quoting and newlines never touch the process command line.
+ *
+ * The command runs as a bare `Invoke-Expression` (no `2>&1 | Out-Default` capture pipeline) — see
+ * the module doc header for why: a native command's stdio handles are inherited directly by its
+ * child process instead of being captured through a PowerShell-internal pipe, so the sentinel is
+ * unblocked by the direct child's own exit rather than by any grandchild holding those handles.
+ */
+const POWERSHELL_BOOTSTRAP = [
+    "$ProgressPreference = 'SilentlyContinue'",
+    "try { [Console]::OutputEncoding = [System.Text.Encoding]::UTF8 } catch {}",
+    "$__pi_in = [Console]::In",
+    "while ($true) {",
+    "\t$__pi_line = $__pi_in.ReadLine()",
+    "\tif ($null -eq $__pi_line) { break }",
+    "\t$__pi_sp = $__pi_line.IndexOf(' ')",
+    "\tif ($__pi_sp -lt 1) { continue }",
+    "\t$__pi_nonce = $__pi_line.Substring(0, $__pi_sp)",
+    "\t$__pi_cmd = [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($__pi_line.Substring($__pi_sp + 1)))",
+    "\t$global:LASTEXITCODE = 0",
+    "\t$__pi_thrown = $false",
+    "\ttry { Invoke-Expression $__pi_cmd } catch { $__pi_thrown = $true; $__pi_msg = ($_ | Out-String).TrimEnd(); if ($__pi_msg) { [Console]::Out.WriteLine($__pi_msg) } }",
+    "\t$__pi_code = $global:LASTEXITCODE",
+    "\tif ($null -eq $__pi_code) { $__pi_code = 0 }",
+    "\tif ($__pi_thrown -and ($__pi_code -eq 0)) { $__pi_code = 1 }",
+    "\t[Console]::Out.Write(('{0}{1}{2}:{3}{1}' -f [char]10, [char]30, $__pi_nonce, $__pi_code))",
+    "}",
+].join("\n");
+function shallowEnvEquals(a, b) {
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    for (const key of aKeys) {
+        if (a[key] !== b[key])
+            return false;
+    }
+    return true;
+}
+export class PersistentShellSession {
+    key;
+    kind;
+    child = null;
+    childEnv = null;
+    lastRequestedCwd = null;
+    activeExec = null;
+    queue = Promise.resolve();
+    disposed = false;
+    constructor(key, kind) {
+        this.key = key;
+        this.kind = kind;
+    }
+    get sessionKind() {
+        return this.kind;
+    }
+    /** Serialized: one command at a time per session, later calls queue behind earlier ones. */
+    exec(command, cwd, options) {
+        const run = this.queue.then(() => this.execNow(command, cwd, options));
+        this.queue = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    dispose() {
+        this.disposed = true;
+        this.killChild();
+    }
+    /** Synchronous best-effort kill for process-exit hooks (async spawn never runs during exit).
+     * `killProcessTree` is itself synchronous (blocking `spawnSync` on Windows, `process.kill` on
+     * POSIX), so it is safe to call directly from a `process.on("exit", ...)` handler. */
+    killForProcessExit() {
+        const pid = this.child?.pid;
+        this.child = null;
+        if (!pid)
+            return;
+        untrackDetachedChildPid(pid);
+        killProcessTree(pid);
+    }
+    async execNow(command, cwd, { onData, signal, timeoutSeconds, silenceMs, env }) {
+        if (this.disposed)
+            throw new Error(`Shell session "${this.key}" is disposed`);
+        if (signal?.aborted)
+            throw new Error("aborted");
+        const resolvedEnv = env ?? getShellEnv();
+        // The environment is spawn-time shell config: an env that differs from the running
+        // session's (e.g. a spawn hook rewriting it per command) requires a fresh shell.
+        if (this.child && this.childEnv && !shallowEnvEquals(this.childEnv, resolvedEnv)) {
+            this.killChild();
+        }
+        // Re-enter the host-requested cwd only when it CHANGES between calls; an unchanged
+        // request preserves the agent's own in-session `cd` (that persistence is the feature).
+        let cdTo = null;
+        if (!this.child) {
+            this.spawnChild(cwd, resolvedEnv);
+        }
+        else if (this.lastRequestedCwd !== cwd) {
+            cdTo = cwd;
+        }
+        this.lastRequestedCwd = cwd;
+        const child = this.child;
+        if (!child?.stdin || !child.stdout || !child.stderr) {
+            this.killChild();
+            throw new Error(`Failed to start ${this.kind} session`);
+        }
+        const nonce = randomBytes(8).toString("hex");
+        const wire = this.kind === "powershell" ? buildPowerShellWire(command, nonce, cdTo) : buildBashWire(command, nonce, cdTo);
+        const sentinelPrefix = Buffer.from(`\n\x1e${nonce}:`, "latin1");
+        this.setLoopRef(true);
+        try {
+            return await new Promise((resolve, reject) => {
+                let settled = false;
+                let pending = Buffer.alloc(0);
+                let timeoutTimer;
+                const silenceWatchdog = timeoutSeconds === undefined && silenceMs !== undefined && silenceMs > 0
+                    ? createSilenceWatchdog({
+                        silenceMs,
+                        onSilence: () => {
+                            this.killChild();
+                            settle(() => reject(new Error(`silence:${silenceMs / 1000}`)));
+                        },
+                    })
+                    : undefined;
+                const settle = (finish) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    if (timeoutTimer)
+                        clearTimeout(timeoutTimer);
+                    silenceWatchdog?.disarm();
+                    if (signal)
+                        signal.removeEventListener("abort", onAbort);
+                    this.activeExec = null;
+                    finish();
+                };
+                const onAbort = () => {
+                    this.killChild();
+                    settle(() => reject(new Error("aborted")));
+                };
+                const emitPending = (upTo) => {
+                    if (upTo <= 0)
+                        return;
+                    onData(pending.subarray(0, upTo));
+                    pending = pending.subarray(upTo);
+                };
+                this.activeExec = {
+                    onStdout: (data) => {
+                        silenceWatchdog?.touch();
+                        pending = pending.length === 0 ? data : Buffer.concat([pending, data]);
+                        const prefixIndex = pending.indexOf(sentinelPrefix);
+                        if (prefixIndex !== -1) {
+                            const closeIndex = pending.indexOf(SENTINEL_BYTE, prefixIndex + sentinelPrefix.length);
+                            if (closeIndex !== -1) {
+                                const codeText = pending
+                                    .subarray(prefixIndex + sentinelPrefix.length, closeIndex)
+                                    .toString("latin1");
+                                emitPending(prefixIndex);
+                                const parsed = Number.parseInt(codeText, 10);
+                                // Defer the settle by one microtask turn: with the bare Invoke-Expression
+                                // form a native command's stderr now arrives on the session's OWN stderr
+                                // pipe (see module doc header) instead of being pre-merged into the same
+                                // stdout bytes the sentinel rides on. Node fires already-queued stream
+                                // 'data' events in event-loop order; queueing the resolution behind a
+                                // microtask guarantees any stderr chunk the kernel delivered alongside (or
+                                // just before) this stdout chunk has already run its 'data' handler — and
+                                // thus reached `onData` — before the promise settles, so callers never see a
+                                // truncated stderr tail immediately after resolution.
+                                queueMicrotask(() => settle(() => resolve({ exitCode: Number.isNaN(parsed) ? null : parsed })));
+                                return;
+                            }
+                        }
+                        // Stream promptly but retain a tail large enough to hold any split sentinel.
+                        emitPending(pending.length - SENTINEL_HOLDBACK_BYTES);
+                    },
+                    onStderr: (data) => {
+                        // The command's stderr is merged into stdout at the shell; this pipe only
+                        // carries the session shell's own diagnostics. Forward for visibility.
+                        silenceWatchdog?.touch();
+                        onData(data);
+                    },
+                    onChildClose: (code) => {
+                        // The command terminated the shell itself (e.g. `exit 3`) or the shell
+                        // crashed: report its exit code like the per-command backend would.
+                        emitPending(pending.length);
+                        settle(() => resolve({ exitCode: code }));
+                    },
+                    fail: (error) => {
+                        this.killChild();
+                        settle(() => reject(error));
+                    },
+                };
+                if (signal)
+                    signal.addEventListener("abort", onAbort, { once: true });
+                if (timeoutSeconds !== undefined && timeoutSeconds > 0) {
+                    timeoutTimer = setTimeout(() => {
+                        this.killChild();
+                        settle(() => reject(new Error(`timeout:${timeoutSeconds}`)));
+                    }, timeoutSeconds * 1000);
+                }
+                child.stdin?.write(wire, (error) => {
+                    if (!error)
+                        return;
+                    this.killChild();
+                    settle(() => reject(new Error(`Failed to write to ${this.kind} session: ${error.message}`)));
+                });
+            });
+        }
+        finally {
+            this.setLoopRef(false);
+        }
+    }
+    spawnChild(cwd, env) {
+        const { shell } = getShellConfig(undefined, this.kind);
+        const args = this.kind === "powershell"
+            ? [
+                "-NoLogo",
+                "-NoProfile",
+                "-NonInteractive",
+                "-EncodedCommand",
+                Buffer.from(POWERSHELL_BOOTSTRAP, "utf16le").toString("base64"),
+            ]
+            : basename(shell).toLowerCase().includes("bash")
+                ? ["--noprofile", "--norc"]
+                : [];
+        const child = spawn(shell, args, {
+            cwd,
+            env,
+            detached: process.platform !== "win32",
+            stdio: ["pipe", "pipe", "pipe"],
+            windowsHide: true,
+        });
+        if (child.pid)
+            trackDetachedChildPid(child.pid);
+        // Every listener gates on the child still being the session's current one: after a
+        // timeout/abort kill replaced it, the dead shell's late data/close events are stale noise
+        // that must never reach the NEXT command's handlers.
+        child.stdout?.on("data", (data) => {
+            if (this.child === child)
+                this.activeExec?.onStdout(data);
+        });
+        child.stderr?.on("data", (data) => {
+            if (this.child === child)
+                this.activeExec?.onStderr(data);
+        });
+        child.on("error", (error) => {
+            if (this.child !== child)
+                return;
+            this.clearChild(child);
+            this.activeExec?.fail(error instanceof Error ? error : new Error(String(error)));
+        });
+        // Settle the shell-died path on "exit" (process death), not "close" (stdio streams ended):
+        // a live detached grandchild that inherited these pipes (e.g. `sleep 30 &` before `exit 3`)
+        // keeps them open indefinitely even though the shell itself is already gone, and Node only
+        // fires "close" once every stdio stream has ended. Waiting for "close" here would hang for
+        // as long as the grandchild lives. The per-command backend
+        // (waitForChildProcessWithTermination in ../../utils/child-process.ts) faces the identical
+        // hazard and settles on "exit" for the same reason.
+        //
+        // "exit" can fire before Node has delivered already-buffered stdout/stderr "data" events for
+        // bytes the kernel handed over just before the process died (e.g. the sentinel line itself).
+        // Defer the settlement by one setImmediate turn: Node drains the poll phase (which is where
+        // pending stream "data" events run) before the check phase (where setImmediate callbacks
+        // run), so by the time this callback executes, every "data" event for bytes already received
+        // has already reached onStdout/onStderr, and thus onData, before we resolve/reject. This is
+        // not a hang-fix timer — it never waits on anything and does not run if the grandchild is
+        // gone and "close" (or a replacement child) got there first.
+        child.on("exit", (code) => {
+            if (this.child !== child)
+                return;
+            setImmediate(() => {
+                if (this.child !== child)
+                    return;
+                this.clearChild(child);
+                this.activeExec?.onChildClose(code);
+            });
+        });
+        // Kept alongside "exit" for the genuine fast-close case (no lingering grandchild): whichever
+        // event reaches its guard first wins and nulls out this.child, making the other a no-op, so
+        // settlement stays idempotent regardless of which fires first or whether both fire.
+        child.on("close", (code) => {
+            if (this.child !== child)
+                return;
+            this.clearChild(child);
+            this.activeExec?.onChildClose(code);
+        });
+        this.child = child;
+        this.childEnv = env;
+        this.lastRequestedCwd = cwd;
+    }
+    clearChild(child) {
+        if (child.pid)
+            untrackDetachedChildPid(child.pid);
+        this.child = null;
+        this.childEnv = null;
+        this.lastRequestedCwd = null;
+    }
+    killChild() {
+        const child = this.child;
+        if (!child)
+            return;
+        this.clearChild(child);
+        if (child.pid)
+            killProcessTree(child.pid);
+    }
+    /**
+     * An idle session must not keep the Node event loop alive (one-shot modes have to exit
+     * naturally); during a command the child and its pipes are re-referenced so the loop stays
+     * alive even without an armed timer.
+     */
+    setLoopRef(active) {
+        const child = this.child;
+        if (!child)
+            return;
+        // Stdio pipes are Sockets at runtime (ref/unref exist) but are typed as plain streams.
+        const streams = [child.stdin, child.stdout, child.stderr];
+        if (active) {
+            child.ref();
+            for (const stream of streams)
+                stream?.ref?.();
+        }
+        else {
+            child.unref();
+            for (const stream of streams)
+                stream?.unref?.();
+        }
+    }
+}
+const shellSessions = new Map();
+let exitHookInstalled = false;
+function installExitHook() {
+    if (exitHookInstalled)
+        return;
+    exitHookInstalled = true;
+    // Detached sessions outlive the parent on clean exits unless explicitly killed; shutdown
+    // signals are already covered by the tracked-detached-children mechanism.
+    process.on("exit", () => {
+        for (const session of shellSessions.values()) {
+            session.killForProcessExit();
+        }
+    });
+}
+/** Get or lazily create the persistent session for a key. A kind change replaces the session. */
+export function acquirePersistentShellSession(key, kind) {
+    installExitHook();
+    const existing = shellSessions.get(key);
+    if (existing && existing.sessionKind === kind)
+        return existing;
+    existing?.dispose();
+    const session = new PersistentShellSession(key, kind);
+    shellSessions.set(key, session);
+    return session;
+}
+/** Kill and forget a session (agent teardown). Safe to call for keys that never spawned. */
+export function disposePersistentShellSession(key) {
+    const session = shellSessions.get(key);
+    if (!session)
+        return;
+    shellSessions.delete(key);
+    session.dispose();
+}
+//# sourceMappingURL=shell-session.js.map

package/dist/core/tools/shell-session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-session.js","sourceRoot":"","sources":["../../../src/core/tools/shell-session.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Persistent shell sessions for the bash tool.\n *\n * One long-lived shell process per agent (keyed registry) replaces process-per-command spawning.\n * On Windows every command previously paid a full PowerShell boot; a persistent session pays it\n * once. Shell state (current directory, environment variables) persists across an agent's\n * commands; each key gets an isolated session so concurrently running agents never share state.\n *\n * Protocol: commands stream to the session over stdin and are terminated by a per-command\n * sentinel carrying a random nonce and the exit code. Bash wraps commands in an eval of a quoted\n * heredoc (arbitrary content stays data; syntax errors stay contained in eval); PowerShell runs a\n * ReadLine loop decoding base64 lines (no external binaries involved). On bash, command stderr is\n * merged into stdout at the shell so sentinel ordering is guaranteed on one pipe.\n *\n * PowerShell runs each command as a bare `Invoke-Expression`, NOT piped into `Out-Default`: piping\n * a native command's output into another pipeline stage forces PowerShell's NativeCommandProcessor\n * to capture that child's stdout/stderr into an internal pipe and read it to EOF before the\n * pipeline completes. A detached grandchild that inherited those handles (e.g. `start /b` holding\n * stdio open) then keeps that internal pipe's write end open, so the sentinel — written after the\n * pipeline \"completes\" — waits for the grandchild to die instead of the direct child. The bare\n * invocation lets a native command's stdout/stderr handles be inherited directly by the child\n * process; the direct child's own exit is what unblocks the sentinel line, exactly like the\n * per-command backend and like bash's stdio inheritance above. The bounded consequence: a native\n * command's stderr no longer merges into the session's stdout pipe (there is no capturing pipeline\n * stage to merge it) — it arrives on the session's own stderr pipe instead, forwarded via\n * `onStderr` -> `onData` same as the shell's own diagnostics. PowerShell 5.1's habit of wrapping\n * redirected stderr text in a `NativeCommandError` record also disappears, which is an accuracy\n * improvement (the raw stderr bytes are reported, not a wrapped/duplicated rendering of them).\n *\n * Kill semantics: timeout/abort/silence kill the WHOLE session process tree (a hung foreground\n * command cannot be killed individually without job control) and the next exec respawns a fresh\n * session, losing accumulated shell state by design. A command that exits the shell itself\n * (`exit 3`) reports the shell's exit code and also respawns lazily afterwards.\n */\n\nimport { randomBytes } from \"node:crypto\";\nimport { basename } from \"node:path\";\nimport { createSilenceWatchdog } from \"@caupulican/pi-agent-core\";\nimport { type ChildProcess, spawn } from \"child_process\";\nimport {\n\tgetShellConfig,\n\tgetShellEnv,\n\tkillProcessTree,\n\ttype PlatformShellToolName,\n\ttrackDetachedChildPid,\n\tuntrackDetachedChildPid,\n} from \"../../utils/shell.ts\";\n\nconst SENTINEL_BYTE = 0x1e;\n/** Longest possible sentinel: \"\\n\" + 0x1e + 16-hex nonce + \":\" + exit code digits + 0x1e. */\nconst SENTINEL_HOLDBACK_BYTES = 64;\n\nexport interface ShellSessionExecOptions {\n\tonData: (data: Buffer) => void;\n\tsignal?: AbortSignal;\n\t/** Wall-clock bound in seconds; when set, a breach kills the session and throws `timeout:<s>`. */\n\ttimeoutSeconds?: number;\n\t/** Output-silence bound in ms; when set, silence kills the session and throws `silence:<s>`. */\n\tsilenceMs?: number;\n\tenv?: NodeJS.ProcessEnv;\n}\n\nfunction escapeSingleQuotesPosix(value: string): string {\n\treturn value.replace(/'/g, \"'\\\\''\");\n}\n\nfunction escapeSingleQuotesPowerShell(value: string): string {\n\treturn value.replace(/'/g, \"''\");\n}\n\n/**\n * The whole command is heredoc-quoted data: eval keeps syntax errors contained (a raw syntax\n * error on the session's stdin would abort the shell), and the random delimiter makes content\n * collisions with agent output practically impossible. `< /dev/null` gives commands the same\n * EOF-stdin the per-command backend's `stdio: [\"ignore\", ...]` provided.\n */\nexport function buildBashWire(command: string, nonce: string, cdTo: string | null): string {\n\tconst body = cdTo ? `command cd -- '${escapeSingleQuotesPosix(cdTo)}' && {\\n${command}\\n}` : command;\n\treturn [\n\t\t`{ eval \"$(cat <<'PI_EOF_${nonce}'`,\n\t\tbody,\n\t\t`PI_EOF_${nonce}`,\n\t\t`)\"; } < /dev/null 2>&1`,\n\t\t`printf '\\\\n\\\\036%s:%s\\\\036' '${nonce}' \"$?\"`,\n\t\t\"\",\n\t].join(\"\\n\");\n}\n\n/** One protocol line: `<nonce> <base64(utf8 command)>`. Base64 keeps arbitrary multi-line commands line-safe. */\nexport function buildPowerShellWire(command: string, nonce: string, cdTo: string | null): string {\n\tconst body = cdTo\n\t\t? `Set-Location -LiteralPath '${escapeSingleQuotesPowerShell(cdTo)}' -ErrorAction Stop\\n${command}`\n\t\t: command;\n\treturn `${nonce} ${Buffer.from(body, \"utf8\").toString(\"base64\")}\\n`;\n}\n\n/**\n * PowerShell 5.1-compatible REPL bootstrap. Exit code mirrors `-Command` semantics as closely as\n * a loop can: a native command's $LASTEXITCODE wins, a terminating error forces 1, otherwise 0.\n * Passed via -EncodedCommand so quoting and newlines never touch the process command line.\n *\n * The command runs as a bare `Invoke-Expression` (no `2>&1 | Out-Default` capture pipeline) — see\n * the module doc header for why: a native command's stdio handles are inherited directly by its\n * child process instead of being captured through a PowerShell-internal pipe, so the sentinel is\n * unblocked by the direct child's own exit rather than by any grandchild holding those handles.\n */\nconst POWERSHELL_BOOTSTRAP = [\n\t\"$ProgressPreference = 'SilentlyContinue'\",\n\t\"try { [Console]::OutputEncoding = [System.Text.Encoding]::UTF8 } catch {}\",\n\t\"$__pi_in = [Console]::In\",\n\t\"while ($true) {\",\n\t\"\\t$__pi_line = $__pi_in.ReadLine()\",\n\t\"\\tif ($null -eq $__pi_line) { break }\",\n\t\"\\t$__pi_sp = $__pi_line.IndexOf(' ')\",\n\t\"\\tif ($__pi_sp -lt 1) { continue }\",\n\t\"\\t$__pi_nonce = $__pi_line.Substring(0, $__pi_sp)\",\n\t\"\\t$__pi_cmd = [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($__pi_line.Substring($__pi_sp + 1)))\",\n\t\"\\t$global:LASTEXITCODE = 0\",\n\t\"\\t$__pi_thrown = $false\",\n\t\"\\ttry { Invoke-Expression $__pi_cmd } catch { $__pi_thrown = $true; $__pi_msg = ($_ | Out-String).TrimEnd(); if ($__pi_msg) { [Console]::Out.WriteLine($__pi_msg) } }\",\n\t\"\\t$__pi_code = $global:LASTEXITCODE\",\n\t\"\\tif ($null -eq $__pi_code) { $__pi_code = 0 }\",\n\t\"\\tif ($__pi_thrown -and ($__pi_code -eq 0)) { $__pi_code = 1 }\",\n\t\"\\t[Console]::Out.Write(('{0}{1}{2}:{3}{1}' -f [char]10, [char]30, $__pi_nonce, $__pi_code))\",\n\t\"}\",\n].join(\"\\n\");\n\nfunction shallowEnvEquals(a: NodeJS.ProcessEnv, b: NodeJS.ProcessEnv): boolean {\n\tconst aKeys = Object.keys(a);\n\tconst bKeys = Object.keys(b);\n\tif (aKeys.length !== bKeys.length) return false;\n\tfor (const key of aKeys) {\n\t\tif (a[key] !== b[key]) return false;\n\t}\n\treturn true;\n}\n\ninterface ActiveExec {\n\tonStdout(data: Buffer): void;\n\tonStderr(data: Buffer): void;\n\tonChildClose(code: number | null): void;\n\tfail(error: Error): void;\n}\n\nexport class PersistentShellSession {\n\tprivate readonly key: string;\n\tprivate readonly kind: PlatformShellToolName;\n\tprivate child: ChildProcess | null = null;\n\tprivate childEnv: NodeJS.ProcessEnv | null = null;\n\tprivate lastRequestedCwd: string | null = null;\n\tprivate activeExec: ActiveExec | null = null;\n\tprivate queue: Promise<void> = Promise.resolve();\n\tprivate disposed = false;\n\n\tconstructor(key: string, kind: PlatformShellToolName) {\n\t\tthis.key = key;\n\t\tthis.kind = kind;\n\t}\n\n\tget sessionKind(): PlatformShellToolName {\n\t\treturn this.kind;\n\t}\n\n\t/** Serialized: one command at a time per session, later calls queue behind earlier ones. */\n\texec(command: string, cwd: string, options: ShellSessionExecOptions): Promise<{ exitCode: number | null }> {\n\t\tconst run = this.queue.then(() => this.execNow(command, cwd, options));\n\t\tthis.queue = run.then(\n\t\t\t() => undefined,\n\t\t\t() => undefined,\n\t\t);\n\t\treturn run;\n\t}\n\n\tdispose(): void {\n\t\tthis.disposed = true;\n\t\tthis.killChild();\n\t}\n\n\t/** Synchronous best-effort kill for process-exit hooks (async spawn never runs during exit).\n\t * `killProcessTree` is itself synchronous (blocking `spawnSync` on Windows, `process.kill` on\n\t * POSIX), so it is safe to call directly from a `process.on(\"exit\", ...)` handler. */\n\tkillForProcessExit(): void {\n\t\tconst pid = this.child?.pid;\n\t\tthis.child = null;\n\t\tif (!pid) return;\n\t\tuntrackDetachedChildPid(pid);\n\t\tkillProcessTree(pid);\n\t}\n\n\tprivate async execNow(\n\t\tcommand: string,\n\t\tcwd: string,\n\t\t{ onData, signal, timeoutSeconds, silenceMs, env }: ShellSessionExecOptions,\n\t): Promise<{ exitCode: number | null }> {\n\t\tif (this.disposed) throw new Error(`Shell session \"${this.key}\" is disposed`);\n\t\tif (signal?.aborted) throw new Error(\"aborted\");\n\n\t\tconst resolvedEnv = env ?? getShellEnv();\n\t\t// The environment is spawn-time shell config: an env that differs from the running\n\t\t// session's (e.g. a spawn hook rewriting it per command) requires a fresh shell.\n\t\tif (this.child && this.childEnv && !shallowEnvEquals(this.childEnv, resolvedEnv)) {\n\t\t\tthis.killChild();\n\t\t}\n\n\t\t// Re-enter the host-requested cwd only when it CHANGES between calls; an unchanged\n\t\t// request preserves the agent's own in-session `cd` (that persistence is the feature).\n\t\tlet cdTo: string | null = null;\n\t\tif (!this.child) {\n\t\t\tthis.spawnChild(cwd, resolvedEnv);\n\t\t} else if (this.lastRequestedCwd !== cwd) {\n\t\t\tcdTo = cwd;\n\t\t}\n\t\tthis.lastRequestedCwd = cwd;\n\n\t\tconst child = this.child;\n\t\tif (!child?.stdin || !child.stdout || !child.stderr) {\n\t\t\tthis.killChild();\n\t\t\tthrow new Error(`Failed to start ${this.kind} session`);\n\t\t}\n\n\t\tconst nonce = randomBytes(8).toString(\"hex\");\n\t\tconst wire =\n\t\t\tthis.kind === \"powershell\" ? buildPowerShellWire(command, nonce, cdTo) : buildBashWire(command, nonce, cdTo);\n\t\tconst sentinelPrefix = Buffer.from(`\\n\\x1e${nonce}:`, \"latin1\");\n\n\t\tthis.setLoopRef(true);\n\t\ttry {\n\t\t\treturn await new Promise<{ exitCode: number | null }>((resolve, reject) => {\n\t\t\t\tlet settled = false;\n\t\t\t\tlet pending: Buffer = Buffer.alloc(0);\n\t\t\t\tlet timeoutTimer: NodeJS.Timeout | undefined;\n\n\t\t\t\tconst silenceWatchdog =\n\t\t\t\t\ttimeoutSeconds === undefined && silenceMs !== undefined && silenceMs > 0\n\t\t\t\t\t\t? createSilenceWatchdog({\n\t\t\t\t\t\t\t\tsilenceMs,\n\t\t\t\t\t\t\t\tonSilence: () => {\n\t\t\t\t\t\t\t\t\tthis.killChild();\n\t\t\t\t\t\t\t\t\tsettle(() => reject(new Error(`silence:${silenceMs / 1000}`)));\n\t\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t})\n\t\t\t\t\t\t: undefined;\n\n\t\t\t\tconst settle = (finish: () => void) => {\n\t\t\t\t\tif (settled) return;\n\t\t\t\t\tsettled = true;\n\t\t\t\t\tif (timeoutTimer) clearTimeout(timeoutTimer);\n\t\t\t\t\tsilenceWatchdog?.disarm();\n\t\t\t\t\tif (signal) signal.removeEventListener(\"abort\", onAbort);\n\t\t\t\t\tthis.activeExec = null;\n\t\t\t\t\tfinish();\n\t\t\t\t};\n\n\t\t\t\tconst onAbort = () => {\n\t\t\t\t\tthis.killChild();\n\t\t\t\t\tsettle(() => reject(new Error(\"aborted\")));\n\t\t\t\t};\n\n\t\t\t\tconst emitPending = (upTo: number) => {\n\t\t\t\t\tif (upTo <= 0) return;\n\t\t\t\t\tonData(pending.subarray(0, upTo));\n\t\t\t\t\tpending = pending.subarray(upTo);\n\t\t\t\t};\n\n\t\t\t\tthis.activeExec = {\n\t\t\t\t\tonStdout: (data) => {\n\t\t\t\t\t\tsilenceWatchdog?.touch();\n\t\t\t\t\t\tpending = pending.length === 0 ? data : Buffer.concat([pending, data]);\n\t\t\t\t\t\tconst prefixIndex = pending.indexOf(sentinelPrefix);\n\t\t\t\t\t\tif (prefixIndex !== -1) {\n\t\t\t\t\t\t\tconst closeIndex = pending.indexOf(SENTINEL_BYTE, prefixIndex + sentinelPrefix.length);\n\t\t\t\t\t\t\tif (closeIndex !== -1) {\n\t\t\t\t\t\t\t\tconst codeText = pending\n\t\t\t\t\t\t\t\t\t.subarray(prefixIndex + sentinelPrefix.length, closeIndex)\n\t\t\t\t\t\t\t\t\t.toString(\"latin1\");\n\t\t\t\t\t\t\t\temitPending(prefixIndex);\n\t\t\t\t\t\t\t\tconst parsed = Number.parseInt(codeText, 10);\n\t\t\t\t\t\t\t\t// Defer the settle by one microtask turn: with the bare Invoke-Expression\n\t\t\t\t\t\t\t\t// form a native command's stderr now arrives on the session's OWN stderr\n\t\t\t\t\t\t\t\t// pipe (see module doc header) instead of being pre-merged into the same\n\t\t\t\t\t\t\t\t// stdout bytes the sentinel rides on. Node fires already-queued stream\n\t\t\t\t\t\t\t\t// 'data' events in event-loop order; queueing the resolution behind a\n\t\t\t\t\t\t\t\t// microtask guarantees any stderr chunk the kernel delivered alongside (or\n\t\t\t\t\t\t\t\t// just before) this stdout chunk has already run its 'data' handler — and\n\t\t\t\t\t\t\t\t// thus reached `onData` — before the promise settles, so callers never see a\n\t\t\t\t\t\t\t\t// truncated stderr tail immediately after resolution.\n\t\t\t\t\t\t\t\tqueueMicrotask(() => settle(() => resolve({ exitCode: Number.isNaN(parsed) ? null : parsed })));\n\t\t\t\t\t\t\t\treturn;\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t}\n\t\t\t\t\t\t// Stream promptly but retain a tail large enough to hold any split sentinel.\n\t\t\t\t\t\temitPending(pending.length - SENTINEL_HOLDBACK_BYTES);\n\t\t\t\t\t},\n\t\t\t\t\tonStderr: (data) => {\n\t\t\t\t\t\t// The command's stderr is merged into stdout at the shell; this pipe only\n\t\t\t\t\t\t// carries the session shell's own diagnostics. Forward for visibility.\n\t\t\t\t\t\tsilenceWatchdog?.touch();\n\t\t\t\t\t\tonData(data);\n\t\t\t\t\t},\n\t\t\t\t\tonChildClose: (code) => {\n\t\t\t\t\t\t// The command terminated the shell itself (e.g. `exit 3`) or the shell\n\t\t\t\t\t\t// crashed: report its exit code like the per-command backend would.\n\t\t\t\t\t\temitPending(pending.length);\n\t\t\t\t\t\tsettle(() => resolve({ exitCode: code }));\n\t\t\t\t\t},\n\t\t\t\t\tfail: (error) => {\n\t\t\t\t\t\tthis.killChild();\n\t\t\t\t\t\tsettle(() => reject(error));\n\t\t\t\t\t},\n\t\t\t\t};\n\n\t\t\t\tif (signal) signal.addEventListener(\"abort\", onAbort, { once: true });\n\t\t\t\tif (timeoutSeconds !== undefined && timeoutSeconds > 0) {\n\t\t\t\t\ttimeoutTimer = setTimeout(() => {\n\t\t\t\t\t\tthis.killChild();\n\t\t\t\t\t\tsettle(() => reject(new Error(`timeout:${timeoutSeconds}`)));\n\t\t\t\t\t}, timeoutSeconds * 1000);\n\t\t\t\t}\n\n\t\t\t\tchild.stdin?.write(wire, (error) => {\n\t\t\t\t\tif (!error) return;\n\t\t\t\t\tthis.killChild();\n\t\t\t\t\tsettle(() => reject(new Error(`Failed to write to ${this.kind} session: ${error.message}`)));\n\t\t\t\t});\n\t\t\t});\n\t\t} finally {\n\t\t\tthis.setLoopRef(false);\n\t\t}\n\t}\n\n\tprivate spawnChild(cwd: string, env: NodeJS.ProcessEnv): void {\n\t\tconst { shell } = getShellConfig(undefined, this.kind);\n\t\tconst args =\n\t\t\tthis.kind === \"powershell\"\n\t\t\t\t? [\n\t\t\t\t\t\t\"-NoLogo\",\n\t\t\t\t\t\t\"-NoProfile\",\n\t\t\t\t\t\t\"-NonInteractive\",\n\t\t\t\t\t\t\"-EncodedCommand\",\n\t\t\t\t\t\tBuffer.from(POWERSHELL_BOOTSTRAP, \"utf16le\").toString(\"base64\"),\n\t\t\t\t\t]\n\t\t\t\t: basename(shell).toLowerCase().includes(\"bash\")\n\t\t\t\t\t? [\"--noprofile\", \"--norc\"]\n\t\t\t\t\t: [];\n\t\tconst child = spawn(shell, args, {\n\t\t\tcwd,\n\t\t\tenv,\n\t\t\tdetached: process.platform !== \"win32\",\n\t\t\tstdio: [\"pipe\", \"pipe\", \"pipe\"],\n\t\t\twindowsHide: true,\n\t\t});\n\t\tif (child.pid) trackDetachedChildPid(child.pid);\n\t\t// Every listener gates on the child still being the session's current one: after a\n\t\t// timeout/abort kill replaced it, the dead shell's late data/close events are stale noise\n\t\t// that must never reach the NEXT command's handlers.\n\t\tchild.stdout?.on(\"data\", (data: Buffer) => {\n\t\t\tif (this.child === child) this.activeExec?.onStdout(data);\n\t\t});\n\t\tchild.stderr?.on(\"data\", (data: Buffer) => {\n\t\t\tif (this.child === child) this.activeExec?.onStderr(data);\n\t\t});\n\t\tchild.on(\"error\", (error) => {\n\t\t\tif (this.child !== child) return;\n\t\t\tthis.clearChild(child);\n\t\t\tthis.activeExec?.fail(error instanceof Error ? error : new Error(String(error)));\n\t\t});\n\t\t// Settle the shell-died path on \"exit\" (process death), not \"close\" (stdio streams ended):\n\t\t// a live detached grandchild that inherited these pipes (e.g. `sleep 30 &` before `exit 3`)\n\t\t// keeps them open indefinitely even though the shell itself is already gone, and Node only\n\t\t// fires \"close\" once every stdio stream has ended. Waiting for \"close\" here would hang for\n\t\t// as long as the grandchild lives. The per-command backend\n\t\t// (waitForChildProcessWithTermination in ../../utils/child-process.ts) faces the identical\n\t\t// hazard and settles on \"exit\" for the same reason.\n\t\t//\n\t\t// \"exit\" can fire before Node has delivered already-buffered stdout/stderr \"data\" events for\n\t\t// bytes the kernel handed over just before the process died (e.g. the sentinel line itself).\n\t\t// Defer the settlement by one setImmediate turn: Node drains the poll phase (which is where\n\t\t// pending stream \"data\" events run) before the check phase (where setImmediate callbacks\n\t\t// run), so by the time this callback executes, every \"data\" event for bytes already received\n\t\t// has already reached onStdout/onStderr, and thus onData, before we resolve/reject. This is\n\t\t// not a hang-fix timer — it never waits on anything and does not run if the grandchild is\n\t\t// gone and \"close\" (or a replacement child) got there first.\n\t\tchild.on(\"exit\", (code) => {\n\t\t\tif (this.child !== child) return;\n\t\t\tsetImmediate(() => {\n\t\t\t\tif (this.child !== child) return;\n\t\t\t\tthis.clearChild(child);\n\t\t\t\tthis.activeExec?.onChildClose(code);\n\t\t\t});\n\t\t});\n\t\t// Kept alongside \"exit\" for the genuine fast-close case (no lingering grandchild): whichever\n\t\t// event reaches its guard first wins and nulls out this.child, making the other a no-op, so\n\t\t// settlement stays idempotent regardless of which fires first or whether both fire.\n\t\tchild.on(\"close\", (code) => {\n\t\t\tif (this.child !== child) return;\n\t\t\tthis.clearChild(child);\n\t\t\tthis.activeExec?.onChildClose(code);\n\t\t});\n\t\tthis.child = child;\n\t\tthis.childEnv = env;\n\t\tthis.lastRequestedCwd = cwd;\n\t}\n\n\tprivate clearChild(child: ChildProcess): void {\n\t\tif (child.pid) untrackDetachedChildPid(child.pid);\n\t\tthis.child = null;\n\t\tthis.childEnv = null;\n\t\tthis.lastRequestedCwd = null;\n\t}\n\n\tprivate killChild(): void {\n\t\tconst child = this.child;\n\t\tif (!child) return;\n\t\tthis.clearChild(child);\n\t\tif (child.pid) killProcessTree(child.pid);\n\t}\n\n\t/**\n\t * An idle session must not keep the Node event loop alive (one-shot modes have to exit\n\t * naturally); during a command the child and its pipes are re-referenced so the loop stays\n\t * alive even without an armed timer.\n\t */\n\tprivate setLoopRef(active: boolean): void {\n\t\tconst child = this.child;\n\t\tif (!child) return;\n\t\t// Stdio pipes are Sockets at runtime (ref/unref exist) but are typed as plain streams.\n\t\tconst streams = [child.stdin, child.stdout, child.stderr] as unknown as Array<{\n\t\t\tref?: () => void;\n\t\t\tunref?: () => void;\n\t\t} | null>;\n\t\tif (active) {\n\t\t\tchild.ref();\n\t\t\tfor (const stream of streams) stream?.ref?.();\n\t\t} else {\n\t\t\tchild.unref();\n\t\t\tfor (const stream of streams) stream?.unref?.();\n\t\t}\n\t}\n}\n\nconst shellSessions = new Map<string, PersistentShellSession>();\nlet exitHookInstalled = false;\n\nfunction installExitHook(): void {\n\tif (exitHookInstalled) return;\n\texitHookInstalled = true;\n\t// Detached sessions outlive the parent on clean exits unless explicitly killed; shutdown\n\t// signals are already covered by the tracked-detached-children mechanism.\n\tprocess.on(\"exit\", () => {\n\t\tfor (const session of shellSessions.values()) {\n\t\t\tsession.killForProcessExit();\n\t\t}\n\t});\n}\n\n/** Get or lazily create the persistent session for a key. A kind change replaces the session. */\nexport function acquirePersistentShellSession(key: string, kind: PlatformShellToolName): PersistentShellSession {\n\tinstallExitHook();\n\tconst existing = shellSessions.get(key);\n\tif (existing && existing.sessionKind === kind) return existing;\n\texisting?.dispose();\n\tconst session = new PersistentShellSession(key, kind);\n\tshellSessions.set(key, session);\n\treturn session;\n}\n\n/** Kill and forget a session (agent teardown). Safe to call for keys that never spawned. */\nexport function disposePersistentShellSession(key: string): void {\n\tconst session = shellSessions.get(key);\n\tif (!session) return;\n\tshellSessions.delete(key);\n\tsession.dispose();\n}\n"]}

package/dist/core/tools/task-steps.d.ts

@@ -9,6 +9,7 @@ declare const taskStepsSchema: Type.TObject<{
         status: Type.TOptional<Type.TUnion<[Type.TLiteral<"pending">, Type.TLiteral<"in_progress">, Type.TLiteral<"completed">, Type.TLiteral<"blocked">, Type.TLiteral<"cancelled">]>>;
         priority: Type.TOptional<Type.TUnion<[Type.TLiteral<"low">, Type.TLiteral<"normal">, Type.TLiteral<"high">]>>;
         owner: Type.TOptional<Type.TString>;
+        requirementIds: Type.TOptional<Type.TArray<Type.TString>>;
         note: Type.TOptional<Type.TString>;
         evidence: Type.TOptional<Type.TArray<Type.TString>>;
     }>>>;
@@ -18,6 +19,7 @@ declare const taskStepsSchema: Type.TObject<{
     status: Type.TOptional<Type.TUnion<[Type.TLiteral<"pending">, Type.TLiteral<"in_progress">, Type.TLiteral<"completed">, Type.TLiteral<"blocked">, Type.TLiteral<"cancelled">]>>;
     priority: Type.TOptional<Type.TUnion<[Type.TLiteral<"low">, Type.TLiteral<"normal">, Type.TLiteral<"high">]>>;
     owner: Type.TOptional<Type.TString>;
+    requirementIds: Type.TOptional<Type.TArray<Type.TString>>;
     note: Type.TOptional<Type.TString>;
     evidence: Type.TOptional<Type.TArray<Type.TString>>;
     clearCompleted: Type.TOptional<Type.TBoolean>;
@@ -35,6 +37,10 @@ export interface TaskStepsToolDetails {
     openStepCount?: number;
     verificationNudgeNeeded?: boolean;
     showCompleted?: boolean;
+    /** Set when `add` was a no-op because an open step already carries this content. */
+    duplicateOfStepId?: string;
+    /** Step ids silently demoted to pending because another step became active in this call. */
+    demotedStepIds?: readonly string[];
 }
 export interface TaskStepsToolDependencies {
     getTaskStepsState: () => TaskStepsState | undefined;

package/dist/core/tools/task-steps.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task-steps.d.ts","sourceRoot":"","sources":["../../../src/core/tools/task-steps.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EASN,KAAK,cAAc,EAEnB,MAAM,wBAAwB,CAAC;AA2BhC,QAAA,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;EAuCpB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAChE,MAAM,MAAM,eAAe,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;AAE3D,MAAM,WAAW,oBAAoB;IACpC,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,aAAa,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,yBAAyB;IACzC,iBAAiB,EAAE,MAAM,cAAc,GAAG,SAAS,CAAC;IACpD,kBAAkB,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;IACpD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACnB;AAkCD,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,yBAAyB,GAAG,cAAc,CA4F7F","sourcesContent":["import { type Static, Type } from \"typebox\";\nimport type { ToolDefinition } from \"../extensions/types.ts\";\nimport {\n\taddTaskStep,\n\tclearTaskSteps,\n\tcompactTaskSteps,\n\tcreateTaskStepsState,\n\tformatTaskSteps,\n\tMAX_TASK_STEPS,\n\tsetTaskSteps,\n\ttype TaskStepInput,\n\ttype TaskStepsState,\n\tupdateTaskStep,\n} from \"../tasks/task-state.ts\";\n\nconst statusSchema = Type.Union([\n\tType.Literal(\"pending\"),\n\tType.Literal(\"in_progress\"),\n\tType.Literal(\"completed\"),\n\tType.Literal(\"blocked\"),\n\tType.Literal(\"cancelled\"),\n]);\n\nconst prioritySchema = Type.Union([Type.Literal(\"low\"), Type.Literal(\"normal\"), Type.Literal(\"high\")]);\n\nconst stepInputSchema = Type.Object(\n\t{\n\t\tcontent: Type.String({ minLength: 1, maxLength: 2_000, description: \"Imperative task step text.\" }),\n\t\tactiveForm: Type.Optional(\n\t\t\tType.String({ minLength: 1, maxLength: 2_000, description: \"Short present-progress label for active UI.\" }),\n\t\t),\n\t\tstatus: Type.Optional(statusSchema),\n\t\tpriority: Type.Optional(prioritySchema),\n\t\towner: Type.Optional(Type.String({ maxLength: 200 })),\n\t\tnote: Type.Optional(Type.String({ maxLength: 4_000 })),\n\t\tevidence: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 2_000 }), { maxItems: 32 })),\n\t},\n\t{ additionalProperties: false },\n);\n\nconst taskStepsSchema = Type.Object(\n\t{\n\t\taction: Type.Union(\n\t\t\t[\n\t\t\t\tType.Literal(\"set\"),\n\t\t\t\tType.Literal(\"add\"),\n\t\t\t\tType.Literal(\"update\"),\n\t\t\t\tType.Literal(\"list\"),\n\t\t\t\tType.Literal(\"clear\"),\n\t\t\t\tType.Literal(\"compact\"),\n\t\t\t\tType.Literal(\"intake\"),\n\t\t\t],\n\t\t\t{ description: \"Checklist action. Use list to read without mutation.\" },\n\t\t),\n\t\tsteps: Type.Optional(\n\t\t\tType.Array(stepInputSchema, {\n\t\t\t\tmaxItems: MAX_TASK_STEPS,\n\t\t\t\tdescription: \"Complete replacement list for set/intake. Intake preserves every supplied item in order.\",\n\t\t\t}),\n\t\t),\n\t\tid: Type.Optional(\n\t\t\tType.String({\n\t\t\t\tdescription: \"For update: current/active, exact step id, unique id prefix, or unique content selector.\",\n\t\t\t}),\n\t\t),\n\t\tcontent: Type.Optional(Type.String({ minLength: 1, maxLength: 2_000 })),\n\t\tactiveForm: Type.Optional(Type.String({ maxLength: 2_000 })),\n\t\tstatus: Type.Optional(statusSchema),\n\t\tpriority: Type.Optional(prioritySchema),\n\t\towner: Type.Optional(Type.String({ maxLength: 200 })),\n\t\tnote: Type.Optional(Type.String({ maxLength: 4_000 })),\n\t\tevidence: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 2_000 }), { maxItems: 32 })),\n\t\tclearCompleted: Type.Optional(\n\t\t\tType.Boolean({ description: \"For list: compact completed and cancelled steps before rendering.\" }),\n\t\t),\n\t\tshowCompleted: Type.Optional(Type.Boolean({ description: \"Include completed and cancelled steps in output.\" })),\n\t\tmaxItems: Type.Optional(Type.Integer({ minimum: 1, maximum: MAX_TASK_STEPS })),\n\t},\n\t{ additionalProperties: false },\n);\n\nexport type TaskStepsToolInput = Static<typeof taskStepsSchema>;\nexport type TaskStepsAction = TaskStepsToolInput[\"action\"];\n\nexport interface TaskStepsToolDetails {\n\taction: TaskStepsAction;\n\tapplied: boolean;\n\terror?: string;\n\tstate?: TaskStepsState;\n\tstepCount?: number;\n\topenStepCount?: number;\n\tverificationNudgeNeeded?: boolean;\n\tshowCompleted?: boolean;\n}\n\nexport interface TaskStepsToolDependencies {\n\tgetTaskStepsState: () => TaskStepsState | undefined;\n\tsaveTaskStepsState: (state: TaskStepsState) => void;\n\tnow?: () => string;\n}\n\nfunction toTaskStepInput(input: TaskStepsToolInput): TaskStepInput {\n\treturn {\n\t\tcontent: input.content ?? \"\",\n\t\tactiveForm: input.activeForm,\n\t\tstatus: input.status,\n\t\tpriority: input.priority,\n\t\towner: input.owner,\n\t\tnote: input.note,\n\t\tevidence: input.evidence,\n\t};\n}\n\nfunction counts(\n\tstate: TaskStepsState,\n): Pick<TaskStepsToolDetails, \"stepCount\" | \"openStepCount\" | \"verificationNudgeNeeded\"> {\n\tconst openStepCount = state.steps.filter(\n\t\t(step) => step.status !== \"completed\" && step.status !== \"cancelled\",\n\t).length;\n\treturn {\n\t\tstepCount: state.steps.length,\n\t\topenStepCount,\n\t\tverificationNudgeNeeded: state.steps.some((step) => step.status === \"completed\" && step.evidence.length === 0),\n\t};\n}\n\nfunction errorResult(action: TaskStepsAction, error: string, state?: TaskStepsState) {\n\treturn {\n\t\tcontent: [{ type: \"text\" as const, text: `task_steps ${action} failed: ${error}` }],\n\t\tdetails: { action, applied: false, error, state, ...(state ? counts(state) : {}) } satisfies TaskStepsToolDetails,\n\t};\n}\n\nexport function createTaskStepsToolDefinition(deps: TaskStepsToolDependencies): ToolDefinition {\n\tconst now = deps.now ?? (() => new Date().toISOString());\n\treturn {\n\t\tname: \"task_steps\",\n\t\tlabel: \"Task Steps\",\n\t\tdescription:\n\t\t\t\"Maintain the current session's native ordered checklist for multi-step work. Supports pending, in_progress, completed, blocked, and cancelled steps with notes and evidence. State is isolated to and persisted with the active session; use native goal for durable outcome requirements and native delegate/delegate_status for background workers.\",\n\t\tpromptSnippet: \"Track and drain multi-step work with a native session checklist.\",\n\t\tpromptGuidelines: [\n\t\t\t\"Use task_steps for complex work, explicit task-tracking requests, and harness/self-improvement work; keep exactly one step in_progress while actively working.\",\n\t\t\t\"Always address the first open task step before unrelated work: start it, complete/block/cancel it with evidence, ask one clarifying question, or explicitly defer or reorder it.\",\n\t\t\t\"Mark steps completed as soon as evidence is gathered, and attach concise evidence or a blocker reason through update.\",\n\t\t\t\"Use action=intake with a complete steps array when preserving a raw multi-item dump; retain every item and do not silently drop entries.\",\n\t\t\t\"Drain task_steps before final responses: leave no stale in_progress step, and explicitly discuss or defer remaining pending or blocked work.\",\n\t\t\t\"Use goal for the durable goal ledger and delegate/delegate_status for worker lanes; do not emulate background execution inside task_steps.\",\n\t\t],\n\t\tparameters: taskStepsSchema,\n\t\tasync execute(_toolCallId, input: TaskStepsToolInput) {\n\t\t\tconst timestamp = now();\n\t\t\tconst current = deps.getTaskStepsState();\n\t\t\tlet state = current ?? createTaskStepsState(timestamp);\n\t\t\ttry {\n\t\t\t\tswitch (input.action) {\n\t\t\t\t\tcase \"set\":\n\t\t\t\t\t\tif (!input.steps) return errorResult(input.action, \"set requires steps[].\", current);\n\t\t\t\t\t\tstate = setTaskSteps(state, input.steps, timestamp);\n\t\t\t\t\t\tbreak;\n\t\t\t\t\tcase \"intake\":\n\t\t\t\t\t\tif (!input.steps)\n\t\t\t\t\t\t\treturn errorResult(input.action, \"intake requires a complete steps[] list.\", current);\n\t\t\t\t\t\tstate = setTaskSteps(state, input.steps, timestamp);\n\t\t\t\t\t\tbreak;\n\t\t\t\t\tcase \"add\":\n\t\t\t\t\t\tstate = addTaskStep(state, toTaskStepInput(input), timestamp);\n\t\t\t\t\t\tbreak;\n\t\t\t\t\tcase \"update\":\n\t\t\t\t\t\tif (!input.id?.trim())\n\t\t\t\t\t\t\treturn errorResult(input.action, \"update requires id or a unique selector.\", current);\n\t\t\t\t\t\tstate = updateTaskStep(\n\t\t\t\t\t\t\tstate,\n\t\t\t\t\t\t\tinput.id,\n\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\tcontent: input.content,\n\t\t\t\t\t\t\t\tactiveForm: input.activeForm,\n\t\t\t\t\t\t\t\tstatus: input.status,\n\t\t\t\t\t\t\t\tpriority: input.priority,\n\t\t\t\t\t\t\t\towner: input.owner,\n\t\t\t\t\t\t\t\tnote: input.note,\n\t\t\t\t\t\t\t\tevidence: input.evidence,\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\ttimestamp,\n\t\t\t\t\t\t);\n\t\t\t\t\t\tbreak;\n\t\t\t\t\tcase \"clear\":\n\t\t\t\t\t\tstate = clearTaskSteps(state, timestamp);\n\t\t\t\t\t\tbreak;\n\t\t\t\t\tcase \"compact\":\n\t\t\t\t\t\tstate = compactTaskSteps(state, timestamp);\n\t\t\t\t\t\tbreak;\n\t\t\t\t\tcase \"list\":\n\t\t\t\t\t\tif (input.clearCompleted) state = compactTaskSteps(state, timestamp);\n\t\t\t\t\t\tbreak;\n\t\t\t\t}\n\n\t\t\t\tconst mutated = input.action !== \"list\" || input.clearCompleted === true;\n\t\t\t\tif (mutated) deps.saveTaskStepsState(state);\n\t\t\t\treturn {\n\t\t\t\t\tcontent: [\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\ttype: \"text\" as const,\n\t\t\t\t\t\t\ttext: `${input.action === \"list\" ? \"\" : `task_steps ${input.action} recorded.\\n`}${formatTaskSteps(\n\t\t\t\t\t\t\t\tstate,\n\t\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\t\tincludeTerminal: input.showCompleted,\n\t\t\t\t\t\t\t\t\tmaxItems: input.maxItems,\n\t\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t)}`,\n\t\t\t\t\t\t},\n\t\t\t\t\t],\n\t\t\t\t\tdetails: {\n\t\t\t\t\t\taction: input.action,\n\t\t\t\t\t\tapplied: true,\n\t\t\t\t\t\tstate,\n\t\t\t\t\t\t...counts(state),\n\t\t\t\t\t\tshowCompleted: input.showCompleted,\n\t\t\t\t\t} satisfies TaskStepsToolDetails,\n\t\t\t\t};\n\t\t\t} catch (error) {\n\t\t\t\treturn errorResult(input.action, error instanceof Error ? error.message : String(error), current);\n\t\t\t}\n\t\t},\n\t};\n}\n"]}
+{"version":3,"file":"task-steps.d.ts","sourceRoot":"","sources":["../../../src/core/tools/task-steps.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAaN,KAAK,cAAc,EAEnB,MAAM,wBAAwB,CAAC;AAuChC,QAAA,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;EA6CpB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAChE,MAAM,MAAM,eAAe,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;AAE3D,MAAM,WAAW,oBAAoB;IACpC,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,oFAAoF;IACpF,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,4FAA4F;IAC5F,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,yBAAyB;IACzC,iBAAiB,EAAE,MAAM,cAAc,GAAG,SAAS,CAAC;IACpD,kBAAkB,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;IACpD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACnB;AAmID,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,yBAAyB,GAAG,cAAc,CAiK7F","sourcesContent":["import { type Static, Type } from \"typebox\";\nimport type { ToolDefinition } from \"../extensions/types.ts\";\nimport {\n\taddTaskStep,\n\tclearTaskSteps,\n\tcompactTaskSteps,\n\tcreateTaskStepsState,\n\tfindOpenDuplicateStep,\n\tformatTaskSteps,\n\thasUnverifiedCompletedStep,\n\tMAX_TASK_STEPS,\n\tresolveTaskStepSelector,\n\tsetTaskSteps,\n\ttype TaskStep,\n\ttype TaskStepInput,\n\ttype TaskStepsState,\n\tupdateTaskStep,\n} from \"../tasks/task-state.ts\";\nimport {\n\temptyOrchestrationCall,\n\tOrchestrationPanelComponent,\n\ttype OrchestrationPanelModel,\n\ttaskStepPanelRow,\n} from \"./orchestration-panel.ts\";\n\nconst statusSchema = Type.Union([\n\tType.Literal(\"pending\"),\n\tType.Literal(\"in_progress\"),\n\tType.Literal(\"completed\"),\n\tType.Literal(\"blocked\"),\n\tType.Literal(\"cancelled\"),\n]);\n\nconst prioritySchema = Type.Union([Type.Literal(\"low\"), Type.Literal(\"normal\"), Type.Literal(\"high\")]);\n\nconst stepInputSchema = Type.Object(\n\t{\n\t\tcontent: Type.String({ minLength: 1, maxLength: 2_000, description: \"Imperative task step text.\" }),\n\t\tactiveForm: Type.Optional(\n\t\t\tType.String({ minLength: 1, maxLength: 2_000, description: \"Short present-progress label for active UI.\" }),\n\t\t),\n\t\tstatus: Type.Optional(statusSchema),\n\t\tpriority: Type.Optional(prioritySchema),\n\t\towner: Type.Optional(Type.String({ maxLength: 200 })),\n\t\trequirementIds: Type.Optional(\n\t\t\tType.Array(Type.String({ minLength: 1, maxLength: 200 }), {\n\t\t\t\tmaxItems: 32,\n\t\t\t\tdescription: \"Goal requirement ids this foreground step advances.\",\n\t\t\t}),\n\t\t),\n\t\tnote: Type.Optional(Type.String({ maxLength: 4_000 })),\n\t\tevidence: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 2_000 }), { maxItems: 32 })),\n\t},\n\t{ additionalProperties: false },\n);\n\nconst taskStepsSchema = Type.Object(\n\t{\n\t\taction: Type.Union(\n\t\t\t[\n\t\t\t\tType.Literal(\"set\"),\n\t\t\t\tType.Literal(\"add\"),\n\t\t\t\tType.Literal(\"update\"),\n\t\t\t\tType.Literal(\"list\"),\n\t\t\t\tType.Literal(\"clear\"),\n\t\t\t\tType.Literal(\"compact\"),\n\t\t\t\tType.Literal(\"intake\"),\n\t\t\t],\n\t\t\t{ description: \"Checklist action. Use list to read without mutation.\" },\n\t\t),\n\t\tsteps: Type.Optional(\n\t\t\tType.Array(stepInputSchema, {\n\t\t\t\tmaxItems: MAX_TASK_STEPS,\n\t\t\t\tdescription: \"Complete replacement list for set/intake. Intake preserves every supplied item in order.\",\n\t\t\t}),\n\t\t),\n\t\tid: Type.Optional(\n\t\t\tType.String({\n\t\t\t\tdescription: \"For update: current/active, exact step id, unique id prefix, or unique content selector.\",\n\t\t\t}),\n\t\t),\n\t\tcontent: Type.Optional(Type.String({ minLength: 1, maxLength: 2_000 })),\n\t\tactiveForm: Type.Optional(Type.String({ maxLength: 2_000 })),\n\t\tstatus: Type.Optional(statusSchema),\n\t\tpriority: Type.Optional(prioritySchema),\n\t\towner: Type.Optional(Type.String({ maxLength: 200 })),\n\t\trequirementIds: Type.Optional(\n\t\t\tType.Array(Type.String({ minLength: 1, maxLength: 200 }), {\n\t\t\t\tmaxItems: 32,\n\t\t\t\tdescription: \"Goal requirement ids this foreground step advances; [] clears existing links.\",\n\t\t\t}),\n\t\t),\n\t\tnote: Type.Optional(Type.String({ maxLength: 4_000 })),\n\t\tevidence: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 2_000 }), { maxItems: 32 })),\n\t\tclearCompleted: Type.Optional(\n\t\t\tType.Boolean({ description: \"For list: compact completed and cancelled steps before rendering.\" }),\n\t\t),\n\t\tshowCompleted: Type.Optional(Type.Boolean({ description: \"Include completed and cancelled steps in output.\" })),\n\t\tmaxItems: Type.Optional(Type.Integer({ minimum: 1, maximum: MAX_TASK_STEPS })),\n\t},\n\t{ additionalProperties: false },\n);\n\nexport type TaskStepsToolInput = Static<typeof taskStepsSchema>;\nexport type TaskStepsAction = TaskStepsToolInput[\"action\"];\n\nexport interface TaskStepsToolDetails {\n\taction: TaskStepsAction;\n\tapplied: boolean;\n\terror?: string;\n\tstate?: TaskStepsState;\n\tstepCount?: number;\n\topenStepCount?: number;\n\tverificationNudgeNeeded?: boolean;\n\tshowCompleted?: boolean;\n\t/** Set when `add` was a no-op because an open step already carries this content. */\n\tduplicateOfStepId?: string;\n\t/** Step ids silently demoted to pending because another step became active in this call. */\n\tdemotedStepIds?: readonly string[];\n}\n\nexport interface TaskStepsToolDependencies {\n\tgetTaskStepsState: () => TaskStepsState | undefined;\n\tsaveTaskStepsState: (state: TaskStepsState) => void;\n\tnow?: () => string;\n}\n\nfunction toTaskStepInput(input: TaskStepsToolInput): TaskStepInput {\n\treturn {\n\t\tcontent: input.content ?? \"\",\n\t\tactiveForm: input.activeForm,\n\t\tstatus: input.status,\n\t\tpriority: input.priority,\n\t\towner: input.owner,\n\t\trequirementIds: input.requirementIds,\n\t\tnote: input.note,\n\t\tevidence: input.evidence,\n\t};\n}\n\nfunction counts(\n\tstate: TaskStepsState,\n): Pick<TaskStepsToolDetails, \"stepCount\" | \"openStepCount\" | \"verificationNudgeNeeded\"> {\n\tconst openStepCount = state.steps.filter(\n\t\t(step) => step.status !== \"completed\" && step.status !== \"cancelled\",\n\t).length;\n\treturn {\n\t\tstepCount: state.steps.length,\n\t\topenStepCount,\n\t\tverificationNudgeNeeded: hasUnverifiedCompletedStep(state),\n\t};\n}\n\n/** Ids (from `resultSteps`, index-aligned with `inputs`) whose status was set explicitly by the caller. */\nfunction explicitStatusStepIds(inputs: readonly TaskStepInput[], resultSteps: readonly TaskStep[]): Set<string> {\n\tconst ids = new Set<string>();\n\tinputs.forEach((stepInput, index) => {\n\t\tif (stepInput.status !== undefined) {\n\t\t\tconst id = resultSteps[index]?.id;\n\t\t\tif (id) ids.add(id);\n\t\t}\n\t});\n\treturn ids;\n}\n\n/**\n * Steps that were in_progress before this call and are pending after, excluding any step whose\n * new status was set explicitly by the caller (an explicit change is not a \"silent\" demotion).\n */\nfunction computeDemotedStepIds(\n\tbefore: TaskStepsState,\n\tafter: TaskStepsState,\n\texcludeIds: ReadonlySet<string>,\n): string[] {\n\tconst beforeActiveIds = new Set(before.steps.filter((step) => step.status === \"in_progress\").map((step) => step.id));\n\treturn after.steps\n\t\t.filter((step) => beforeActiveIds.has(step.id) && step.status === \"pending\" && !excludeIds.has(step.id))\n\t\t.map((step) => step.id);\n}\n\nfunction errorResult(action: TaskStepsAction, error: string, state?: TaskStepsState) {\n\treturn {\n\t\tcontent: [{ type: \"text\" as const, text: `task_steps ${action} failed: ${error}` }],\n\t\tdetails: { action, applied: false, error, state, ...(state ? counts(state) : {}) } satisfies TaskStepsToolDetails,\n\t};\n}\n\nfunction taskStepsPanelModel(details: TaskStepsToolDetails, expanded: boolean): OrchestrationPanelModel {\n\tconst state = details.state;\n\tif (!state) {\n\t\treturn {\n\t\t\tlabel: \"task steps\",\n\t\t\taction: details.action,\n\t\t\tstatus: details.error ? \"error\" : \"idle\",\n\t\t\temptyText: details.error ?? \"No checklist state.\",\n\t\t};\n\t}\n\tconst active = state.steps.filter((step) => step.status === \"in_progress\");\n\tconst blocked = state.steps.filter((step) => step.status === \"blocked\");\n\tconst pending = state.steps.filter((step) => step.status === \"pending\");\n\tconst completed = state.steps.filter((step) => step.status === \"completed\");\n\tconst cancelled = state.steps.filter((step) => step.status === \"cancelled\");\n\tconst open = [...active, ...blocked, ...pending];\n\tconst terminal = details.showCompleted ? [...completed, ...cancelled] : [];\n\tconst candidates = [...open, ...terminal];\n\tconst limit = expanded ? 24 : 8;\n\tconst rows = candidates.slice(0, limit).map(taskStepPanelRow);\n\tconst archivedDone = state.archive.completed + state.archive.cancelled;\n\tconst done = completed.length + state.archive.completed;\n\tconst summary = [\n\t\tactive.length ? `${active.length} working` : undefined,\n\t\t`${open.length} open`,\n\t\t`${done} done`,\n\t\tblocked.length ? `${blocked.length} blocked` : undefined,\n\t\tarchivedDone ? `${archivedDone} archived` : undefined,\n\t].filter((value): value is string => value !== undefined);\n\tconst notices = [];\n\tif (!details.showCompleted && completed.length + cancelled.length > 0) {\n\t\tnotices.push({\n\t\t\tstatus: \"info\" as const,\n\t\t\ttext: `${completed.length + cancelled.length} finished step${completed.length + cancelled.length === 1 ? \"\" : \"s\"} hidden`,\n\t\t});\n\t}\n\tif (details.duplicateOfStepId) {\n\t\tnotices.push({ status: \"info\" as const, text: \"Duplicate open step ignored.\" });\n\t}\n\tif (details.demotedStepIds?.length) {\n\t\tnotices.push({\n\t\t\tstatus: \"info\" as const,\n\t\t\ttext: `${details.demotedStepIds.length} previous working step${details.demotedStepIds.length === 1 ? \"\" : \"s\"} returned to pending.`,\n\t\t});\n\t}\n\tif (details.verificationNudgeNeeded) {\n\t\tnotices.push({ status: \"warning\" as const, text: \"Completed work still needs attached evidence.\" });\n\t}\n\tconst status = details.error\n\t\t? \"error\"\n\t\t: blocked.length > 0\n\t\t\t? \"warning\"\n\t\t\t: active.length > 0\n\t\t\t\t? \"running\"\n\t\t\t\t: open.length === 0 && state.steps.length > 0\n\t\t\t\t\t? \"success\"\n\t\t\t\t\t: \"idle\";\n\treturn {\n\t\tlabel: \"task steps\",\n\t\taction: details.action,\n\t\tstatus,\n\t\tsummary,\n\t\trows,\n\t\tnotices,\n\t\temptyText: state.steps.length === 0 ? \"No tracked steps.\" : \"All open steps are done.\",\n\t\thiddenRowCount: Math.max(0, candidates.length - rows.length),\n\t};\n}\n\nexport function createTaskStepsToolDefinition(deps: TaskStepsToolDependencies): ToolDefinition {\n\tconst now = deps.now ?? (() => new Date().toISOString());\n\treturn {\n\t\tname: \"task_steps\",\n\t\tlabel: \"Task Steps\",\n\t\tdescription:\n\t\t\t\"Maintain the current session's native ordered checklist for multi-step work. Supports pending, in_progress, completed, blocked, and cancelled steps with notes and evidence. State is isolated to and persisted with the active session; use native goal for durable outcome requirements and native delegate/delegate_status for background workers.\",\n\t\tpromptSnippet: \"Track and drain multi-step work with a native session checklist.\",\n\t\tpromptGuidelines: [\n\t\t\t\"Use task_steps for complex work, explicit task-tracking requests, and harness/self-improvement work; keep exactly one step in_progress while actively working.\",\n\t\t\t\"Always address the first open task step before unrelated work: start it, complete/block/cancel it with evidence, ask one clarifying question, or explicitly defer or reorder it.\",\n\t\t\t\"Mark steps completed as soon as evidence is gathered, and attach concise evidence or a blocker reason through update.\",\n\t\t\t\"Use action=intake with a complete steps array when preserving a raw multi-item dump; retain every item and do not silently drop entries.\",\n\t\t\t\"When a goal is active, set requirementIds on each step that advances a goal requirement; do not rely on repeating requirement text.\",\n\t\t\t\"Drain task_steps before final responses: leave no stale in_progress step, and explicitly discuss or defer remaining pending or blocked work.\",\n\t\t\t\"Use goal for the durable goal ledger and delegate/delegate_status for worker lanes; do not emulate background execution inside task_steps.\",\n\t\t],\n\t\tparameters: taskStepsSchema,\n\t\trenderShell: \"self\",\n\t\trenderCall() {\n\t\t\treturn emptyOrchestrationCall();\n\t\t},\n\t\trenderResult(result, { expanded, isPartial }, theme) {\n\t\t\tif (isPartial) {\n\t\t\t\treturn new OrchestrationPanelComponent(theme, {\n\t\t\t\t\tlabel: \"task steps\",\n\t\t\t\t\taction: \"updating\",\n\t\t\t\t\tstatus: \"running\",\n\t\t\t\t});\n\t\t\t}\n\t\t\tconst details = result.details as TaskStepsToolDetails | undefined;\n\t\t\tif (!details) {\n\t\t\t\treturn new OrchestrationPanelComponent(theme, {\n\t\t\t\t\tlabel: \"task steps\",\n\t\t\t\t\tstatus: \"error\",\n\t\t\t\t\temptyText: \"No task-step details were returned.\",\n\t\t\t\t});\n\t\t\t}\n\t\t\treturn new OrchestrationPanelComponent(theme, taskStepsPanelModel(details, expanded), expanded);\n\t\t},\n\t\tasync execute(_toolCallId, input: TaskStepsToolInput) {\n\t\t\tconst timestamp = now();\n\t\t\tconst current = deps.getTaskStepsState();\n\t\t\tconst before = current ?? createTaskStepsState(timestamp);\n\t\t\tlet state = before;\n\t\t\tlet duplicateStepId: string | undefined;\n\t\t\tlet demotedStepIds: readonly string[] = [];\n\t\t\ttry {\n\t\t\t\tswitch (input.action) {\n\t\t\t\t\tcase \"set\":\n\t\t\t\t\t\tif (!input.steps) return errorResult(input.action, \"set requires steps[].\", current);\n\t\t\t\t\t\tstate = setTaskSteps(state, input.steps, timestamp);\n\t\t\t\t\t\tdemotedStepIds = computeDemotedStepIds(\n\t\t\t\t\t\t\tbefore,\n\t\t\t\t\t\t\tstate,\n\t\t\t\t\t\t\texplicitStatusStepIds(input.steps, state.steps),\n\t\t\t\t\t\t);\n\t\t\t\t\t\tbreak;\n\t\t\t\t\tcase \"intake\":\n\t\t\t\t\t\tif (!input.steps)\n\t\t\t\t\t\t\treturn errorResult(input.action, \"intake requires a complete steps[] list.\", current);\n\t\t\t\t\t\tstate = setTaskSteps(state, input.steps, timestamp);\n\t\t\t\t\t\tdemotedStepIds = computeDemotedStepIds(\n\t\t\t\t\t\t\tbefore,\n\t\t\t\t\t\t\tstate,\n\t\t\t\t\t\t\texplicitStatusStepIds(input.steps, state.steps),\n\t\t\t\t\t\t);\n\t\t\t\t\t\tbreak;\n\t\t\t\t\tcase \"add\":\n\t\t\t\t\t\tstate = addTaskStep(state, toTaskStepInput(input), timestamp);\n\t\t\t\t\t\tif (state === before) {\n\t\t\t\t\t\t\t// The reducer returned the unchanged state: an open step already carries this\n\t\t\t\t\t\t\t// content, so nothing was created. Name the existing step in the response.\n\t\t\t\t\t\t\tduplicateStepId = findOpenDuplicateStep(before.steps, input.content ?? \"\")?.id;\n\t\t\t\t\t\t}\n\t\t\t\t\t\tbreak;\n\t\t\t\t\tcase \"update\": {\n\t\t\t\t\t\tif (!input.id?.trim())\n\t\t\t\t\t\t\treturn errorResult(input.action, \"update requires id or a unique selector.\", current);\n\t\t\t\t\t\tconst selected = resolveTaskStepSelector(before.steps, input.id);\n\t\t\t\t\t\tstate = updateTaskStep(\n\t\t\t\t\t\t\tstate,\n\t\t\t\t\t\t\tinput.id,\n\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\tcontent: input.content,\n\t\t\t\t\t\t\t\tactiveForm: input.activeForm,\n\t\t\t\t\t\t\t\tstatus: input.status,\n\t\t\t\t\t\t\t\tpriority: input.priority,\n\t\t\t\t\t\t\t\towner: input.owner,\n\t\t\t\t\t\t\t\trequirementIds: input.requirementIds,\n\t\t\t\t\t\t\t\tnote: input.note,\n\t\t\t\t\t\t\t\tevidence: input.evidence,\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\ttimestamp,\n\t\t\t\t\t\t);\n\t\t\t\t\t\t// Exclude the explicitly targeted step: its own status change was requested by\n\t\t\t\t\t\t// the caller, so it is never a \"silent\" demotion even if it moved to pending.\n\t\t\t\t\t\tdemotedStepIds = computeDemotedStepIds(before, state, new Set([selected.id]));\n\t\t\t\t\t\tbreak;\n\t\t\t\t\t}\n\t\t\t\t\tcase \"clear\":\n\t\t\t\t\t\tstate = clearTaskSteps(state, timestamp);\n\t\t\t\t\t\tbreak;\n\t\t\t\t\tcase \"compact\":\n\t\t\t\t\t\tstate = compactTaskSteps(state, timestamp);\n\t\t\t\t\t\tbreak;\n\t\t\t\t\tcase \"list\":\n\t\t\t\t\t\tif (input.clearCompleted) state = compactTaskSteps(state, timestamp);\n\t\t\t\t\t\tbreak;\n\t\t\t\t}\n\n\t\t\t\tconst isNoopDuplicateAdd = input.action === \"add\" && state === before;\n\t\t\t\tconst mutated = (input.action !== \"list\" || input.clearCompleted === true) && !isNoopDuplicateAdd;\n\t\t\t\tif (mutated) deps.saveTaskStepsState(state);\n\n\t\t\t\tconst stateCounts = counts(state);\n\t\t\t\tconst noticeLines: string[] = [];\n\t\t\t\tif (duplicateStepId) {\n\t\t\t\t\tnoticeLines.push(\n\t\t\t\t\t\t`Duplicate open step ignored; existing ${duplicateStepId} already tracks this content.`,\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\tif (demotedStepIds.length > 0) {\n\t\t\t\t\tnoticeLines.push(`Demoted to pending because another step became active: ${demotedStepIds.join(\", \")}.`);\n\t\t\t\t}\n\t\t\t\tif (stateCounts.verificationNudgeNeeded) {\n\t\t\t\t\tnoticeLines.push(\n\t\t\t\t\t\t\"Reminder: a completed step has no evidence attached; attach evidence via update before treating it as verified.\",\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\tconst notices = noticeLines.length > 0 ? `\\n${noticeLines.join(\"\\n\")}` : \"\";\n\n\t\t\t\tconst headerAction =\n\t\t\t\t\tinput.action === \"list\"\n\t\t\t\t\t\t? \"\"\n\t\t\t\t\t\t: `task_steps ${input.action} ${duplicateStepId ? \"ignored (duplicate)\" : \"recorded\"}.\\n`;\n\t\t\t\treturn {\n\t\t\t\t\tcontent: [\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\ttype: \"text\" as const,\n\t\t\t\t\t\t\ttext: `${headerAction}${formatTaskSteps(state, {\n\t\t\t\t\t\t\t\tincludeTerminal: input.showCompleted,\n\t\t\t\t\t\t\t\tmaxItems: input.maxItems,\n\t\t\t\t\t\t\t})}${notices}`,\n\t\t\t\t\t\t},\n\t\t\t\t\t],\n\t\t\t\t\tdetails: {\n\t\t\t\t\t\taction: input.action,\n\t\t\t\t\t\tapplied: true,\n\t\t\t\t\t\tstate,\n\t\t\t\t\t\t...stateCounts,\n\t\t\t\t\t\tshowCompleted: input.showCompleted,\n\t\t\t\t\t\tduplicateOfStepId: duplicateStepId,\n\t\t\t\t\t\tdemotedStepIds: demotedStepIds.length > 0 ? demotedStepIds : undefined,\n\t\t\t\t\t} satisfies TaskStepsToolDetails,\n\t\t\t\t};\n\t\t\t} catch (error) {\n\t\t\t\treturn errorResult(input.action, error instanceof Error ? error.message : String(error), current);\n\t\t\t}\n\t\t},\n\t};\n}\n"]}