pi-grok-agent 0.1.0

package/dist/scripts/server.js

@@ -0,0 +1,486 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import { createConnection } from 'node:net';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { WebSocketServer, WebSocket } from 'ws';
+import { agentDir, defaultSecretFile, readConfig } from "../src/config.js";
+await mkdir(agentDir, { recursive: true, mode: 0o700 });
+if (!process.env.GROK_AGENT_SECRET) {
+    try {
+        await writeFile(defaultSecretFile, randomBytes(32).toString('hex') + '\n', { flag: 'wx', mode: 0o600 });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+}
+const config = await readConfig();
+const MCP_PATH = '/mcp/';
+const GATEWAY_ID_PREFIX = 'pi-gw:';
+const { ackMs: ACK_MS, policyMs: POLICY_MS, checkBudgetMs: CHECK_BUDGET_MS, dialogMs: DIALOG_MS } = config.guard;
+function gateKey(message) {
+    const p = message?.params ?? {};
+    if (message?.method === '_x.ai/hooks/run') {
+        const event = String(p.hookEventName ?? '');
+        if (event === 'stop')
+            return `stop:${p.sessionId ?? p.session_id ?? ''}`;
+        return p.toolUseId ? `${event}:${p.toolUseId}` : undefined;
+    }
+    if (message?.method === 'session/request_permission')
+        return p.toolCall?.toolCallId ? `perm:${p.toolCall.toolCallId}` : undefined;
+    if (message?.method === '_x.ai/ask_user_question')
+        return `ask:${p.toolCallId ?? p.tool_call_id ?? ''}`;
+    return undefined;
+}
+const guardStats = { gateDenied: 0, feedbackContinued: 0, permissionRejected: 0, lateAnswersDropped: 0 };
+class ReverseRequestGuard {
+    gates = new Map();
+    byKey = new Map();
+    reply;
+    constructor(reply) { this.reply = reply; }
+    get open() { let n = 0; for (const g of this.gates.values())
+        if (g.state === 'open')
+            n++; return n; }
+    watch(message) {
+        if (typeof message?.method !== 'string' || !('id' in message) || message.id === null)
+            return;
+        const id = JSON.stringify(message.id);
+        const reply = (result) => this.reply({ jsonrpc: '2.0', id: message.id, result });
+        let gate;
+        if (message.method === '_x.ai/hooks/run') {
+            const event = String(message.params?.hookEventName ?? '');
+            if (event === 'pre_tool_use')
+                gate = { kind: 'gate', state: 'open', answer: (why) => { guardStats.gateDenied++; reply({ decision: 'deny', reason: `Denied by the Pi gateway: ${why}.` }); } };
+            else if (event === 'stop' || event === 'post_tool_use')
+                gate = { kind: 'feedback', state: 'open', answer: () => { guardStats.feedbackContinued++; reply({ decision: 'continue' }); } };
+        }
+        else if (message.method === 'session/request_permission') {
+            const options = message.params?.options ?? [];
+            const reject = options.find((o) => o?.kind === 'reject_once') ?? options.find((o) => String(o?.kind).startsWith('reject'));
+            gate = { kind: 'permission', state: 'open', answer: () => { guardStats.permissionRejected++; reply(reject ? { outcome: { outcome: 'selected', optionId: reject.optionId } } : { outcome: { outcome: 'cancelled' } }); } };
+        }
+        else if (message.method === '_x.ai/ask_user_question') {
+            gate = { kind: 'permission', state: 'open', answer: () => { guardStats.permissionRejected++; reply({ outcome: 'cancelled' }); } };
+        }
+        if (!gate)
+            return;
+        gate.key = gateKey(message);
+        this.gates.set(id, gate);
+        if (gate.key)
+            this.byKey.set(gate.key, id);
+        this.arm(id, gate, ACK_MS, `Pi did not acknowledge within ${ACK_MS / 1000}s`);
+    }
+    ack(params) {
+        const id = this.byKey.get(String(params?.key ?? ''));
+        const gate = id ? this.gates.get(id) : undefined;
+        if (!id || !gate || gate.state !== 'open')
+            return;
+        if (params?.dialog)
+            this.arm(id, gate, DIALOG_MS, `no answer to the dialog within ${DIALOG_MS / 60_000} min`);
+        else if (params?.check)
+            this.arm(id, gate, CHECK_BUDGET_MS, `check exceeded ${CHECK_BUDGET_MS / 1000}s`);
+        else
+            this.arm(id, gate, POLICY_MS, `Pi policy did not answer within ${POLICY_MS / 1000}s`);
+    }
+    settle(message) {
+        if (!message || !('id' in message) || !('result' in message || 'error' in message))
+            return 'forward';
+        const id = JSON.stringify(message.id);
+        const gate = this.gates.get(id);
+        if (!gate)
+            return 'forward';
+        this.forget(id, gate);
+        if (gate.state === 'open')
+            return 'forward';
+        guardStats.lateAnswersDropped++;
+        return 'drop';
+    }
+    close(why) {
+        for (const [id, gate] of this.gates)
+            if (gate.state === 'open') {
+                clearTimeout(gate.timer);
+                gate.state = 'answered';
+                gate.answer(why);
+                this.forget(id, gate);
+            }
+    }
+    arm(id, gate, ms, why) {
+        clearTimeout(gate.timer);
+        gate.timer = setTimeout(() => { if (this.gates.get(id) === gate && gate.state === 'open') {
+            gate.state = 'answered';
+            gate.answer(why);
+        } }, ms);
+    }
+    forget(id, gate) {
+        clearTimeout(gate.timer);
+        this.gates.delete(id);
+        if (gate.key && this.byKey.get(gate.key) === id)
+            this.byKey.delete(gate.key);
+    }
+}
+const relays = new Map();
+let gatewayIds = 0;
+function mcpTokenFrom(value) {
+    try {
+        const path = new URL(String(value)).pathname;
+        if (path.startsWith(MCP_PATH))
+            return path.slice(MCP_PATH.length);
+    }
+    catch { }
+    return undefined;
+}
+function registerMcpTokens(relay, message) {
+    if (message?.method !== 'session/new' && message?.method !== 'session/load')
+        return;
+    for (const server of message.params?.mcpServers ?? []) {
+        const token = mcpTokenFrom(server?.url);
+        if (!token)
+            continue;
+        const previous = relays.get(token);
+        if (previous && previous !== relay)
+            previous.tokens.delete(token);
+        relays.set(token, relay);
+        relay.tokens.add(token);
+    }
+}
+function endJson(res, status, body, headers = {}) {
+    const text = body === undefined ? '' : JSON.stringify(body);
+    res.writeHead(status, { 'content-type': 'application/json', 'content-length': Buffer.byteLength(text), ...headers });
+    res.end(text);
+}
+function handleMcpHttp(req, res) {
+    const path = new URL(req.url ?? '/', 'http://localhost').pathname;
+    if (!path.startsWith(MCP_PATH)) {
+        endJson(res, 404, { error: 'not found' });
+        return;
+    }
+    const token = path.slice(MCP_PATH.length);
+    if (req.method !== 'POST') {
+        res.writeHead(405, { allow: 'POST' });
+        res.end();
+        return;
+    }
+    const relay = relays.get(token);
+    if (!relay || relay.socket.readyState !== WebSocket.OPEN) {
+        endJson(res, 404, { error: 'unknown MCP token' });
+        return;
+    }
+    const chunks = [];
+    let size = 0;
+    req.on('data', (c) => { size += c.length; if (size > 16 * 1024 * 1024) {
+        req.destroy();
+        return;
+    } chunks.push(c); });
+    req.on('end', () => {
+        let message;
+        try {
+            message = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        }
+        catch {
+            endJson(res, 400, { error: 'invalid JSON' });
+            return;
+        }
+        if (!message || typeof message !== 'object' || typeof message.method !== 'string') {
+            endJson(res, 400, { error: 'expected a JSON-RPC message' });
+            return;
+        }
+        if (!('id' in message) || message.id === null) {
+            res.writeHead(202);
+            res.end();
+            return;
+        }
+        const id = `${GATEWAY_ID_PREFIX}${++gatewayIds}`;
+        relay.pending.set(id, res);
+        res.on('close', () => relay.pending.delete(id));
+        relay.socket.send(JSON.stringify({ jsonrpc: '2.0', id, method: '_x.ai/mcp/sdk_call', params: { serverId: token, message } }), (error) => {
+            if (error && relay.pending.delete(id))
+                endJson(res, 502, { jsonrpc: '2.0', id: message.id, error: { code: -32000, message: 'Pi connection send failed' } });
+        });
+    });
+}
+function answerFromPi(relay, message) {
+    if (typeof message?.id !== 'string' || !message.id.startsWith(GATEWAY_ID_PREFIX) || !('result' in message || 'error' in message))
+        return false;
+    const res = relay.pending.get(message.id);
+    relay.pending.delete(message.id);
+    if (!res)
+        return true;
+    if ('error' in message)
+        endJson(res, 200, { jsonrpc: '2.0', id: null, error: message.error });
+    else
+        endJson(res, 200, message.result);
+    return true;
+}
+const url = new URL(config.url);
+if (url.protocol !== 'ws:' || !['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname) || url.pathname !== '/ws') {
+    throw new Error('The local launcher requires a loopback ws:// endpoint ending in /ws.');
+}
+const leaderSocket = process.env.PI_GROK_LEADER_SOCKET || join(homedir(), '.grok', 'pi', 'leader.sock');
+await mkdir(join(homedir(), '.grok', 'pi'), { recursive: true, mode: 0o700 });
+const grokBinary = process.env.PI_GROK_BINARY || 'grok';
+const proxies = new Set();
+let gateway;
+let httpServer;
+let stopping = false;
+let leader;
+let leaderRestarts = 0;
+const leaderLock = leaderSocket.replace(/\.sock$/, '') + '.lock';
+function socketAnswers() {
+    return new Promise((resolve) => { const s = createConnection(leaderSocket); s.once('connect', () => { s.destroy(); resolve(true); }); s.once('error', () => { s.destroy(); resolve(false); }); });
+}
+async function existingLeaderPid() {
+    try {
+        const pid = Number((await readFile(leaderLock, 'utf8')).trim());
+        if (!Number.isInteger(pid) || pid <= 0)
+            return undefined;
+        try {
+            process.kill(pid, 0);
+        }
+        catch {
+            return undefined;
+        }
+        return (await socketAnswers()) ? pid : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function leaderAlive() { return !!leader; }
+function stopLeader() {
+    if (!leader)
+        return;
+    if ('adopted' in leader) {
+        try {
+            process.kill(leader.pid, 'SIGTERM');
+        }
+        catch { }
+        leader = undefined;
+        return;
+    }
+    stopChild(leader);
+}
+function watchAdopted(pid) {
+    const timer = setInterval(() => {
+        if (leader && 'adopted' in leader && leader.pid === pid) {
+            try {
+                process.kill(pid, 0);
+                return;
+            }
+            catch {
+                leader = undefined;
+                clearInterval(timer);
+                if (!stopping)
+                    void onLeaderGone(`adopted leader ${pid} exited`);
+            }
+        }
+        else
+            clearInterval(timer);
+    }, 1000);
+    timer.unref();
+}
+const LEADER_ARGS = ['--permission-mode', 'default', 'agent', 'leader', '--no-exit-on-disconnect', '--relay-on-demand', '--no-auto-update', '--leader-socket', leaderSocket];
+function waitForSocket(child, timeoutMs = 30_000) {
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => { cleanup(); reject(new Error('Grok leader socket startup timed out.')); }, timeoutMs);
+        const failed = () => { cleanup(); reject(new Error('Grok leader exited before startup.')); };
+        const interval = setInterval(() => {
+            const socket = createConnection(leaderSocket);
+            socket.once('connect', () => { socket.destroy(); cleanup(); resolve(); });
+            socket.once('error', () => socket.destroy());
+        }, 100);
+        const cleanup = () => { clearTimeout(timeout); clearInterval(interval); child.off('exit', failed); child.off('error', failed); };
+        child.once('exit', failed);
+        child.once('error', failed);
+        if (stopping)
+            failed();
+    });
+}
+async function startLeader() {
+    const existing = await existingLeaderPid();
+    if (existing) {
+        leader = { pid: existing, adopted: true };
+        watchAdopted(existing);
+        console.error(`Adopted leader ${existing} already on ${leaderSocket}.`);
+        return;
+    }
+    try {
+        const pid = Number((await readFile(leaderLock, 'utf8')).trim());
+        process.kill(pid, 0);
+    }
+    catch {
+        await rm(leaderSocket, { force: true });
+    }
+    const child = spawn(grokBinary, LEADER_ARGS, { stdio: ['ignore', 'inherit', 'inherit'] });
+    leader = child;
+    child.once('exit', (code, sig) => {
+        if (leader !== child)
+            return;
+        leader = undefined;
+        if (stopping)
+            return;
+        void onLeaderGone(`exited (${code ?? sig})`);
+    });
+    child.once('error', (error) => { if (leader === child) {
+        leader = undefined;
+        if (!stopping)
+            void onLeaderGone(error.message);
+    } });
+    await waitForSocket(child);
+}
+async function onLeaderGone(why) {
+    leaderRestarts++;
+    const delay = Math.min(30_000, 1000 * 2 ** Math.min(leaderRestarts - 1, 5));
+    console.error(`Grok leader ${why}; dropping ${proxies.size} bridge(s), ensuring a leader in ${delay / 1000}s (restart #${leaderRestarts}).`);
+    for (const proxy of proxies)
+        stopChild(proxy);
+    await new Promise((r) => setTimeout(r, delay));
+    if (stopping)
+        return;
+    try {
+        await startLeader();
+        console.error(leader && 'adopted' in leader ? 'Grok leader adopted.' : 'Grok leader respawned.');
+        if (leaderRestarts > 0)
+            setTimeout(() => { leaderRestarts = Math.max(0, leaderRestarts - 1); }, 120_000).unref();
+    }
+    catch (error) {
+        console.error(`Grok leader respawn failed: ${error instanceof Error ? error.message : String(error)}`);
+        void onLeaderGone('respawn failed');
+    }
+}
+function stopChild(child) {
+    if (child.exitCode !== null || child.signalCode !== null)
+        return;
+    child.kill('SIGTERM');
+    const kill = setTimeout(() => { if (child.exitCode === null && child.signalCode === null)
+        child.kill('SIGKILL'); }, 2500);
+    kill.unref();
+    child.once('exit', () => clearTimeout(kill));
+}
+function shutdown(error) {
+    if (stopping)
+        return;
+    stopping = true;
+    if (error) {
+        console.error(error.message);
+        process.exitCode = 1;
+    }
+    for (const socket of gateway?.clients ?? [])
+        socket.terminate();
+    gateway?.close();
+    httpServer?.close();
+    for (const proxy of proxies)
+        stopChild(proxy);
+    stopLeader();
+}
+for (const signal of ['SIGTERM', 'SIGINT'])
+    process.on(signal, () => shutdown());
+try {
+    httpServer = createServer(handleMcpHttp);
+    httpServer.requestTimeout = 0;
+    httpServer.headersTimeout = 60_000;
+    gateway = new WebSocketServer({
+        server: httpServer, path: '/ws', maxPayload: 16 * 1024 * 1024,
+        verifyClient: ({ req }) => req.headers.authorization === `Bearer ${config.secret}`,
+    });
+    gateway.on('error', (error) => shutdown(error));
+    gateway.on('connection', async (socket) => {
+        for (let i = 0; !leaderAlive() && !stopping && i < 100; i++)
+            await new Promise((r) => setTimeout(r, 300));
+        if (!leaderAlive() || stopping) {
+            socket.close(1013, 'Grok leader unavailable');
+            return;
+        }
+        const proxy = spawn(grokBinary, ['--permission-mode', 'default', 'agent', '--leader', 'stdio', '--leader-socket', leaderSocket], { stdio: ['pipe', 'pipe', 'inherit'] });
+        proxies.add(proxy);
+        const relay = { socket, pending: new Map(), tokens: new Set(), guard: new ReverseRequestGuard((message) => proxy.stdin.write(JSON.stringify(message) + '\n')) };
+        let buffer = '';
+        const fail = () => { if (socket.readyState === WebSocket.OPEN)
+            socket.close(1011, 'Grok leader client disconnected'); stopChild(proxy); };
+        proxy.stdout.setEncoding('utf8');
+        proxy.stdout.on('data', (chunk) => {
+            buffer += chunk;
+            if (buffer.length > 16 * 1024 * 1024 || socket.bufferedAmount > 16 * 1024 * 1024) {
+                fail();
+                return;
+            }
+            for (;;) {
+                const end = buffer.indexOf('\n');
+                if (end < 0)
+                    break;
+                const line = buffer.slice(0, end).replace(/\r$/, '');
+                buffer = buffer.slice(end + 1);
+                if (!line)
+                    continue;
+                try {
+                    relay.guard.watch(JSON.parse(line));
+                }
+                catch { }
+                if (socket.readyState === WebSocket.OPEN)
+                    socket.send(line, (error) => { if (error)
+                        fail(); });
+            }
+        });
+        socket.on('message', (data) => {
+            const text = data.toString().replace(/[\r\n]+$/, '');
+            if (!text || text === 'ping')
+                return;
+            let message;
+            try {
+                message = JSON.parse(text);
+            }
+            catch {
+                message = undefined;
+            }
+            if (message && answerFromPi(relay, message))
+                return;
+            if (message?.method === 'pi/gate-ack') {
+                relay.guard.ack(message.params);
+                return;
+            }
+            if (message) {
+                if (relay.guard.settle(message) === 'drop')
+                    return;
+                registerMcpTokens(relay, message);
+            }
+            if (!proxy.stdin.write(text + '\n'))
+                socket.pause();
+        });
+        proxy.stdin.on('drain', () => socket.resume());
+        proxy.stdin.on('error', fail);
+        proxy.on('error', fail);
+        proxy.once('exit', () => { proxies.delete(proxy); if (socket.readyState === WebSocket.OPEN)
+            socket.close(1011, 'Grok leader client exited'); });
+        socket.on('error', () => stopChild(proxy));
+        socket.once('close', () => {
+            const hadGates = relay.guard.open > 0;
+            relay.guard.close('Pi connection closed');
+            if (hadGates)
+                setTimeout(() => stopChild(proxy), 500);
+            else
+                stopChild(proxy);
+            for (const token of relay.tokens)
+                if (relays.get(token) === relay)
+                    relays.delete(token);
+            for (const [id, res] of relay.pending) {
+                relay.pending.delete(id);
+                endJson(res, 502, { jsonrpc: '2.0', id: null, error: { code: -32000, message: 'Pi connection closed' } });
+            }
+        });
+    });
+    await new Promise((resolve, reject) => {
+        httpServer.once('error', reject);
+        httpServer.listen(Number(url.port || 80), url.hostname === '[::1]' ? '::1' : url.hostname, () => { httpServer.off('error', reject); resolve(); });
+    });
+    httpServer.on('error', (error) => shutdown(error));
+    await startLeader();
+    if (stopping)
+        throw new Error('Grok gateway startup cancelled.');
+    console.log(`Grok WebSocket ACP ready at ${url}; MCP relay at ${url.origin.replace(/^ws/, 'http')}${MCP_PATH}<token>; leader socket ${leaderSocket}; binary ${grokBinary}`);
+}
+catch (error) {
+    shutdown(error instanceof Error ? error : new Error(String(error)));
+}

package/dist/src/client.js

@@ -0,0 +1,82 @@
+import WebSocket from 'ws';
+export function validateEndpoint(value) {
+    const url = new URL(value);
+    if (!['ws:', 'wss:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+        throw new Error('Use a ws:// or wss:// endpoint without credentials, query, or fragment.');
+    }
+    if (url.protocol === 'ws:' && !['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)) {
+        throw new Error('Use wss:// for a non-loopback server.');
+    }
+    return url.toString();
+}
+export async function openSocket(options, signal) {
+    signal?.throwIfAborted();
+    const url = validateEndpoint(options.url);
+    if (!options.secret.trim())
+        throw new Error('Grok WebSocket secret is missing.');
+    const socket = new WebSocket(url, {
+        headers: { Authorization: `Bearer ${options.secret}` },
+        handshakeTimeout: 10_000,
+        maxPayload: 16 * 1024 * 1024,
+        followRedirects: false,
+    });
+    let input;
+    let ended = false;
+    const end = (error) => {
+        if (ended)
+            return;
+        ended = true;
+        if (error)
+            input.error(error);
+        else
+            input.close();
+    };
+    const readable = new ReadableStream({
+        start(controller) { input = controller; },
+        cancel() { ended = true; socket.terminate(); }
+    });
+    socket.on('message', (data) => {
+        if (ended)
+            return;
+        try {
+            input.enqueue(JSON.parse(data.toString()));
+        }
+        catch {
+            end(new Error('Invalid JSON from Grok WebSocket.'));
+            socket.terminate();
+        }
+    });
+    let resolveClosed;
+    const closed = new Promise((resolve) => { resolveClosed = resolve; });
+    socket.on('close', () => { end(); resolveClosed(); });
+    socket.on('error', () => end(new Error('Grok WebSocket connection failed. Check the endpoint, server, and secret.')));
+    await new Promise((resolve, reject) => {
+        const cleanup = () => { signal?.removeEventListener('abort', abort); socket.off('open', opened); socket.off('error', failed); socket.off('close', closed); };
+        const opened = () => { cleanup(); resolve(); };
+        const failed = () => { cleanup(); socket.terminate(); reject(new Error('Grok WebSocket handshake failed. Check the endpoint, server, and secret.')); };
+        const closed = () => { cleanup(); reject(new Error('Grok WebSocket closed during connection.')); };
+        const abort = () => { cleanup(); socket.terminate(); reject(new Error('Grok connection cancelled.')); };
+        socket.once('open', opened);
+        socket.once('error', failed);
+        socket.once('close', closed);
+        signal?.addEventListener('abort', abort, { once: true });
+        if (signal?.aborted)
+            abort();
+    });
+    return {
+        stream: {
+            readable,
+            writable: new WritableStream({
+                write(message) {
+                    return new Promise((resolve, reject) => {
+                        socket.send(JSON.stringify(message), (error) => error ? reject(new Error('Grok WebSocket send failed.')) : resolve());
+                    });
+                },
+                close() { socket.close(); },
+                abort() { socket.terminate(); },
+            }),
+        },
+        close() { socket.terminate(); },
+        closed,
+    };
+}

package/dist/src/config.js

@@ -0,0 +1,89 @@
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+import { validateEndpoint } from "./client.js";
+export const agentDir = process.env.PI_CODING_AGENT_DIR || join(homedir(), '.pi', 'agent');
+export const configPath = join(agentDir, 'grok-ws.json');
+export const defaultSecretFile = join(agentDir, 'grok-ws.secret');
+export const PI_CORE_TOOLS = new Set(['read', 'bash', 'edit', 'write', 'grep', 'find', 'ls']);
+export const GROK_HOOK_CAP_MS = 600_000;
+export const GATE_REGISTRATION_MS = 30_000;
+const GUARD_DEFAULTS = { ackMs: 5_000, policyMs: 15_000, checkBudgetMs: 590_000, dialogMs: 600_000 };
+export function resolveGuard(settings, env = process.env) {
+    const pick = (key, envName) => {
+        const raw = env[envName] ?? settings?.[key];
+        if (raw === undefined || raw === '')
+            return GUARD_DEFAULTS[key];
+        const n = Number(raw);
+        if (!Number.isFinite(n) || n <= 0)
+            throw new Error(`guard.${key} must be a positive number of milliseconds (got ${String(raw)}).`);
+        return Math.floor(n);
+    };
+    const guard = { ackMs: pick('ackMs', 'PI_GROK_ACK_MS'), policyMs: pick('policyMs', 'PI_GROK_POLICY_MS'), checkBudgetMs: pick('checkBudgetMs', 'PI_GROK_CHECK_BUDGET_MS'), dialogMs: pick('dialogMs', 'PI_GROK_DIALOG_MS') };
+    if (guard.ackMs >= GATE_REGISTRATION_MS || guard.policyMs >= GATE_REGISTRATION_MS)
+        throw new Error('guard.ackMs and guard.policyMs must be below the pre_tool_use registration deadline (' + GATE_REGISTRATION_MS + ' ms).');
+    if (guard.checkBudgetMs >= GROK_HOOK_CAP_MS)
+        throw new Error('guard.checkBudgetMs must be below Grok\'s hook cap (' + GROK_HOOK_CAP_MS + ' ms).');
+    if (guard.ackMs > guard.policyMs)
+        throw new Error('guard.ackMs must not exceed guard.policyMs.');
+    return guard;
+}
+export async function readSecretFile(secretFile) {
+    try {
+        return (await readFile(secretFile, 'utf8')).trim();
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+export async function readConfig() {
+    let settings = {};
+    try {
+        settings = JSON.parse(await readFile(configPath, 'utf8'));
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const url = validateEndpoint(process.env.GROK_ACP_URL || settings.url || 'ws://127.0.0.1:2419/ws');
+    const configuredFile = settings.secretFile || defaultSecretFile;
+    const secretFile = configuredFile.startsWith('~/') ? join(homedir(), configuredFile.slice(2)) : configuredFile;
+    if (!isAbsolute(secretFile))
+        throw new Error('grok-ws secretFile must be absolute or start with ~/.');
+    const secret = process.env.GROK_AGENT_SECRET || (await readSecretFile(secretFile)) || '';
+    const piTools = process.env.PI_GROK_PI_TOOLS ? parsePolicy(process.env.PI_GROK_PI_TOOLS) : settings.piTools ?? 'extensions';
+    const hooks = { ...settings.hooks };
+    if (process.env.PI_GROK_STOP_CHECK)
+        hooks.stopCheck = process.env.PI_GROK_STOP_CHECK;
+    if (process.env.PI_GROK_POST_EDIT_CHECK)
+        hooks.postEditCheck = process.env.PI_GROK_POST_EDIT_CHECK;
+    if (process.env.PI_GROK_DENY_TOOLS)
+        hooks.denyGrokTools = process.env.PI_GROK_DENY_TOOLS.split(',').map((s) => s.trim()).filter(Boolean);
+    const headlessPermissions = process.env.PI_GROK_HEADLESS_PERMISSIONS ?? settings.headlessPermissions ?? 'dialog';
+    if (!['dialog', 'deny', 'reads', 'allow'].includes(headlessPermissions))
+        throw new Error(`headlessPermissions must be dialog, deny, reads, or allow (got ${headlessPermissions}).`);
+    const guard = resolveGuard(settings.guard);
+    const mediaDir = process.env.PI_GROK_MEDIA_DIR ?? settings.mediaDir ?? '.pi/grok-images';
+    const grokMode = process.env.PI_GROK_GROK_MODE ?? settings.grokMode ?? 'default';
+    if (!['default', 'auto', 'yolo'].includes(grokMode))
+        throw new Error(`grokMode must be default, auto, or yolo (got ${grokMode}).`);
+    const autoStartGateway = process.env.PI_GROK_AUTOSTART ? !['0', 'false', 'no', 'off'].includes(process.env.PI_GROK_AUTOSTART.toLowerCase()) : settings.autoStartGateway ?? true;
+    return { url, secret, secretFile, piTools, hooks, headlessPermissions, guard, mediaDir, grokMode, autoStartGateway };
+}
+function parsePolicy(value) {
+    if (value === 'none' || value === 'extensions' || value === 'all')
+        return value;
+    return value.split(',').map((s) => s.trim()).filter(Boolean);
+}
+export function selectPiTools(tools, policy) {
+    if (policy === 'none')
+        return [];
+    if (policy === 'all')
+        return tools;
+    if (policy === 'extensions')
+        return tools.filter((t) => !PI_CORE_TOOLS.has(t.name));
+    const allowed = new Set(policy);
+    return tools.filter((t) => allowed.has(t.name));
+}