@pugi/cli 0.1.0-beta.7 → 0.1.0-beta.87

package/dist/tools/powershell.js

@@ -0,0 +1,268 @@
+/**
+ * PowerShell tool — .
+ *
+ * Windows operators cannot run native `*.ps1` scripts via the bash tool
+ * (which spawns `/bin/sh`). This tool spawns `pwsh -NoProfile -Command`
+ * на cross-platform PowerShell 7+ binary so Windows-first workflows are
+ * first-class на Pugi.
+ *
+ * Clean-room re-implementation. Surface mirrors bashTool's permission
+ * gate, env sanitiser, output cap, timeout, and exit-code propagation;
+ * the only difference is the shell binary selection. Per-platform
+ * resolution:
+ *  - All OS: try `pwsh` on $PATH first (PowerShell 7+ cross-platform).
+ *  - Windows fallback: `powershell.exe` (Windows PowerShell 5.1 baked-in).
+ *  - Other OS without pwsh: tool returns a clear "powershell binary
+ *    not found" error so the operator can install pwsh or fall back
+ *    к bash.
+ *
+ * Permission class: reuses the bash classifier — destructive patterns,
+ * sandbox detection, and additional-directories checks are command-string
+ * based and apply equally to pwsh and sh.
+ */
+import { spawnSync } from 'node:child_process';
+import { listDestructivePatterns } from '../core/bash-classifier.js';
+import { recordToolCall, recordToolResult } from '../core/session.js';
+export const POWERSHELL_OUTPUT_CAP_BYTES = 64 * 1024;
+export const POWERSHELL_DEFAULT_TIMEOUT_MS = 30_000;
+export const POWERSHELL_MAX_TIMEOUT_MS = 120_000;
+/**
+ * PowerShell-specific destructive patterns. Layered ON TOP of the
+ * shared `listDestructivePatterns()` from the bash classifier (which
+ * covers `rm -rf`, `DROP TABLE`, etc — patterns that also surface в
+ * pwsh-via-aliases). These are the cmdlet forms unique to pwsh.
+ *
+ * Patterns are case-insensitive matched against the command string
+ * (pwsh cmdlets accept any case: `remove-item -force` == `Remove-Item -Force`).
+ */
+const PWSH_DESTRUCTIVE_PATTERNS = [
+    // Recursive force delete via cmdlet
+    'remove-item -recurse -force',
+    'remove-item -force -recurse',
+    'ri -recurse -force',
+    'ri -force -recurse',
+    'rmdir -recurse -force',
+    'rmdir -force -recurse',
+    // Disk / volume operations
+    'format-volume',
+    'clear-disk',
+    'reset-physicaldisk',
+    // System state
+    'stop-computer',
+    'restart-computer',
+    'shutdown',
+    // Security weakening
+    'set-executionpolicy unrestricted',
+    'set-executionpolicy bypass',
+    // Service / process attack surface
+    'invoke-webrequest', // common phishing-script vector when piped to iex
+    'iex (new-object', // download-execute pattern
+    // Credential exfil
+    'get-credential | export-clixml',
+];
+/**
+ * Normalize whitespace before pattern matching: collapse runs of
+ * whitespace к single space + lowercase. Defends against the
+ * `iex(New-Object`/`IEX (New-Object` style bypass where pattern
+ * `iex (new-object` would miss the no-space or double-space variant.
+ */
+function normalizeForMatch(text) {
+    return text.toLowerCase().replace(/\s+/g, ' ');
+}
+function findPwshDestructiveMatch(cmd) {
+    const normalized = normalizeForMatch(cmd);
+    for (const pattern of PWSH_DESTRUCTIVE_PATTERNS) {
+        if (normalized.includes(normalizeForMatch(pattern)))
+            return pattern;
+    }
+    // Fall back к the shared bash destructive list (covers cross-shell
+    // patterns like `rm -rf /`, `DROP DATABASE`). Shared patterns may
+    // contain uppercase (case-insensitive SQL verbs); normalize both
+    // sides before compare.
+    const shared = listDestructivePatterns();
+    for (const pattern of shared) {
+        if (normalized.includes(normalizeForMatch(pattern)))
+            return pattern;
+    }
+    return null;
+}
+/**
+ * PowerShell-aware permission decision. Differs from
+ * `evaluateBashPermission` в two ways:
+ *
+ *  1. Default class is `allow` (after destructive check) instead of
+ *     `unknown → deny`. The bash classifier rejects any first-token
+ *     it does not recognise — appropriate for bash where every verb
+ *     is a separate binary, hostile for pwsh where the Verb-Noun
+ *     cmdlet convention means thousands of legitimate verbs exist
+ *     (`Get-Process`, `$PSVersionTable`, `Select-Object`, ...).
+ *
+ *  2. Destructive patterns combine the shared bash denylist (covers
+ *     cross-shell patterns like `rm -rf`) с pwsh-specific cmdlet
+ *     forms (`Remove-Item -Recurse -Force`, `Format-Volume`, etc).
+ *
+ * Mode FSM mirrors bash: plan → deny ALL, ask → ask, auto/bypass → allow,
+ * destructive class → deny unless `bypassPermissions + human + ENV override`.
+ */
+function evaluatePwshPermission(cmd, mode, source) {
+    const destructive = findPwshDestructiveMatch(cmd);
+    if (destructive !== null) {
+        const overrideOk = mode === 'bypassPermissions' &&
+            source === 'human' &&
+            process.env['PUGI_DESTRUCTIVE_OVERRIDE'] === '1';
+        if (overrideOk) {
+            return {
+                decision: 'allow',
+                reason: `destructive pwsh pattern '${destructive}' allowed via override (bypassPermissions + human + PUGI_DESTRUCTIVE_OVERRIDE=1)`,
+            };
+        }
+        return {
+            decision: 'deny',
+            reason: `destructive pwsh pattern '${destructive}' is always denied (override requires bypassPermissions + human + PUGI_DESTRUCTIVE_OVERRIDE=1)`,
+        };
+    }
+    // Non-destructive pwsh command — mode FSM.
+    switch (mode) {
+        case 'plan':
+            return { decision: 'deny', reason: 'plan mode denies all shell dispatches' };
+        case 'ask':
+        case 'acceptEdits':
+            return { decision: 'ask', reason: 'pwsh command requires operator confirmation' };
+        case 'auto':
+        case 'dontAsk':
+        case 'bypassPermissions':
+            return { decision: 'allow', reason: 'pwsh command allowed by mode' };
+        default:
+            return { decision: 'ask', reason: `unknown mode ${mode}; defaulting к ask` };
+    }
+}
+/** Cached binary path so repeated calls inside one session skip the probe. */
+let cachedShellBinary;
+function resolveShellBinary() {
+    if (cachedShellBinary !== undefined)
+        return cachedShellBinary;
+    // Try pwsh (cross-platform PowerShell 7+) first.
+    const pwshProbe = spawnSync('pwsh', ['-NoProfile', '-Command', 'exit 0'], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'ignore', 'ignore'],
+        timeout: 3000,
+    });
+    if (pwshProbe.status === 0) {
+        cachedShellBinary = 'pwsh';
+        return 'pwsh';
+    }
+    // Windows fallback к the baked-in PowerShell 5.1.
+    if (process.platform === 'win32') {
+        const wpsProbe = spawnSync('powershell.exe', ['-NoProfile', '-Command', 'exit 0'], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'ignore', 'ignore'],
+            timeout: 3000,
+        });
+        if (wpsProbe.status === 0) {
+            cachedShellBinary = 'powershell.exe';
+            return 'powershell.exe';
+        }
+    }
+    cachedShellBinary = null;
+    return null;
+}
+function sanitizeTimeout(value) {
+    if (value === undefined || !Number.isFinite(value) || value <= 0) {
+        return POWERSHELL_DEFAULT_TIMEOUT_MS;
+    }
+    return Math.min(value, POWERSHELL_MAX_TIMEOUT_MS);
+}
+function buildChildEnv() {
+    const env = { ...process.env };
+    delete env['PUGI_API_KEY'];
+    delete env['PUGI_LOGIN_TOKEN'];
+    return env;
+}
+/**
+ * Sync PowerShell dispatch. Mirrors bashToolSync shape so dispatchTool
+ * can call either tool with the same context shape.
+ */
+export function powerShellToolSync(input, ctx) {
+    const cmd = input.cmd ?? '';
+    const source = ctx.source ?? 'agent';
+    const toolCallId = recordToolCall(ctx.session, 'powershell', cmd);
+    // pwsh-aware permission gate (NOT the bash classifier). Bash classifier
+    // would reject `$PSVersionTable`, `Get-Process`, etc as "Unrecognized
+    // command" → default-deny, making the pwsh tool useless. The pwsh gate
+    // applies the shared destructive denylist (rm -rf / DROP TABLE) + a
+    // pwsh-specific list (Remove-Item -Recurse -Force / Format-Volume /
+    // Set-ExecutionPolicy Unrestricted / iex (New-Object ...)) and
+    // defaults non-destructive cmdlets к allow under mode FSM.
+    const decision = evaluatePwshPermission(cmd, ctx.settings.permissions.mode, source);
+    if (decision.decision !== 'allow') {
+        const reason = `Permission ${decision.decision}: ${decision.reason}`;
+        recordToolResult(ctx.session, toolCallId, 'error', reason);
+        return {
+            stdout: '',
+            stderr: `Permission ${decision.decision}: ${decision.reason}`,
+            exitCode: 126,
+            truncated: false,
+            timedOut: false,
+            shellBinary: 'unresolved',
+        };
+    }
+    const shellBinary = resolveShellBinary();
+    if (shellBinary === null) {
+        const reason = 'powershell binary not found (tried pwsh' +
+            (process.platform === 'win32' ? ', powershell.exe' : '') +
+            '). Install PowerShell 7+ from https://aka.ms/powershell or use the bash tool instead.';
+        recordToolResult(ctx.session, toolCallId, 'error', reason);
+        return {
+            stdout: '',
+            stderr: reason,
+            exitCode: 127,
+            truncated: false,
+            timedOut: false,
+            shellBinary: 'unavailable',
+        };
+    }
+    const timeoutMs = sanitizeTimeout(input.timeoutMs);
+    const childEnv = buildChildEnv();
+    const cwd = input.cwd ?? ctx.root;
+    const result = spawnSync(shellBinary, ['-NoProfile', '-Command', cmd], {
+        cwd,
+        env: childEnv,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: timeoutMs,
+        maxBuffer: 10 * 1024 * 1024,
+    });
+    const stdoutFull = (result.stdout ?? '').toString();
+    const stderrFull = (result.stderr ?? '').toString();
+    const combined = stdoutFull.length + stderrFull.length;
+    const truncated = combined > POWERSHELL_OUTPUT_CAP_BYTES;
+    let stdoutOut = stdoutFull;
+    let stderrOut = stderrFull;
+    if (truncated) {
+        const halfCap = POWERSHELL_OUTPUT_CAP_BYTES / 2;
+        stdoutOut = stdoutFull.slice(0, halfCap);
+        stderrOut = stderrFull.slice(0, halfCap);
+    }
+    const timedOut = result.error?.code === 'ETIMEDOUT' ||
+        result.signal === 'SIGTERM';
+    const exitCode = timedOut ? 124 : result.status ?? 1;
+    if (timedOut) {
+        recordToolResult(ctx.session, toolCallId, 'error', `powershell timed out after ${timeoutMs}ms`);
+    }
+    else {
+        recordToolResult(ctx.session, toolCallId, 'success', `powershell exit=${exitCode} bytes=${combined} binary=${shellBinary}`);
+    }
+    return {
+        stdout: stdoutOut,
+        stderr: stderrOut,
+        exitCode,
+        truncated,
+        timedOut,
+        shellBinary,
+    };
+}
+/** Visible-for-spec helper: forces a re-probe on next call. */
+export function _resetShellBinaryCacheForSpec() {
+    cachedShellBinary = undefined;
+}
+//# sourceMappingURL=powershell.js.map

