@pugi/cli 0.1.0-beta.12 → 0.1.0-beta.14

package/dist/core/mcp/server.js

@@ -0,0 +1,397 @@
+import { EventEmitter } from 'node:events';
+/**
+ * Pugi MCP server (β4 M2) — exposes Pugi's native tool surface to other
+ * agents (Claude Code, OpenCode, Codex CLI, any client that speaks
+ * MCP).
+ *
+ * Transport-agnostic core. The stdio entry-point lives at the bottom of
+ * this module (`serveStdio`); the HTTP+SSE wrapper lives in
+ * `./http-server.ts` and feeds the same core via the synchronous
+ * `handleMessage` entry-point.
+ *
+ * Spec: https://modelcontextprotocol.io/specification (2024-11-05).
+ *
+ * Methods implemented:
+ *   - `initialize`               -> protocol handshake, server capabilities
+ *   - `notifications/initialized` -> ack, no-op
+ *   - `tools/list`               -> Pugi tool schemas
+ *   - `tools/call`               -> dispatch to the underlying executor
+ *   - `ping`                     -> liveness, returns `{}` (some MCP clients
+ *                                   poll this on a HTTP transport)
+ *
+ * NOT yet implemented (deferred — these are not on the β4 acceptance
+ * surface):
+ *   - `resources/*`              — file resource browser
+ *   - `prompts/*`                — server-supplied prompts
+ *   - `sampling/*`               — agent sampling callbacks
+ *   - `notifications/cancelled`  — client-side cancellation (we honour
+ *                                   the AbortSignal passed at construction
+ *                                   instead)
+ *
+ * Why hand-rolled instead of `@modelcontextprotocol/sdk`:
+ *   - The SDK ships every transport (stdio, HTTP, WebSocket, SSE) and
+ *     drags in a 3 MB compressed dependency footprint. Pugi-CLI ships as
+ *     `npm i -g pugi` and every transitive dep is supply-chain risk.
+ *   - The core JSON-RPC envelope is <500 LOC and we already maintain the
+ *     client-side variant in `./client.ts` — keeping the server matching
+ *     hand-roll lets a code reviewer hold both sides of the wire in one
+ *     head.
+ *   - Pugi-specific extensions (permission FSM hooks on `tools/call`,
+ *     bearer-auth attestation on HTTP, scope-limited tool filtering for
+ *     paired-agent worktrees) drop in cleanly because we own the
+ *     dispatch table.
+ */
+/* ---------- protocol types (mirror client.ts conventions) ----------------- */
+export const PUGI_MCP_PROTOCOL_VERSION = '2024-11-05';
+export const PUGI_MCP_SERVER_NAME = 'pugi';
+export const PUGI_MCP_SERVER_VERSION = '0.1.0';
+/** JSON-RPC standard error codes used by the server. */
+export const MCP_ERROR_CODES = Object.freeze({
+    PARSE_ERROR: -32700,
+    INVALID_REQUEST: -32600,
+    METHOD_NOT_FOUND: -32601,
+    INVALID_PARAMS: -32602,
+    INTERNAL_ERROR: -32603,
+    /**
+     * Pugi-specific: operator-side permission gate refused this tool call.
+     * Distinct from generic INTERNAL_ERROR so MCP clients can surface a
+     * "permission denied" status to their user.
+     */
+    PERMISSION_REFUSED: -32001,
+    /**
+     * Pugi-specific: HTTP transport saw an invalid or missing bearer
+     * token. Stdio transport never emits this code (no auth).
+     */
+    AUTH_REQUIRED: -32002,
+});
+export class McpServerToolError extends Error {
+    code;
+    constructor(message, code = MCP_ERROR_CODES.INTERNAL_ERROR) {
+        super(message);
+        this.name = 'McpServerToolError';
+        this.code = code;
+    }
+}
+/**
+ * Build a Pugi MCP server bound to a fixed tool surface. Stateless
+ * between requests — the same instance can drive many concurrent stdio
+ * connections (one per child process) without cross-talk.
+ */
+export function createPugiMcpServer(options) {
+    const events = new EventEmitter();
+    // Build a lookup by name once at construction. Duplicate names are a
+    // programmer error and we throw eagerly so the bug surfaces in the
+    // boot path, not at the first `tools/call`.
+    const byName = new Map();
+    for (const tool of options.tools) {
+        // Reject names that would re-encode as MCP `mcp__<server>__<tool>`
+        // false-positively on the consumer side — a server name containing
+        // `__` makes parseMcpToolName misalign the split. We surface the
+        // bug here, not at first dispatch. β4 r1 P2.
+        if (tool.name.includes('__')) {
+            throw new Error(`pugi mcp server: tool name "${tool.name}" must not contain "__" (collides with mcp__<server>__<tool> naming)`);
+        }
+        if (byName.has(tool.name)) {
+            throw new Error(`pugi mcp server: duplicate tool name "${tool.name}" — every tool in the surface must be unique`);
+        }
+        byName.set(tool.name, tool);
+    }
+    const tools = Array.from(byName.values()).sort((a, b) => a.name.localeCompare(b.name));
+    const log = options.log ?? (() => { });
+    if (typeof options.permissionGate !== 'function') {
+        throw new Error('pugi mcp server: options.permissionGate is required (β4 r1 P1 #2 — no implicit allow-all default)');
+    }
+    const permissionGate = options.permissionGate;
+    const requireInitialized = options.requireInitialized !== false;
+    let initialized = false;
+    async function dispatch(method, params, clientId) {
+        switch (method) {
+            case 'initialize': {
+                // The MCP spec permits multiple `initialize` calls before
+                // `notifications/initialized` settles the handshake — we just
+                // re-affirm. After init, repeated `initialize` is harmless on
+                // our side and lets the client recover from a state desync.
+                return {
+                    protocolVersion: PUGI_MCP_PROTOCOL_VERSION,
+                    capabilities: {
+                        tools: { listChanged: false },
+                    },
+                    serverInfo: {
+                        name: PUGI_MCP_SERVER_NAME,
+                        version: PUGI_MCP_SERVER_VERSION,
+                    },
+                };
+            }
+            case 'ping': {
+                return {};
+            }
+            case 'tools/list': {
+                return {
+                    tools: tools.map((tool) => ({
+                        name: tool.name,
+                        description: tool.description,
+                        inputSchema: tool.inputSchema,
+                    })),
+                };
+            }
+            case 'tools/call': {
+                if (options.signal?.aborted) {
+                    throw new McpServerToolError('server shutting down', MCP_ERROR_CODES.INTERNAL_ERROR);
+                }
+                // β4 r1 P2 — require `initialize` + `notifications/initialized`
+                // handshake first. Without this, an attacker with the bearer
+                // token can dispatch a `tools/call` without ever advertising
+                // client capabilities; the MCP spec mandates the handshake.
+                if (requireInitialized && !initialized) {
+                    throw new McpServerToolError('tools/call: MCP handshake not complete — send `initialize` + `notifications/initialized` first', MCP_ERROR_CODES.INVALID_REQUEST);
+                }
+                const p = (params ?? {});
+                const rawName = p['name'];
+                if (typeof rawName !== 'string') {
+                    throw new McpServerToolError('tools/call: params.name (string) is required', MCP_ERROR_CODES.INVALID_PARAMS);
+                }
+                // Trim whitespace-only names so the lookup fails fast with
+                // METHOD_NOT_FOUND instead of silently matching an entry that
+                // happens to share leading/trailing whitespace. β4 r1 P2.
+                const toolName = rawName.trim();
+                if (toolName.length === 0) {
+                    throw new McpServerToolError('tools/call: params.name (string) is required', MCP_ERROR_CODES.INVALID_PARAMS);
+                }
+                const tool = byName.get(toolName);
+                if (!tool) {
+                    throw new McpServerToolError(`tools/call: tool "${toolName}" is not registered`, MCP_ERROR_CODES.METHOD_NOT_FOUND);
+                }
+                const rawArgs = p['arguments'];
+                let args;
+                if (rawArgs === undefined || rawArgs === null) {
+                    args = {};
+                }
+                else if (typeof rawArgs === 'object' && !Array.isArray(rawArgs)) {
+                    args = rawArgs;
+                }
+                else {
+                    throw new McpServerToolError('tools/call: params.arguments must be a JSON object', MCP_ERROR_CODES.INVALID_PARAMS);
+                }
+                const allowed = await permissionGate({
+                    tool,
+                    arguments: args,
+                    ...(clientId ? { clientId } : {}),
+                });
+                if (!allowed) {
+                    log('warn', `permission refused: ${tool.name}`);
+                    throw new McpServerToolError(`permission refused by operator: ${tool.name}`, MCP_ERROR_CODES.PERMISSION_REFUSED);
+                }
+                // Stamp clientId on emitted events so the HTTP transport can
+                // route them to the originating SSE listener instead of
+                // broadcasting to every bearer-holder (β4 r1 P1 #5).
+                events.emit('tool_call', {
+                    name: tool.name,
+                    args,
+                    ...(clientId ? { clientId } : {}),
+                });
+                try {
+                    const text = await tool.execute(args);
+                    events.emit('tool_result', {
+                        name: tool.name,
+                        ok: true,
+                        summary: text.slice(0, 200),
+                        ...(clientId ? { clientId } : {}),
+                    });
+                    return {
+                        content: [{ type: 'text', text }],
+                        isError: false,
+                    };
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    events.emit('tool_result', {
+                        name: tool.name,
+                        ok: false,
+                        summary: message.slice(0, 200),
+                        ...(clientId ? { clientId } : {}),
+                    });
+                    // Tool-level failures surface as MCP `isError: true` content —
+                    // the client knows the call ran but failed, distinct from a
+                    // protocol-level error (bad tool name, malformed params).
+                    return {
+                        content: [{ type: 'text', text: message }],
+                        isError: true,
+                    };
+                }
+            }
+            case 'notifications/initialized': {
+                initialized = true;
+                events.emit('initialized');
+                return null;
+            }
+            default: {
+                if (method.startsWith('notifications/')) {
+                    // Silently accept unknown notifications — the spec requires
+                    // they be ignored, not errored.
+                    return null;
+                }
+                throw new McpServerToolError(`method not found: ${method}`, MCP_ERROR_CODES.METHOD_NOT_FOUND);
+            }
+        }
+    }
+    async function handleMessage(request) {
+        const clientId = request.meta?.clientId;
+        // Notifications never get a response.
+        const isNotification = request.id === undefined || request.id === null;
+        if (isNotification) {
+            try {
+                await dispatch(request.method, request.params, clientId);
+            }
+            catch (error) {
+                log('error', `notification handler threw: ${error.message}`);
+            }
+            return null;
+        }
+        const id = request.id;
+        try {
+            const result = await dispatch(request.method, request.params, clientId);
+            // dispatch may return null for void responses (notifications) —
+            // but we already filtered those above. Treat null here as `{}`.
+            return {
+                jsonrpc: '2.0',
+                id,
+                result: result ?? {},
+            };
+        }
+        catch (error) {
+            const isToolError = error instanceof McpServerToolError;
+            const code = isToolError ? error.code : MCP_ERROR_CODES.INTERNAL_ERROR;
+            const message = error instanceof Error ? error.message : String(error);
+            log('error', `dispatch ${request.method} (id=${id}) failed: ${message}`);
+            return {
+                jsonrpc: '2.0',
+                id,
+                error: { code, message },
+            };
+        }
+    }
+    return {
+        handleMessage,
+        events,
+        listToolsSync() {
+            return tools.slice();
+        },
+        // Internal: exposed to tests via type assertion when they want to
+        // verify the initialized flag advanced. Not part of the public
+        // interface intentionally — production callers should listen on
+        // `events` instead.
+        // @ts-expect-error — debug accessor
+        _isInitialized() {
+            return initialized;
+        },
+    };
+}
+/**
+ * Run the server on stdio. Reads one JSON-RPC line per request from
+ * stdin, writes the response (or nothing for notifications) as one line
+ * to stdout. Lines are `\n`-terminated UTF-8 JSON.
+ *
+ * Returns a promise that resolves when stdin closes. The caller can race
+ * it against `signal` to force shutdown — the stdio reader is shielded
+ * by the same signal, so an abort terminates the line loop cleanly.
+ */
+export async function serveStdio(options) {
+    const stdin = options.stdin ?? process.stdin;
+    const stdout = options.stdout ?? process.stdout;
+    const { server, signal } = options;
+    return new Promise((resolve) => {
+        let buffer = '';
+        let closed = false;
+        const finish = () => {
+            if (closed)
+                return;
+            closed = true;
+            stdin.off('data', onData);
+            stdin.off('end', finish);
+            stdin.off('close', finish);
+            if (signal) {
+                signal.removeEventListener('abort', finish);
+            }
+            resolve();
+        };
+        const writeFrame = (response) => {
+            stdout.write(`${JSON.stringify(response)}\n`);
+        };
+        const writeParseError = (id, message) => {
+            writeFrame({
+                jsonrpc: '2.0',
+                id,
+                error: { code: MCP_ERROR_CODES.PARSE_ERROR, message },
+            });
+        };
+        const processLine = async (line) => {
+            const trimmed = line.trim();
+            if (trimmed.length === 0)
+                return;
+            let parsed;
+            try {
+                parsed = JSON.parse(trimmed);
+            }
+            catch (error) {
+                writeParseError(null, `invalid JSON: ${error.message}`);
+                return;
+            }
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                writeParseError(null, 'request must be a JSON object');
+                return;
+            }
+            const candidate = parsed;
+            if (candidate.jsonrpc !== '2.0' || typeof candidate.method !== 'string') {
+                writeParseError(typeof candidate.id === 'number' || typeof candidate.id === 'string'
+                    ? candidate.id
+                    : null, 'invalid JSON-RPC envelope: jsonrpc=2.0 + string method required');
+                return;
+            }
+            // Stdio is a single-tenant transport — the parent process owns
+            // both ends — so we intentionally drop any inbound `meta.clientId`.
+            // Per-connection scoping only makes sense for HTTP+SSE.
+            const request = {
+                jsonrpc: '2.0',
+                method: candidate.method,
+                ...(candidate.id !== undefined ? { id: candidate.id } : {}),
+                ...(candidate.params !== undefined ? { params: candidate.params } : {}),
+            };
+            const response = await server.handleMessage(request);
+            if (response)
+                writeFrame(response);
+        };
+        const onData = (chunk) => {
+            buffer += typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+            let newlineIndex = buffer.indexOf('\n');
+            while (newlineIndex !== -1) {
+                const line = buffer.slice(0, newlineIndex);
+                buffer = buffer.slice(newlineIndex + 1);
+                // Fire-and-forget the line handler; ordering of responses
+                // matches request ordering at the protocol level because the
+                // dispatch is microtask-serialized via the await above for
+                // each line — Node iterates `data` callbacks synchronously,
+                // and processLine awaits the dispatcher before returning so
+                // the next iteration of the loop sees the prior one settled.
+                void processLine(line);
+                newlineIndex = buffer.indexOf('\n');
+            }
+        };
+        if (signal) {
+            if (signal.aborted) {
+                finish();
+                return;
+            }
+            signal.addEventListener('abort', finish, { once: true });
+        }
+        if (!stdin.readable) {
+            // Stream already closed (e.g. parent piped EOF immediately).
+            finish();
+            return;
+        }
+        stdin.setEncoding('utf8');
+        stdin.on('data', onData);
+        stdin.on('end', finish);
+        stdin.on('close', finish);
+    });
+}
+//# sourceMappingURL=server.js.map

