@addai/node 0.4.0

package/dist/grok-spawn.js

@@ -0,0 +1,495 @@
+"use strict";
+// grok -p --output-format streaming-json adapter.
+//
+// Mirrors claude-print.ts / kimi-spawn.ts: spawns `grok` non-interactively
+// with a JSONL output stream, parses each line into our normalised
+// RuntimeEvent shape, and resolves on exit.
+//
+// Two things make grok different from the other agents and drive the
+// design here:
+//
+//   1. No `--mcp-config` flag. Grok discovers MCP servers from
+//      `config.toml` (user + project scope), `~/.claude.json`, and
+//      `.mcp.json` — the Claude-Code compatibility layer. To give an
+//      entity ONLY its own servers we (a) write the entity's servers to a
+//      per-session project `<cwd>/.grok/config.toml`, and (b) run grok
+//      under a sandbox $HOME whose `.claude.json` is empty, so the host's
+//      global Claude MCPs don't leak in. The sandbox HOME symlinks every
+//      other real-home entry so git / npm / ssh still find their configs
+//      (the lesson from kimi: never point HOME at an empty dir).
+//
+//   2. The account lives in `~/.grok/auth.json` and its OAuth token is
+//      refreshed in place. So GROK_HOME stays pointed at the REAL
+//      `~/.grok` — the entity uses the same logged-in account the user
+//      set up, and token refresh keeps working — while only $HOME is
+//      sandboxed.
+//
+// grok's streaming-json emits `thought` (reasoning), `text` (assistant
+// output) and a final `end` (usage + sessionId). It does not surface
+// per-tool events, so unlike claude we can't render individual tool
+// bubbles; unknown types are forwarded as `grok:<type>` for forward-compat.
+//
+// Reference: grok --help, ~/.grok/README.md (Claude Code Compatibility).
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spawnGrok = spawnGrok;
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const grok_binary_1 = require("./grok-binary");
+const win_1 = require("./win");
+const events_1 = require("./events");
+/** Real config dir for the logged-in account. GROK_HOME points here so the
+ *  entity uses the same account and token refresh works. */
+function realGrokHome() {
+    return path.join(os.homedir(), '.grok');
+}
+// Home entries that are MCP / harness discovery sources for grok's
+// Claude-Code compatibility layer. Masked in the sandbox so an entity only
+// sees its own servers, never the host's global Claude/Cursor MCPs.
+const MASKED_HOME_ENTRIES = new Set(['.claude.json', '.claude', '.mcp.json', '.cursor']);
+/** Build a sandbox $HOME: bridge every real-home entry (so git/npm/ssh
+ *  keep working) EXCEPT the Claude/Cursor MCP sources, then drop an empty
+ *  `.claude.json` so host MCPs resolve to nothing. Caller cleans it up.
+ *
+ *  POSIX: plain symlinks. win32: directory junctions (work unprivileged)
+ *  and symlink-or-copy for files (file symlinks need admin/Dev Mode). */
+function writeGrokSandboxHome() {
+    const home = os.homedir();
+    const sandbox = fs.mkdtempSync(path.join(os.tmpdir(), 'entities-grok-home-'));
+    let entries = [];
+    try {
+        entries = fs.readdirSync(home);
+    }
+    catch { /* best-effort */ }
+    for (const name of entries) {
+        if (MASKED_HOME_ENTRIES.has(name))
+            continue;
+        const real = path.join(home, name);
+        const dest = path.join(sandbox, name);
+        if (!win_1.IS_WINDOWS) {
+            try {
+                fs.symlinkSync(real, dest);
+            }
+            catch { /* skip */ }
+            continue;
+        }
+        try {
+            if (fs.statSync(real).isDirectory())
+                (0, win_1.linkDir)(real, dest);
+            else
+                (0, win_1.linkOrCopyFile)(real, dest);
+        }
+        catch { /* unreadable entry — skip */ }
+    }
+    // Empty Claude config → no host MCPs leak through the compat layer.
+    try {
+        fs.writeFileSync(path.join(sandbox, '.claude.json'), JSON.stringify({ mcpServers: {} }), { mode: 0o600 });
+    }
+    catch { /* non-fatal */ }
+    return sandbox;
+}
+/** Env overrides pointing the child's "home" at the sandbox. POSIX tools
+ *  read HOME; on Windows the profile is USERPROFILE (+ HOMEDRIVE/HOMEPATH),
+ *  and HOME alone would change nothing. */
+function sandboxHomeEnv(sandboxHome) {
+    const env = { HOME: sandboxHome };
+    if (win_1.IS_WINDOWS) {
+        env.USERPROFILE = sandboxHome;
+        const parsed = path.parse(sandboxHome);
+        if (parsed.root) {
+            env.HOMEDRIVE = parsed.root.replace(/[\\/]+$/, '');
+            env.HOMEPATH = sandboxHome.slice(env.HOMEDRIVE.length) || '\\';
+        }
+    }
+    return env;
+}
+/** Escape a string for a TOML double-quoted value. */
+function tomlStr(s) {
+    return '"' + s.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n') + '"';
+}
+/** Write the entity's MCP servers as a project-scoped `<cwd>/.grok/config.toml`.
+ *  Project scope only supports `[mcp_servers]`, which is exactly what we need.
+ *  Returns the config path (for logging) or null when there are no servers. */
+function writeProjectMcpConfig(workingDirectory, servers) {
+    const usable = servers.filter(s => s.slug && s.command);
+    if (usable.length === 0) {
+        // No usable servers: remove any stale config.toml from a prior turn.
+        // Returning null WITHOUT deleting leaves grok loading the old servers
+        // (project-scoped config persists in the cwd across turns).
+        try {
+            fs.rmSync(path.join(workingDirectory, '.grok', 'config.toml'), { force: true });
+        }
+        catch { /* nothing to remove */ }
+        return null;
+    }
+    const lines = [];
+    for (const s of usable) {
+        // `cmd /c` wrapper for npm-shim commands on native Windows (no-op on POSIX).
+        const wrapped = (0, win_1.wrapMcpCommandForPlatform)(s.command, Array.isArray(s.args) ? s.args.map(String) : []);
+        lines.push(`[mcp_servers.${tomlStr(s.slug)}]`);
+        lines.push(`command = ${tomlStr(wrapped.command)}`);
+        if (wrapped.args.length > 0) {
+            lines.push(`args = [${wrapped.args.map(a => tomlStr(a)).join(', ')}]`);
+        }
+        if (s.env && Object.keys(s.env).length > 0) {
+            const kv = Object.entries(s.env)
+                .filter(([, v]) => typeof v === 'string' && v.length > 0)
+                .map(([k, v]) => `${/^[A-Za-z0-9_]+$/.test(k) ? k : tomlStr(k)} = ${tomlStr(String(v))}`)
+                .join(', ');
+            lines.push(`env = { ${kv} }`);
+        }
+        lines.push('enabled = true');
+        // Cap MCP startup so a slow/broken server fails the tool instead of
+        // hanging the whole agent (the "thinking forever" class of bug), but
+        // allow enough for a cold `npx` fetch of the server package.
+        lines.push('startup_timeout_sec = 30');
+        lines.push('');
+    }
+    const dir = path.join(workingDirectory, '.grok');
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+        const target = path.join(dir, 'config.toml');
+        fs.writeFileSync(target, lines.join('\n'), { mode: 0o600 });
+        return target;
+    }
+    catch {
+        return null;
+    }
+}
+/** grok issues its own session ids as UUIDv7 (time-ordered, version nibble
+ *  '7', e.g. 019f60ef-6aa4-7fd2-...). A conversation's stored session id may
+ *  come from a DIFFERENT agent (claude etc. use UUIDv4) or the chat framework.
+ *  Passing such an id to `grok --resume` makes grok try to restore it from its
+ *  remote registry, get a 404, and exit 1 — which is why grok failed on
+ *  chatflows continuation turns. Only resume when the id is plausibly a grok
+ *  session; otherwise start fresh (grok couldn't resume a foreign session
+ *  anyway). Degrades safely: an unrecognised id just means a new session. */
+function isGrokSessionId(id) {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id);
+}
+/** Map our effort levels to grok's `--reasoning-effort` accepted values. */
+function grokEffort(level) {
+    switch (level) {
+        case 'low': return 'low';
+        case 'medium': return 'medium';
+        case 'high':
+        case 'xhigh':
+        case 'max': return 'high';
+        default: return null;
+    }
+}
+/** Parse one streaming-json line into 0+ RuntimeEvents. grok emits
+ *  `thought` (reasoning tokens), `text` (assistant output deltas), a final
+ *  `end` (usage + sessionId), and `error`. Tool calls happen internally and
+ *  are not surfaced as discrete events. Anything unrecognised is forwarded
+ *  as `grok:<type>`. */
+function lineToEvents(line) {
+    const type = typeof line.type === 'string' ? line.type : '';
+    const data = typeof line.data === 'string' ? line.data : '';
+    // Assistant output deltas.
+    if (type === 'text') {
+        return data ? [{ type: 'assistant_text', delta: data }] : [];
+    }
+    // Reasoning tokens — normalized 'thinking' deltas (coalesced below like
+    // text). Kept out of the visible answer; the chat relay aggregates them
+    // into a collapsible "thinking" attachment. The old per-token
+    // `grok:thought` passthrough flooded the events table (~1 row/token).
+    if (type === 'thought') {
+        return data ? [{ type: 'thinking', delta: data }] : [];
+    }
+    // Forward-compat: if a future grok build surfaces tool events, map them.
+    if (type === 'tool_use' || type === 'tool_call') {
+        return [{
+                type: 'tool_use',
+                id: String(line.id ?? line.toolCallId ?? ''),
+                name: String(line.name ?? line.tool ?? ''),
+                input: line.input ?? line.args ?? line.arguments,
+            }];
+    }
+    if (type === 'tool_result') {
+        return [{
+                type: 'tool_result',
+                id: String(line.id ?? line.toolCallId ?? ''),
+                content: line.content ?? line.result ?? line.output,
+                isError: line.isError === true || line.is_error === true,
+            }];
+    }
+    // Turn / session end.
+    if (type === 'end' || type === 'result' || type === 'turn_complete') {
+        return [{
+                type: 'turn_complete',
+                usage: line.usage ?? undefined,
+                stopReason: typeof line.stopReason === 'string'
+                    ? line.stopReason
+                    : (typeof line.stop_reason === 'string' ? line.stop_reason : undefined),
+            }];
+    }
+    // Errors.
+    if (type === 'error' || type === 'turn_failed') {
+        const message = line.error?.message
+            ?? (typeof line.message === 'string' ? line.message : 'grok error');
+        return [
+            { type: 'error', code: 'grok_error', message },
+            { type: 'turn_complete', stopReason: 'failed' },
+        ];
+    }
+    return [{ type: `grok:${type || 'unknown'}`, raw: line }];
+}
+function spawnGrok(input) {
+    const bin = (0, grok_binary_1.findGrokBinary)();
+    if (!bin) {
+        // Surface a "grok not installed" error via the event stream so the
+        // chat fails cleanly instead of hanging. bufferedEvents delivers even
+        // though the runner attaches its listener after an await.
+        const events = (0, events_1.bufferedEvents)([
+            { type: 'error', code: 'grok_not_installed', message: 'grok CLI is not installed on this runtime. Install it from https://grok.com and run `grok login`.' },
+            { type: 'turn_complete', stopReason: 'failed' },
+        ]);
+        return {
+            pid: undefined,
+            sessionId: null,
+            kill: () => { },
+            onEvent: events.onEvent,
+            onActivity: () => { },
+            done: Promise.resolve(127),
+        };
+    }
+    const sandboxHome = writeGrokSandboxHome();
+    writeProjectMcpConfig(input.workingDirectory, input.mcpServers ?? []);
+    const args = [
+        '-p', input.prompt,
+        '--output-format', 'streaming-json',
+        '--cwd', input.workingDirectory,
+        // Autonomous entity: no human to answer approvals in headless mode.
+        '--always-approve',
+        // Trust the working folder so its repo-local MCP servers (the entity's
+        // <cwd>/.grok/config.toml) actually START. Without this, grok's
+        // folder-trust gate silently skips repo-local MCP servers in a headless
+        // untrusted dir, and the agent can't call its tools.
+        '--trust',
+    ];
+    // Only resume genuine grok sessions — a foreign (e.g. claude UUIDv4) id
+    // would make grok 404 on remote restore and exit 1.
+    if (input.resumeSessionId && isGrokSessionId(input.resumeSessionId)) {
+        args.push('--resume', input.resumeSessionId);
+    }
+    if (input.model) {
+        args.push('--model', input.model);
+    }
+    const effort = grokEffort(input.effortLevel);
+    if (effort) {
+        args.push('--reasoning-effort', effort);
+    }
+    // grok appends `--rules` on top of its base system prompt — same
+    // semantics as claude `--append-system-prompt`.
+    if (input.appendSystemPrompt && input.appendSystemPrompt.trim().length > 0) {
+        args.push('--rules', input.appendSystemPrompt.trim());
+    }
+    const childEnv = {
+        ...process.env,
+        ...sandboxHomeEnv(sandboxHome), // masks host ~/.claude.json MCPs (HOME; +USERPROFILE on win32)
+        GROK_HOME: realGrokHome(), // real account + live token refresh
+        TERM: 'dumb',
+    };
+    let proc;
+    try {
+        // npm .cmd shim → node script (win32); identity on POSIX. Both this
+        // resolution and spawn() itself can throw synchronously on Windows —
+        // fail the request cleanly instead of crashing the daemon.
+        const inv = (0, win_1.resolveCliInvocation)(bin, args);
+        proc = (0, child_process_1.spawn)(inv.file, inv.args, {
+            cwd: input.workingDirectory,
+            env: childEnv,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+    }
+    catch (err) {
+        const msg = err.message || String(err);
+        try {
+            fs.rmSync(sandboxHome, { recursive: true, force: true });
+        }
+        catch { }
+        const events = (0, events_1.bufferedEvents)([
+            { type: 'error', code: 'grok_spawn_failed', message: msg },
+            { type: 'turn_complete', stopReason: 'failed' },
+        ]);
+        return {
+            pid: undefined,
+            sessionId: null,
+            kill: () => { },
+            onEvent: events.onEvent,
+            onActivity: () => { },
+            done: Promise.resolve(-1),
+        };
+    }
+    const listeners = [];
+    const emit = (e) => { for (const l of listeners)
+        try {
+            l(e);
+        }
+        catch { } };
+    let sessionId = null;
+    let buffer = '';
+    // Coalesce assistant text. grok streams one `text` event PER TOKEN — a
+    // short reply is 30-40 events. Emitting each one as its own row floods
+    // the event table AND, because the daemon inserts events fire-and-forget,
+    // rapid per-token rows race and land out of order (the reply renders
+    // scrambled). Buffering deltas into a handful of well-spaced chunks fixes
+    // both: fewer rows, and enough spacing that inserts don't overlap.
+    const FLUSH_MS = 90;
+    const MAX_BUF = 320;
+    // Thinking flushes lazily (bigger chunks, longer window) — it's collapsed
+    // in the UI, so latency doesn't matter; fewer rows do.
+    const THINK_FLUSH_MS = 700;
+    const THINK_MAX_BUF = 1500;
+    let textBuf = '';
+    let thinkBuf = '';
+    let flushTimer = null;
+    let thinkTimer = null;
+    const flushThinking = () => {
+        if (thinkTimer) {
+            clearTimeout(thinkTimer);
+            thinkTimer = null;
+        }
+        if (thinkBuf) {
+            const delta = thinkBuf;
+            thinkBuf = '';
+            emit({ type: 'thinking', delta });
+        }
+    };
+    const flushText = () => {
+        if (flushTimer) {
+            clearTimeout(flushTimer);
+            flushTimer = null;
+        }
+        if (textBuf) {
+            const delta = textBuf;
+            textBuf = '';
+            emit({ type: 'assistant_text', delta });
+        }
+    };
+    const emitCoalesced = (e) => {
+        if (e.type === 'assistant_text') {
+            // Thoughts precede the text they produced — flush them first.
+            flushThinking();
+            textBuf += e.delta;
+            if (textBuf.length >= MAX_BUF)
+                flushText();
+            else if (!flushTimer)
+                flushTimer = setTimeout(flushText, FLUSH_MS);
+        }
+        else if (e.type === 'thinking') {
+            thinkBuf += e.delta;
+            if (thinkBuf.length >= THINK_MAX_BUF)
+                flushThinking();
+            else if (!thinkTimer)
+                thinkTimer = setTimeout(flushThinking, THINK_FLUSH_MS);
+        }
+        else {
+            // Any other event must appear AFTER the stream so far — flush both.
+            flushThinking();
+            flushText();
+            emit(e);
+        }
+    };
+    const activityListeners = [];
+    const touchActivity = () => { for (const l of activityListeners)
+        try {
+            l();
+        }
+        catch { } };
+    proc.stdout?.on('data', (chunk) => {
+        touchActivity();
+        buffer += chunk.toString('utf8');
+        let nl;
+        while ((nl = buffer.indexOf('\n')) !== -1) {
+            const raw = buffer.slice(0, nl).trim();
+            buffer = buffer.slice(nl + 1);
+            if (!raw)
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                continue;
+            }
+            if (!sessionId) {
+                const sid = parsed.sessionId ?? parsed.session_id;
+                if (typeof sid === 'string')
+                    sessionId = sid;
+            }
+            for (const ev of lineToEvents(parsed))
+                emitCoalesced(ev);
+        }
+    });
+    proc.stderr?.on('data', (chunk) => {
+        touchActivity();
+        const txt = chunk.toString('utf8').trim();
+        if (txt)
+            emit({ type: 'error', code: 'grok_stderr', message: txt.slice(0, 4096) });
+    });
+    const done = new Promise((resolve, reject) => {
+        proc.once('error', (err) => {
+            // Async spawn failure (ENOENT/EACCES from a stale cached binary path):
+            // the exit handler never fires, so clean up the sandbox HOME here too —
+            // otherwise it leaks (on Windows we copy files up to 8MB into it).
+            try {
+                fs.rmSync(sandboxHome, { recursive: true, force: true });
+            }
+            catch { }
+            reject(err);
+        });
+        proc.once('exit', (code) => {
+            flushThinking(); // emit buffered tails before we resolve
+            flushText();
+            try {
+                fs.rmSync(sandboxHome, { recursive: true, force: true });
+            }
+            catch { }
+            resolve(code ?? -1);
+        });
+    });
+    return {
+        pid: proc.pid,
+        get sessionId() { return sessionId; },
+        kill: () => { (0, win_1.killProcessTree)(proc); },
+        onEvent: (cb) => { listeners.push(cb); },
+        onActivity: (cb) => { activityListeners.push(cb); },
+        done,
+    };
+}

package/dist/guardrails.d.ts

@@ -0,0 +1,32 @@
+export interface GuardrailDef {
+    id: string;
+    name: string;
+    rule: string;
+    mode: 'fast' | 'runtime';
+    action: 'retry' | 'block' | 'flag';
+    max_retries: number;
+}
+export interface GuardrailVerdict {
+    id: string;
+    verdict: 'pass' | 'fail';
+    reasoning: string;
+    checker_error?: boolean;
+}
+export interface GuardrailIo {
+    loadGuardrails(): Promise<GuardrailDef[]>;
+    fetchOutput(): Promise<string | null>;
+    checkFast(output: string, defs: GuardrailDef[]): Promise<GuardrailVerdict[]>;
+    checkRuntime(output: string, def: GuardrailDef): Promise<GuardrailVerdict>;
+    /** Continuation turn on the same session. null = retry unavailable. */
+    runRetry(feedback: string): Promise<{
+        ok: boolean;
+        text: string;
+    } | null>;
+    setResult(meta: Record<string, unknown>, events: Array<Record<string, unknown>>): Promise<void>;
+    emit(type: string, payload: unknown): Promise<void>;
+}
+export declare function buildRetryFeedback(failures: Array<{
+    def: GuardrailDef;
+    verdict: GuardrailVerdict;
+}>): string;
+export declare function enforceGuardrails(io: GuardrailIo): Promise<void>;

package/dist/guardrails.js

@@ -0,0 +1,125 @@
+"use strict";
+// Guardrails — post-request checks an entity's output passes through before
+// the daemon writes the terminal `completed` status. Holding the terminal
+// status is the whole enforcement mechanism: every delivery path (bot-egress,
+// flows resume, chatflows queue promotion) triggers on terminal status, so
+// nothing is delivered until enforceGuardrails resolves.
+//
+// The state machine is pure over an injected IO surface (GuardrailIo) so it
+// is unit-testable without a network; session-runner.ts supplies the real IO
+// (RPCs + edge fn + retry spawn). Contract: enforceGuardrails NEVER throws
+// and fails OPEN — a broken checker degrades to `flag`, never to a blocked
+// or wedged reply.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildRetryFeedback = buildRetryFeedback;
+exports.enforceGuardrails = enforceGuardrails;
+// Global ceiling on revision rounds regardless of per-guardrail max_retries —
+// bounds worst-case latency added before delivery.
+const GLOBAL_MAX_RETRY_ROUNDS = 3;
+function buildRetryFeedback(failures) {
+    const lines = failures.map(f => `- "${f.def.name}": ${f.def.rule}${f.verdict.reasoning ? ` (violation: ${f.verdict.reasoning})` : ''}`);
+    return [
+        `Your previous response violated ${failures.length === 1 ? 'a guardrail' : `${failures.length} guardrails`}:`,
+        ...lines,
+        '',
+        'Revise your response so it fully complies with every guardrail above.',
+        'Reply ONLY with the corrected response — do not mention the guardrails, this revision process, or apologize for the previous version.',
+    ].join('\n');
+}
+async function judgeAll(io, output, defs) {
+    const fastDefs = defs.filter(d => d.mode === 'fast');
+    const runtimeDefs = defs.filter(d => d.mode === 'runtime');
+    const failOpen = (d, why) => ({ id: d.id, verdict: 'pass', reasoning: `checker_error: ${why}`, checker_error: true });
+    const fastP = fastDefs.length === 0 ? Promise.resolve([]) :
+        io.checkFast(output, fastDefs).then(vs => fastDefs.map(d => ({ def: d, verdict: vs.find(v => v.id === d.id) ?? failOpen(d, 'missing verdict') })), err => fastDefs.map(d => ({ def: d, verdict: failOpen(d, err.message) })));
+    const runtimeP = Promise.all(runtimeDefs.map(d => io.checkRuntime(output, d).then(v => ({ def: d, verdict: v }), err => ({ def: d, verdict: failOpen(d, err.message) }))));
+    const [fast, rt] = await Promise.all([fastP, runtimeP]);
+    return [...fast, ...rt];
+}
+async function enforceGuardrails(io) {
+    try {
+        const defs = await io.loadGuardrails();
+        if (!defs || defs.length === 0)
+            return;
+        void io.emit('guardrails_checking', { count: defs.length });
+        let output = (await io.fetchOutput())?.trim() ?? '';
+        if (!output)
+            return; // nothing produced → nothing to judge
+        const events = [];
+        let attempt = 0;
+        let retried = false;
+        let judged = await judgeAll(io, output, defs);
+        // Retry loop: only rules with action='retry' trigger a revision round.
+        for (;;) {
+            const retryable = judged.filter(j => j.verdict.verdict === 'fail' && !j.verdict.checker_error &&
+                j.def.action === 'retry' && attempt < j.def.max_retries);
+            if (retryable.length === 0 || attempt >= GLOBAL_MAX_RETRY_ROUNDS)
+                break;
+            for (const j of retryable) {
+                events.push({ guardrail_id: j.def.id, verdict: 'fail', action_taken: 'retried', attempt, reasoning: j.verdict.reasoning });
+            }
+            void io.emit('guardrail_retry', { attempt, guardrails: retryable.map(j => j.def.name) });
+            const res = await io.runRetry(buildRetryFeedback(retryable)).catch(() => null);
+            if (!res || !res.ok || !res.text.trim())
+                break; // retry unavailable/failed → resolve with what we have
+            output = res.text.trim();
+            retried = true;
+            attempt += 1;
+            judged = await judgeAll(io, output, defs);
+        }
+        // Final resolution over the last round of verdicts.
+        const blocked = [];
+        const flagged = [];
+        for (const j of judged) {
+            if (j.verdict.checker_error) {
+                flagged.push(j);
+                events.push({ guardrail_id: j.def.id, verdict: 'fail', action_taken: 'flagged', attempt, reasoning: j.verdict.reasoning });
+            }
+            else if (j.verdict.verdict === 'fail' && j.def.action === 'block') {
+                blocked.push(j);
+                events.push({ guardrail_id: j.def.id, verdict: 'fail', action_taken: 'blocked', attempt, reasoning: j.verdict.reasoning });
+            }
+            else if (j.verdict.verdict === 'fail') {
+                // action 'flag', or 'retry' with retries exhausted → deliver + warn
+                flagged.push(j);
+                events.push({ guardrail_id: j.def.id, verdict: 'fail', action_taken: 'flagged', attempt, reasoning: j.verdict.reasoning });
+            }
+            else {
+                events.push({ guardrail_id: j.def.id, verdict: 'pass', action_taken: 'passed', attempt, reasoning: j.verdict.reasoning || null });
+            }
+        }
+        const meta = {
+            checked: defs.length,
+            passed: defs.length - blocked.length - flagged.length,
+            attempt,
+        };
+        if (flagged.length)
+            meta.flags = flagged.map(j => j.def.name);
+        if (blocked.length) {
+            meta.blocked_by = blocked.map(j => j.def.name);
+            meta.original_text = output;
+            meta.final_text = `⛔ This response was blocked by the guardrail “${blocked[0].def.name}”.`;
+        }
+        else if (retried) {
+            // Aggregation would otherwise concatenate original + revision deltas —
+            // pin assistant_text to the revision the checks actually passed on.
+            meta.final_text = output;
+        }
+        await io.setResult(meta, events);
+        void io.emit('guardrails_result', {
+            checked: defs.length,
+            passed: meta.passed,
+            flagged: flagged.map(j => j.def.name),
+            blocked: blocked.map(j => j.def.name),
+            attempt,
+        });
+    }
+    catch (err) {
+        // Fail open — guardrails must never prevent completion/delivery.
+        try {
+            void io.emit('guardrails_result', { error: err.message });
+        }
+        catch { /* ignore */ }
+        console.error(`[guardrails] enforce failed (failing open): ${err.message}`);
+    }
+}

package/dist/hang-watchdog.d.ts

@@ -0,0 +1,17 @@
+export interface HangWatchdogOpts {
+    idleMs: number;
+    /** When provided, consulted on every (re)arm — lets the caller widen the
+     *  window mid-run (e.g. grok: once output has been seen, silent tool work
+     *  is expected and gets a longer leash than a dead-silent spawn). */
+    idleMsFn?: () => number;
+    onHang: () => void;
+    setTimer?: (fn: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+}
+export interface HangWatchdog {
+    /** Call on every agent event — rearms the idle timer. */
+    touch(): void;
+    /** Disarm permanently (run finished / terminal). */
+    stop(): void;
+}
+export declare function createHangWatchdog(opts: HangWatchdogOpts): HangWatchdog;