package/dist/tools/registry.js

@@ -1,16 +1,101 @@
 const registry = [
+    // : unified-diff patch apply. Routes through the same security
+    // gate as Layer A/B/C, so the risk class matches `edit`/`write`
+    // (medium — writes inside the workspace, never to protected files).
+    { name: 'apply_patch', permission: 'edit', risk: 'medium', concurrencySafe: false, m1: true },
+    // structured multi-choice clarifier tool. Risk =
+    // low because the dispatch is a pure UI surface — no file writes, no
+    // shell, no network. Permission = none (no workspace access required).
+    // concurrencySafe = true because the prompt-budget gate runs in the
+    // engine loop, not via tool-side mutex (one prompt per turn is enforced
+    // by the persona system prompt + the engine's tool_calls budget).
+    { name: 'ask_user_question', permission: 'none', risk: 'low', concurrencySafe: true, m1: true },
     { name: 'bash', permission: 'bash', risk: 'high', concurrencySafe: false, m1: true },
+    // Tool gap pack : structured progress brief. Writes
+    // one JSONL record to `.pugi/briefs/<session>.jsonl` per call via
+    // atomic tmp+rename. Risk = low (metadata only, no source mutation).
+    // concurrencySafe = false because the read-modify-write loop is not
+    // atomic (the rename is atomic but two parallel dispatches could lose
+    // the loser's record).
+    { name: 'brief', permission: 'none', risk: 'low', concurrencySafe: false, m1: false },
+    // Backlog #5 P0 : verify_plan_execution anti-fake-dispatch gate.
+    // Reads session audit events only; safe для parallel dispatches.
+    { name: 'verify_plan_execution', permission: 'none', risk: 'low', concurrencySafe: true, m1: false },
     { name: 'edit', permission: 'edit', risk: 'medium', concurrencySafe: false, m1: true },
+    // Tool gap pack : scratch worktree open. Spawns
+    // `git worktree add` under `.pugi/worktrees/<taskId>/`. Permission =
+    // edit because the spawn materialises files on disk; risk = medium
+    // to mirror the existing worktree_create posture (PR r1 raised
+    // that one for disk-pressure parity, same applies here).
+    { name: 'enter_worktree', permission: 'edit', risk: 'medium', concurrencySafe: false, m1: false },
+    // Tool gap pack : scratch worktree teardown. The
+    // destructive primitive — runs `git worktree remove --force` then a
+    // recursive rmSync, both gated by a strict containment check that
+    // refuses any path outside <workspace>/.pugi/worktrees/. Mirrors
+    // worktree_drop's medium-risk posture for the same reason.
+    { name: 'exit_worktree', permission: 'edit', risk: 'medium', concurrencySafe: false, m1: false },
     { name: 'glob', permission: 'read', risk: 'low', concurrencySafe: true, m1: true },
     { name: 'grep', permission: 'read', risk: 'low', concurrencySafe: true, m1: true },
+    // : LSP read-only surface. Server runs locally, no Anvil
+    // round-trip. Concurrency-safe because every operation reads
+    // server state without mutating workspace files.
+    { name: 'lsp_definition', permission: 'read', risk: 'low', concurrencySafe: true, m1: true },
+    { name: 'lsp_diagnostics', permission: 'read', risk: 'low', concurrencySafe: true, m1: true },
+    { name: 'lsp_hover', permission: 'read', risk: 'low', concurrencySafe: true, m1: true },
+    { name: 'lsp_references', permission: 'read', risk: 'low', concurrencySafe: true, m1: true },
+    // β7 L5+T11: multi_edit dispatches an ordered batch of Layer A edits
+    // as a single transaction. Risk = medium (same chokepoints as `edit`).
+    // concurrencySafe = false because the journal serialises one dispatch
+    // per session.
+    { name: 'multi_edit', permission: 'edit', risk: 'medium', concurrencySafe: false, m1: true },
+    // PowerShell tool for Windows-first workflows. Same
+    // bash permission class — destructive-pattern classification fires the
+    // same gate. concurrencySafe = false because spawn-shell child cwd /
+    // env carry-over could race across parallel agent calls.
+    { name: 'powershell', permission: 'bash', risk: 'high', concurrencySafe: false, m1: false },
     { name: 'question', permission: 'none', risk: 'low', concurrencySafe: false, m1: true },
     { name: 'read', permission: 'read', risk: 'low', concurrencySafe: true, m1: true },
     { name: 'skill', permission: 'read', risk: 'low', concurrencySafe: true, m1: true },
+    // Tool gap pack : wall-clock pause primitive. No
+    // filesystem / network / shell side-effects. concurrencySafe = true
+    // because every dispatch is a fresh setTimeout closure with no
+    // shared state.
+    { name: 'sleep', permission: 'none', risk: 'low', concurrencySafe: true, m1: false },
+    // Tool gap pack : experimental engine-only echo
+    // helper. Writes verbatim bytes to the requested stream so a test
+    // harness can assert on the dispatch without spinning the full
+    // engine loop. NOT advertised to customer agents (allowSyntheticOutput
+    // opt-in at the executor level). Risk = low (no source mutation, no
+    // shell), concurrencySafe = true (writes go to fresh stream calls).
+    { name: 'synthetic_output', permission: 'none', risk: 'low', concurrencySafe: true, m1: false },
     { name: 'task_create', permission: 'none', risk: 'low', concurrencySafe: false, m1: true },
     { name: 'task_get', permission: 'none', risk: 'low', concurrencySafe: true, m1: true },
     { name: 'task_list', permission: 'none', risk: 'low', concurrencySafe: true, m1: true },
     { name: 'task_update', permission: 'none', risk: 'low', concurrencySafe: false, m1: true },
+    // batch TodoWrite. Mirrors the standard tool's upstream
+    // surface — full board snapshot, single-in-progress invariant, atomic
+    // tmp+rename persistence to `.pugi/todos.json`. `concurrencySafe = false`
+    // because two concurrent writes could lose the loser's snapshot (the
+    // rename is atomic but the read-modify-write loop is not). Risk = low
+    // because the only filesystem mutation lands inside `.pugi/todos.json`,
+    // which is metadata, not source.
+    { name: 'todo_write', permission: 'none', risk: 'low', concurrencySafe: false, m1: true },
     { name: 'web_fetch', permission: 'network', risk: 'medium', concurrencySafe: true, m1: true },
+    // : scratch worktree management. `worktree_create` writes nothing
+    // dangerous (a clone under `.pugi/worktrees/`); `worktree_promote`
+    // applies a diff back to the main tree, so it shares the `edit`
+    // risk class. `worktree_drop` is the cleanup primitive.
+    //
+    // R1 fix (2026-05-26, PR r1, Fix 9): raised `worktree_create`
+    // and `worktree_drop` from `low` to `medium`. `worktree_drop` runs
+    // `rmSync` on its target — even with the new path-containment gate
+    // in `core/edits/worktree.ts::dropWorktree`, a destructive primitive
+    // belongs in `medium` so the permission FSM prompts on every call.
+    // `worktree_create` is raised for disk-pressure parity (a runaway
+    // agent loop could fill the disk with abandoned scratch worktrees).
+    { name: 'worktree_create', permission: 'edit', risk: 'medium', concurrencySafe: false, m1: true },
+    { name: 'worktree_drop', permission: 'edit', risk: 'medium', concurrencySafe: false, m1: true },
+    { name: 'worktree_promote', permission: 'edit', risk: 'medium', concurrencySafe: false, m1: true },
     { name: 'write', permission: 'edit', risk: 'medium', concurrencySafe: false, m1: true },
 ];
 export const toolRegistry = registry.sort((a, b) => a.name.localeCompare(b.name));