package/dist/core/repl/history.js

@@ -31,6 +31,7 @@
  * keys stay readable English (`brief`, `ts`). No forbidden words.
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync, renameSync, unlinkSync, } from 'node:fs';
+import { randomBytes } from 'node:crypto';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 /** Cap on stored entries per workspace. Drops oldest on overflow. */
@@ -77,7 +78,16 @@ export function append(input) {
     // sibling guarantees that). P2 fix from PR #335 triple-review.
     if (existing.length + 1 > MAX_HISTORY_ENTRIES) {
         const trimmed = [...existing.slice(existing.length + 1 - MAX_HISTORY_ENTRIES), entry];
-        const tmpPath = `${path}.tmp`;
+        // β1b #52 (2026-05-26): unique-per-call tmp suffix.
+        // Previous form was a fixed `${path}.tmp`, which means two CLI
+        // processes hitting the overflow rewrite at the same moment race
+        // on the same sibling file. Whichever writeFileSync lands second
+        // can corrupt the renameSync target's content (one process's
+        // serialized buffer overwrites the other mid-flight). Append a
+        // pid + monotonic-ish timestamp + 8 hex random bytes so the tmp
+        // names are collision-proof across PIDs, concurrent calls inside
+        // one PID, and rapid re-runs that share the same ms timestamp.
+        const tmpPath = `${path}.${process.pid}.${Date.now()}.${randomBytes(4).toString('hex')}.tmp`;
         try {
             writeFileSync(tmpPath, trimmed.map(serialize).join('\n') + '\n', { mode: 0o600 });
             renameSync(tmpPath, path);

package/dist/core/repl/model-pricing.js

@@ -0,0 +1,135 @@
+/**
+ * Static price ladder keyed by exact model slug.
+ *
+ * Source: provider list-price pages as of 2026-05-26. Keep prefix lookup
+ * (`priceForModel`) for forward compat — a `claude-opus-4-8` from a future
+ * model-router rebind falls back onto the `claude-opus-` family entry.
+ */
+const PRICE_LADDER = new Map([
+    // Anthropic Claude family
+    ['claude-opus-4-7', { inputUsdPerM: 15.0, outputUsdPerM: 75.0 }],
+    ['claude-opus-4-6', { inputUsdPerM: 15.0, outputUsdPerM: 75.0 }],
+    ['claude-sonnet-4-6', { inputUsdPerM: 3.0, outputUsdPerM: 15.0 }],
+    ['claude-sonnet-4-5', { inputUsdPerM: 3.0, outputUsdPerM: 15.0 }],
+    ['claude-haiku-4-5', { inputUsdPerM: 0.8, outputUsdPerM: 4.0 }],
+    // OpenAI family — sentinel entries so a `pugi config set` override lands clean.
+    ['gpt-4o', { inputUsdPerM: 2.5, outputUsdPerM: 10.0 }],
+    ['gpt-4o-mini', { inputUsdPerM: 0.15, outputUsdPerM: 0.6 }],
+    ['o3', { inputUsdPerM: 10.0, outputUsdPerM: 40.0 }],
+    ['o3-mini', { inputUsdPerM: 1.1, outputUsdPerM: 4.4 }],
+    // Mistral
+    ['mistral-large', { inputUsdPerM: 2.0, outputUsdPerM: 6.0 }],
+    ['mistral-small', { inputUsdPerM: 0.2, outputUsdPerM: 0.6 }],
+    // Embeddings — input-only; output is zero so the meter shows a
+    // flat per-call cost without inflating the "output" column.
+    ['voyage-3', { inputUsdPerM: 0.12, outputUsdPerM: 0 }],
+    ['voyage-3-large', { inputUsdPerM: 0.18, outputUsdPerM: 0 }],
+]);
+/**
+ * Family-prefix fallback. Used when an unknown slug starts with a
+ * known family stem (e.g. `claude-sonnet-4-7`).
+ */
+const FAMILY_PREFIX = [
+    ['claude-opus-', { inputUsdPerM: 15.0, outputUsdPerM: 75.0 }],
+    ['claude-sonnet-', { inputUsdPerM: 3.0, outputUsdPerM: 15.0 }],
+    ['claude-haiku-', { inputUsdPerM: 0.8, outputUsdPerM: 4.0 }],
+    ['gpt-4o', { inputUsdPerM: 2.5, outputUsdPerM: 10.0 }],
+    ['o3', { inputUsdPerM: 10.0, outputUsdPerM: 40.0 }],
+    ['mistral-', { inputUsdPerM: 2.0, outputUsdPerM: 6.0 }],
+    ['voyage-', { inputUsdPerM: 0.12, outputUsdPerM: 0 }],
+];
+/**
+ * Default ladder when no model slug is known (e.g. the older admin-api
+ * still on the pre-α7 event shape that does not carry `model`). Pinned
+ * to Sonnet-tier so the meter is "honestly conservative" — close to the
+ * default dispatch lane for `reason` + `codegen` tags.
+ */
+const DEFAULT_PRICE = { inputUsdPerM: 3.0, outputUsdPerM: 15.0 };
+/**
+ * Look up the price for a model slug. Resolution order:
+ *   1. Exact match in `PRICE_LADDER`.
+ *   2. Family-prefix match (`startsWith`).
+ *   3. Default Sonnet-tier rate.
+ *
+ * Pure — never throws. The cost meter calls this on every `agent.tokens`
+ * frame so it must stay branch-cheap.
+ */
+export function priceForModel(model) {
+    if (!model || typeof model !== 'string')
+        return DEFAULT_PRICE;
+    const exact = PRICE_LADDER.get(model);
+    if (exact)
+        return exact;
+    for (const [prefix, price] of FAMILY_PREFIX) {
+        if (model.startsWith(prefix))
+            return price;
+    }
+    return DEFAULT_PRICE;
+}
+/**
+ * Compute the USD cost for a single (input, output, model) triple.
+ * Returns a finite number, never NaN/Infinity, capped at zero floor so
+ * a buggy upstream that emits negative deltas (theoretically impossible
+ * via Anvil but we stay defensive) does not credit the operator's meter.
+ *
+ * Pure, deterministic, branch-cheap — called on every `agent.tokens`
+ * event so the hot path keeps the math inline.
+ */
+export function computeCostUsd(tokensIn, tokensOut, model) {
+    const price = priceForModel(model);
+    const safeIn = Number.isFinite(tokensIn) && tokensIn > 0 ? tokensIn : 0;
+    const safeOut = Number.isFinite(tokensOut) && tokensOut > 0 ? tokensOut : 0;
+    const usd = (safeIn * price.inputUsdPerM + safeOut * price.outputUsdPerM) / 1_000_000;
+    return Number.isFinite(usd) && usd > 0 ? usd : 0;
+}
+/**
+ * Format a token count for the status row. Spec (CEO 2026-05-26):
+ *   - `<1000` → raw integer (e.g. `42`)
+ *   - `≥1000` → one-decimal `k` (e.g. `1.2k`)
+ *   - `≥1_000_000` → one-decimal `m` (e.g. `1.0m`)
+ *
+ * Negative / NaN inputs render as `0`.
+ */
+export function formatTokens(value) {
+    if (!Number.isFinite(value) || value <= 0)
+        return '0';
+    if (value < 1_000)
+        return Math.floor(value).toString();
+    if (value < 1_000_000)
+        return `${(value / 1_000).toFixed(1)}k`;
+    return `${(value / 1_000_000).toFixed(1)}m`;
+}
+/**
+ * Format USD cost for the status row. Spec (CEO 2026-05-26):
+ *   - `≥ $0.01` → `$X.XX` (two decimals)
+ *   - `<  $0.01` (but > 0) → `$X.XXX` (three decimals, shows fractions
+ *     of a cent honestly instead of rounding to `$0.00`)
+ *   - `0` / NaN → `$0.00`
+ */
+export function formatCostUsd(usd) {
+    if (!Number.isFinite(usd) || usd <= 0)
+        return '$0.00';
+    if (usd >= 0.01)
+        return `$${usd.toFixed(2)}`;
+    return `$${usd.toFixed(3)}`;
+}
+/**
+ * Format an elapsed-ms duration as `1m2s` / `45s` / `2h3m`. Used by the
+ * status row's session-duration slot. Floors aggressively — we don't
+ * want sub-second decimals stealing column width.
+ */
+export function formatDuration(elapsedMs) {
+    if (!Number.isFinite(elapsedMs) || elapsedMs <= 0)
+        return '0s';
+    const totalSec = Math.floor(elapsedMs / 1000);
+    if (totalSec < 60)
+        return `${totalSec}s`;
+    const min = Math.floor(totalSec / 60);
+    const sec = totalSec % 60;
+    if (min < 60)
+        return `${min}m${sec.toString().padStart(2, '0')}s`;
+    const hr = Math.floor(min / 60);
+    const restMin = min % 60;
+    return `${hr}h${restMin.toString().padStart(2, '0')}m`;
+}
+//# sourceMappingURL=model-pricing.js.map