package/dist/tools/skill-tool.js

@@ -0,0 +1,96 @@
+import { listSkills } from '../core/skills/loader.js';
+import { hashSkillDir, verifyTrust } from '../core/skills/trust.js';
+export const SKILL_BODY_CAP_BYTES = 32 * 1024;
+export const SKILL_LIST_CAP = 100;
+export function skillList(ctx, input) {
+    const scope = input.scope ?? 'all';
+    const all = [];
+    if (scope === 'all' || scope === 'global') {
+        all.push(...listSkills('global', ctx.workspaceRoot));
+    }
+    if (scope === 'all' || scope === 'workspace') {
+        all.push(...listSkills('workspace', ctx.workspaceRoot));
+    }
+    // Dedup by name, prefer workspace scope when both exist (workspace
+    // overrides global per skills loader convention).
+    const byName = new Map();
+    for (const skill of all) {
+        const prev = byName.get(skill.name);
+        if (!prev || skill.scope === 'workspace') {
+            byName.set(skill.name, skill);
+        }
+    }
+    return Array.from(byName.values())
+        .slice(0, SKILL_LIST_CAP)
+        .map((skill) => ({
+        name: skill.name,
+        description: skill.frontmatter.description,
+        scope: skill.scope,
+    }));
+}
+export async function skillInvoke(ctx, input) {
+    if (!input.name || typeof input.name !== 'string') {
+        throw new Error('skill: name is required');
+    }
+    // Defense-in-depth: skill loader already validates slugs but the
+    // tool surface is operator-controlled.
+    if (!/^[a-zA-Z0-9_-]{1,128}$/.test(input.name)) {
+        throw new Error(`skill: invalid skill name shape: "${input.name}"`);
+    }
+    // Workspace scope wins over global (operator override). Mirrors
+    // SkillLoader convention.
+    const workspace = listSkills('workspace', ctx.workspaceRoot).find((s) => s.name === input.name);
+    const global = workspace
+        ? null
+        : listSkills('global', ctx.workspaceRoot).find((s) => s.name === input.name);
+    const skill = workspace ?? global;
+    if (!skill) {
+        throw new Error(`skill: not found: "${input.name}"`);
+    }
+    // β1a r1 : re-verify the on-disk skill payload against
+    // the trust manifest sha256 on EVERY invoke, not just at install
+    // time. Before this fix a post-install swap (malicious npm dep that
+    // touches `~/.pugi/skills/<name>/SKILL.md` after the operator
+    // approved the install) would bypass the trust gate — `listSkills`
+    // reads the body fresh from disk and the loader does no integrity
+    // check. The skill body lands directly in the model's tool result,
+    // so a mutated body is a prompt-injection vector against the agent
+    // loop's tool surface.
+    //
+    // Posture:
+    //  - `trusted`  → proceed (body is hash-pinned).
+    //  - `unsigned` → refuse: the operator never approved this skill.
+    //    This catches the case where a skill directory was dropped in
+    //    manually (no `pugi skills install`) and the loader picked it
+    //    up. Refusing is fail-closed.
+    //  - `mismatch` → refuse + surface the recorded vs actual hashes
+    //    so the operator can decide between re-trust and revoke.
+    //
+    // Performance: `hashSkillDir` walks the skill directory on every
+    // invoke. Skills are small (median 4-8 files, <50KB total) so the
+    // cost is sub-millisecond on warm cache. The β1a r1 spec exercises
+    // a mutated-body case; the existing skill-tool.spec.ts cases for
+    // happy-path use the `recordTrust` helper to seed the registry.
+    const actualHash = hashSkillDir(skill.dir);
+    const verdict = await verifyTrust('skill', skill.scope, skill.name, actualHash);
+    if (verdict.status === 'unsigned') {
+        throw new Error(`skill: refused to invoke "${skill.name}" — no trust entry (run \`pugi skills trust ${skill.name}\` to approve)`);
+    }
+    if (verdict.status === 'mismatch') {
+        throw new Error(`skill: refused to invoke "${skill.name}" — sha256 mismatch (recorded ${verdict.recorded.slice(0, 12)}…, actual ${verdict.actual.slice(0, 12)}…). Re-trust via \`pugi skills trust ${skill.name}\`.`);
+    }
+    const body = skill.body;
+    const truncated = Buffer.byteLength(body, 'utf8') > SKILL_BODY_CAP_BYTES;
+    const cappedBody = truncated
+        ? body.slice(0, SKILL_BODY_CAP_BYTES) +
+            `\n\n(... truncated at ${SKILL_BODY_CAP_BYTES} bytes — see \`pugi skills info ${skill.name}\` for full text)`
+        : body;
+    return {
+        name: skill.name,
+        scope: skill.scope,
+        description: skill.frontmatter.description,
+        body: cappedBody,
+        truncated,
+    };
+}
+//# sourceMappingURL=skill-tool.js.map

package/dist/tools/sleep.js

@@ -0,0 +1,99 @@
+/**
+ * sleep tool — wall-clock pause primitive (tool gap pack).
+ *
+ * Closes a parity gap with the upstream tool's tool surface. The model calls
+ * this when it needs a fixed delay before its next action (waiting on
+ * a process the operator owns, throttling a poll loop). The call
+ * counts against `--max-turns` like every other tool dispatch, so the
+ * budget gate naturally caps abuse.
+ *
+ * Operator guidance: prefer a real poll loop (read + grep + retry) over
+ * blind sleep. The tool exists for the cases where polling is not an
+ * option (a fixed cooldown between API calls, a deterministic settle
+ * window for a build) — most agent flows do NOT want it.
+ *
+ * Wire shape:
+ *  args:  { seconds: number }
+ *          - integer in [1, 600]; non-integer / out-of-range rejects
+ *            at parse time with a sentinel string.
+ *  return: { ok: true, sleptMs: number } serialised JSON.
+ *
+ * No side effects beyond the wall-clock delay; nothing on disk, no
+ * subprocesses, no environment mutation.
+ *
+ * Brand voice: English only, no emoji, no banned words.
+ */
+/** Hard caps. The lower bound rejects zero / negative inputs at parse
+ * time so the model can self-correct; the upper bound matches the
+ * standard tool timeout budget used elsewhere in the CLI. */
+export const SLEEP_MIN_SECONDS = 1;
+export const SLEEP_MAX_SECONDS = 600;
+/** Sentinel prefix returned when input validation rejects the call. */
+export const SLEEP_INVALID_ARGS = 'SLEEP_INVALID_ARGS';
+/**
+ * Validate the raw arguments. Returns the typed value on success or a
+ * `SLEEP_INVALID_ARGS: ...` sentinel string. Non-integer values reject
+ * because partial seconds invite drift across platforms; the model
+ * should round explicitly at the call site.
+ */
+export function parseSleepArgs(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return `${SLEEP_INVALID_ARGS}: arguments must be a JSON object`;
+    }
+    const obj = raw;
+    const seconds = obj['seconds'];
+    if (typeof seconds !== 'number' || !Number.isFinite(seconds)) {
+        return `${SLEEP_INVALID_ARGS}: seconds must be a finite number`;
+    }
+    if (!Number.isInteger(seconds)) {
+        return `${SLEEP_INVALID_ARGS}: seconds must be an integer`;
+    }
+    if (seconds < SLEEP_MIN_SECONDS) {
+        return `${SLEEP_INVALID_ARGS}: seconds must be >= ${SLEEP_MIN_SECONDS}`;
+    }
+    if (seconds > SLEEP_MAX_SECONDS) {
+        return `${SLEEP_INVALID_ARGS}: seconds must be <= ${SLEEP_MAX_SECONDS}`;
+    }
+    return { seconds };
+}
+/**
+ * Dispatch entry point. Validates input, awaits the wall-clock delay,
+ * and returns the structured result envelope as JSON.
+ *
+ * On validation failure returns the sentinel string directly (no throw)
+ * so the engine adapter surfaces it as a recoverable tool result and
+ * the model can self-correct the arguments.
+ */
+export async function dispatchSleep(ctx, raw) {
+    const parsed = parseSleepArgs(raw);
+    if (typeof parsed === 'string') {
+        return parsed;
+    }
+    const ms = parsed.seconds * 1_000;
+    const timer = ctx.timer ?? ((cb, delay) => setTimeout(cb, delay));
+    await new Promise((resolveDelay) => {
+        timer(resolveDelay, ms);
+    });
+    const result = { ok: true, sleptMs: ms };
+    return JSON.stringify(result);
+}
+/**
+ * JSON-Schema fragment the schema builder advertises to the model.
+ * Hand-written for parity with the rest of the tool surface (see the
+ * note on `briefJsonSchema` for why we do not pull in zod-to-json-schema).
+ */
+export const sleepJsonSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['seconds'],
+    properties: {
+        seconds: {
+            type: 'integer',
+            minimum: SLEEP_MIN_SECONDS,
+            maximum: SLEEP_MAX_SECONDS,
+            description: `Wall-clock pause in seconds. Integer in [${SLEEP_MIN_SECONDS}, ${SLEEP_MAX_SECONDS}]. ` +
+                'Prefer a real poll loop over blind sleep; this tool counts against --max-turns.',
+        },
+    },
+};
+//# sourceMappingURL=sleep.js.map