@pugi/cli 0.1.0-alpha.10

package/dist/core/engine/native-pugi.js

@@ -0,0 +1,369 @@
+import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { defaultEngineBudgets, runEngineLoop, } from '@pugi/sdk';
+import { FileReadCache } from '../file-cache.js';
+import { loadSettings } from '../settings.js';
+import { openSession, recordToolCall, recordToolResult } from '../session.js';
+import { buildExecutor, buildToolsSchema } from './tool-bridge.js';
+import { personaSlugFor, systemPromptFor } from './prompts.js';
+/**
+ * Real `NativePugiEngineAdapter`. Drives the Pugi CLI's tool-use loop:
+ *
+ *   1. Pick a system prompt + persona based on the task kind
+ *      (code/explain/fix/plan/build).
+ *   2. Build an OpenAI-shaped tools schema from the local tool registry,
+ *      gated by plan-mode (read-only).
+ *   3. Open a workspace tool context (settings, session, read cache).
+ *   4. Drive `runEngineLoop` against an `EngineLoopClient` until the
+ *      model returns a final text answer or the per-command budget is
+ *      exhausted.
+ *   5. Surface every turn / tool call into both the engine event stream
+ *      (consumer-visible status events) and the existing session log
+ *      (`.pugi/events.jsonl`) so audit replay sees every step.
+ *
+ * The adapter is intentionally transport-agnostic. `client` is required
+ * at construction; the CLI builds an `AnvilEngineLoopClient` from the
+ * resolved credentials, tests inject a fixture client. The adapter
+ * NEVER reads `process.env.PUGI_API_KEY` itself — that lives one layer
+ * up so unit tests can construct the adapter with an in-memory client.
+ *
+ * The engine task → loop mapping:
+ *   - `task.kind === 'build_task'` is mapped to the `build` command.
+ *   - `task.prompt` is the user message.
+ *   - `task.workspaceRoot` pins the workspace root for tool execution.
+ *   - `task.permissionMode` is read by the existing permission module;
+ *     the adapter itself only enforces the plan-mode tool gate which is
+ *     keyed on `kind`, not on permissionMode.
+ */
+export class NativePugiEngineAdapter {
+    options;
+    name = 'native-pugi';
+    /**
+     * Per-adapter scratch map: links the loop's tool_call id to the
+     * audit record id returned by `recordToolCall`. Code Reviewer P2
+     * retro 2026-05-23 moved this off the module scope — two adapters
+     * driven concurrently (cabinet UI + CLI on the same process) would
+     * otherwise share the same Map and a fast turn from adapter A
+     * could `.delete()` an entry that belonged to adapter B before its
+     * `onToolResult` fired, dropping audit pairing for adapter B.
+     * Keeping the Map per-instance contains the collision blast radius
+     * to a single `run()` invocation.
+     */
+    engineToolCallIds = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    async capabilities() {
+        return {
+            supportsStreaming: true,
+            supportsFileEdits: true,
+            supportsShell: true,
+            supportsLsp: false,
+            supportsSubagents: false,
+        };
+    }
+    async *run(task, ctx) {
+        const kind = toCommandKind(task.kind);
+        const root = task.workspaceRoot;
+        const session = this.options.session ?? openSession(root);
+        const settings = loadSettings(root);
+        const toolCtx = {
+            root,
+            settings,
+            session,
+            readCache: new FileReadCache(),
+        };
+        const budget = task.budget?.tokens
+            ? {
+                maxTokens: task.budget.tokens,
+                // The task-level budget only carries tokens; tool calls keep
+                // the per-command default so a careless caller cannot disable
+                // the call-count guard by overriding usd/tokens.
+                maxToolCalls: defaultEngineBudgets[kind].maxToolCalls,
+            }
+            : defaultEngineBudgets[kind];
+        yield {
+            type: 'status',
+            message: `Pugi engine starting: kind=${kind} budget=${budget.maxToolCalls} calls / ${budget.maxTokens} tokens`,
+        };
+        // Buffer status events emitted from inside the loop hooks. Async
+        // generators cannot yield from synchronous callbacks, so we collect
+        // them in a queue and drain after the loop call completes. The loop
+        // is short enough (≤ ~30 turns) that latency-to-stdout is acceptable
+        // — a follow-up PR can switch to an event emitter for true streaming.
+        const buffer = [];
+        // Track files mutated by the loop. We extract the path from the JSON
+        // arguments of every successful write/edit tool call; `bash` is left
+        // out because its filesystem footprint is opaque (a single command
+        // can touch dozens of paths via `make`, `pnpm build`, etc). The
+        // per-session events.jsonl already carries every file_mutation event
+        // for replay; this set is only the headline summary the CLI prints.
+        const filesChanged = new Set();
+        // Pending lookup: call.id → path extracted from arguments. We only
+        // commit to `filesChanged` when the corresponding onToolResult fires
+        // with `ok: true`, so a refused or failed edit does not surface as
+        // a phantom change in the operator summary.
+        const pendingMutations = new Map();
+        // Per-session events mirror — `.pugi/sessions/<id>/events.jsonl`.
+        // The existing global log at `.pugi/events.jsonl` is preserved as
+        // the audit-replay source of truth; this mirror is the easy-to-find
+        // per-run log for operators and the cabinet UI (Sprint 2B).
+        const sessionEventsPath = openSessionMirror(root, session.id);
+        const hooks = {
+            onTurnStart: (turnIndex, messageCount) => {
+                const msg = `turn ${turnIndex + 1}: requesting model (transcript=${messageCount} messages)`;
+                buffer.push({ type: 'status', message: msg });
+                appendSessionMirror(sessionEventsPath, { type: 'turn_start', turn: turnIndex + 1, transcript: messageCount });
+            },
+            onTurnComplete: (turnIndex, response) => {
+                if (response.stop === 'tool_use') {
+                    const calls = response.assistantMessage.toolCalls ?? [];
+                    buffer.push({
+                        type: 'status',
+                        message: `turn ${turnIndex + 1}: model requested ${calls.length} tool call(s)`,
+                    });
+                    appendSessionMirror(sessionEventsPath, {
+                        type: 'turn_complete',
+                        turn: turnIndex + 1,
+                        stop: 'tool_use',
+                        toolCalls: calls.length,
+                        tokensUsed: response.tokensUsed,
+                    });
+                }
+                else if (response.stop === 'text') {
+                    buffer.push({
+                        type: 'status',
+                        message: `turn ${turnIndex + 1}: model returned final text (${response.content.length} chars)`,
+                    });
+                    appendSessionMirror(sessionEventsPath, {
+                        type: 'turn_complete',
+                        turn: turnIndex + 1,
+                        stop: 'text',
+                        contentLength: response.content.length,
+                        tokensUsed: response.tokensUsed,
+                    });
+                }
+            },
+            onToolCall: (call) => {
+                // Record under an `engine_tool` prefix so the audit log can
+                // distinguish loop-driven calls from direct CLI tool calls.
+                const id = recordToolCall(session, `engine:${call.name}`, call.arguments.slice(0, 200));
+                // Stash the audit id on the call for `onToolResult` to close.
+                this.engineToolCallIds.set(call.id, id);
+                // Extract a candidate path for write/edit so we can build the
+                // filesChanged summary if (and only if) the call succeeds. Bad
+                // JSON is harmless here — we ignore it and the executor surfaces
+                // the actual parse error to the model.
+                if (call.name === 'write' || call.name === 'edit') {
+                    const path = extractPathArg(call.arguments);
+                    if (path)
+                        pendingMutations.set(call.id, path);
+                }
+                buffer.push({
+                    type: 'status',
+                    message: `tool_call: ${call.name}(${call.arguments.slice(0, 80)}${call.arguments.length > 80 ? '...' : ''})`,
+                });
+                appendSessionMirror(sessionEventsPath, {
+                    type: 'tool_call',
+                    tool: call.name,
+                    callId: call.id,
+                    argsPreview: call.arguments.slice(0, 200),
+                });
+            },
+            onToolResult: (call, result) => {
+                const auditId = this.engineToolCallIds.get(call.id);
+                if (auditId) {
+                    if (result.ok) {
+                        recordToolResult(session, auditId, 'success', result.content.slice(0, 200));
+                    }
+                    else {
+                        recordToolResult(session, auditId, 'error', result.error.slice(0, 200));
+                    }
+                    this.engineToolCallIds.delete(call.id);
+                }
+                const pendingPath = pendingMutations.get(call.id);
+                if (pendingPath) {
+                    if (result.ok)
+                        filesChanged.add(pendingPath);
+                    pendingMutations.delete(call.id);
+                }
+                buffer.push({
+                    type: 'status',
+                    message: result.ok
+                        ? `tool_result: ${call.name} ok`
+                        : `tool_result: ${call.name} error: ${result.error.slice(0, 120)}`,
+                });
+                appendSessionMirror(sessionEventsPath, {
+                    type: 'tool_result',
+                    tool: call.name,
+                    callId: call.id,
+                    ok: result.ok,
+                    summary: result.ok ? result.content.slice(0, 200) : result.error.slice(0, 200),
+                });
+            },
+        };
+        let outcome;
+        try {
+            outcome = await runEngineLoop({
+                client: this.options.client,
+                executor: buildExecutor({ kind, ctx: toolCtx }),
+                systemPrompt: systemPromptFor(kind),
+                userPrompt: task.prompt,
+                tools: buildToolsSchema(kind),
+                budget,
+                personaSlug: personaSlugFor(kind),
+                hooks,
+                temperature: this.options.temperature ?? 0.2,
+                signal: ctx.signal,
+            });
+        }
+        catch (error) {
+            // Defensive — runEngineLoop wraps errors into status: failed, so
+            // this branch is only hit if the executor or hooks themselves
+            // throw uncaught. Surface as a failed result so the CLI exits
+            // non-zero rather than hanging.
+            const message = error instanceof Error ? error.message : String(error);
+            yield {
+                type: 'result',
+                result: {
+                    status: 'failed',
+                    summary: `engine loop crashed: ${message}`,
+                    filesChanged: [],
+                    patchRefs: [],
+                    testsRun: [],
+                    risks: [`unhandled error in engine adapter: ${message}`],
+                    eventRefs: [],
+                },
+            };
+            return;
+        }
+        // Drain status buffer first so consumers see the chronological order.
+        for (const event of buffer)
+            yield event;
+        // Translate the loop outcome into an EngineResult.
+        const status = outcome.status === 'completed'
+            ? 'done'
+            : outcome.status === 'failed'
+                ? 'failed'
+                : 'blocked';
+        const summaryPrefix = outcome.status === 'completed'
+            ? ''
+            : outcome.status === 'budget_exhausted'
+                ? '[budget_exhausted] '
+                : outcome.status === 'tool_refused'
+                    ? '[plan_mode_refused] '
+                    : '[failed] ';
+        const filesChangedList = Array.from(filesChanged).sort();
+        appendSessionMirror(sessionEventsPath, {
+            type: 'outcome',
+            status: outcome.status,
+            toolCallCount: outcome.toolCallCount,
+            turnsUsed: outcome.turnsUsed,
+            tokensUsed: outcome.tokensUsed,
+            filesChanged: filesChangedList,
+            reason: outcome.reason,
+        });
+        yield {
+            type: 'result',
+            result: {
+                status,
+                summary: `${summaryPrefix}${outcome.finalText || outcome.reason || 'no answer returned'}`,
+                filesChanged: filesChangedList,
+                patchRefs: [],
+                testsRun: [],
+                risks: outcome.status === 'completed'
+                    ? []
+                    : [outcome.reason ?? `outcome=${outcome.status}`],
+                eventRefs: [
+                    `tool_calls=${outcome.toolCallCount}`,
+                    `turns=${outcome.turnsUsed}`,
+                    `tokens=${outcome.tokensUsed}`,
+                    // `outcome=<status>` is a machine-readable echo so callers
+                    // (cli.ts plan exit code, cabinet UI) can distinguish
+                    // `budget_exhausted` from `tool_refused` without parsing
+                    // the human-readable summary prefix. Code Reviewer P2
+                    // retro 2026-05-23: plan exit code previously collapsed
+                    // both blocked reasons into 0, which masked budget hits.
+                    `outcome=${outcome.status}`,
+                    `session=${session.id}`,
+                    `ctx=${ctx.sessionId}`,
+                    `mirror=${sessionEventsPath}`,
+                ],
+            },
+        };
+    }
+}
+/**
+ * Extract a workspace-relative path from a tool_call's JSON arguments.
+ * Used by the adapter hook layer to build the filesChanged summary at
+ * the end of the run. Returns `null` on bad JSON / missing field so the
+ * caller can quietly skip; the executor surfaces the real parse error
+ * to the model.
+ */
+function extractPathArg(raw) {
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            const path = parsed.path;
+            if (typeof path === 'string' && path.length > 0)
+                return path;
+        }
+    }
+    catch {
+        // bad JSON — ignored here, the executor produces the canonical error.
+    }
+    return null;
+}
+/**
+ * Open the per-session events mirror at
+ * `<root>/.pugi/sessions/<sessionId>/events.jsonl` and return the path.
+ *
+ * The global audit log at `.pugi/events.jsonl` is the source of truth
+ * for replay; this mirror is the per-run convenience copy that the
+ * cabinet UI surfaces. Both share the same schema-of-strings format so
+ * the consumer can `jq` either file without translation. When `.pugi`
+ * does not exist yet (init-less run) we no-op and return an empty
+ * string; the hooks then write to nowhere.
+ */
+function openSessionMirror(root, sessionId) {
+    const pugiDir = resolve(root, '.pugi');
+    if (!existsSync(pugiDir))
+        return '';
+    const sessionDir = resolve(pugiDir, 'sessions', sessionId);
+    try {
+        mkdirSync(sessionDir, { recursive: true });
+    }
+    catch {
+        return '';
+    }
+    return resolve(sessionDir, 'events.jsonl');
+}
+function appendSessionMirror(path, event) {
+    if (!path)
+        return;
+    const enriched = { timestamp: new Date().toISOString(), ...event };
+    try {
+        appendFileSync(path, `${JSON.stringify(enriched)}\n`, { encoding: 'utf8', mode: 0o600 });
+    }
+    catch {
+        // Mirror is best-effort — the global audit log already captured the
+        // tool_call / tool_result events via session.ts.
+    }
+}
+/**
+ * Map the SDK's engine task kind to a CLI command kind. The SDK uses
+ * `build_task` as the canonical name for what the CLI exposes as
+ * `pugi build`; everything else passes through.
+ */
+function toCommandKind(kind) {
+    if (kind === 'build_task')
+        return 'build';
+    return kind;
+}
+// The per-adapter `engineToolCallIds` Map lives on the
+// `NativePugiEngineAdapter` instance above — Code Reviewer P2 retro
+// 2026-05-23 lifted it off the module scope to prevent collisions
+// under parallel adapter runs (cabinet UI + CLI sharing one process).
+//# sourceMappingURL=native-pugi.js.map

package/dist/core/engine/noop.js

@@ -0,0 +1,27 @@
+export class NoopEngineAdapter {
+    name = 'noop';
+    async capabilities() {
+        return {
+            supportsStreaming: false,
+            supportsFileEdits: false,
+            supportsShell: false,
+            supportsLsp: false,
+            supportsSubagents: false,
+        };
+    }
+    async *run(task, _ctx) {
+        yield {
+            type: 'result',
+            result: {
+                status: 'blocked',
+                summary: `No engine configured for ${task.kind}`,
+                filesChanged: [],
+                patchRefs: [],
+                testsRun: [],
+                risks: ['Engine adapter is not configured yet.'],
+                eventRefs: [],
+            },
+        };
+    }
+}
+//# sourceMappingURL=noop.js.map

package/dist/core/engine/prompts.js

@@ -0,0 +1,118 @@
+import { getJobRegistry, summarizeJobsForPrompt, } from '../jobs/registry.js';
+/**
+ * System prompts for each engine command. Each prompt:
+ *   - Anchors the model in Pugi's local-first contract (ADR-0037).
+ *   - Lists the tools the model may call (the registry is authoritative,
+ *     but stating it inline prevents the model from inventing tool names
+ *     when the tool schema is large).
+ *   - Defines the deliverable shape so the model produces a useful final
+ *     text answer instead of "here is what I did".
+ *
+ * The prompts are intentionally terse. Per gstack `engineering-standards`
+ * the persona system prompt comes from the runtime (Anvil bridge
+ * prepends `oes-dev` / Sigma prompt automatically when configured); these
+ * prompts ride on top and scope the model to the current command.
+ *
+ * Sprint α5.9 (ADR-0056 PR-PUGI-CLI-M1-GAP-J): the system prompt picks up
+ * a `BACKGROUND JOBS:` snapshot appended at the tail so the agent loop
+ * knows what background bash work is currently on watch and can avoid
+ * spawning a duplicate. The snapshot is sourced from `JobRegistry` and
+ * formatted by `summarizeJobsForPrompt` so the surface is single-sourced.
+ */
+const COMMON_LOCAL_FIRST_PREAMBLE = [
+    'You are the Pugi CLI agent running locally inside the operator\'s repository.',
+    'The local filesystem is the source of truth. Every change you make is committed locally; nothing is uploaded by default (ADR-0037 local-first).',
+    'You have a tool registry: read, write, edit, grep, glob, bash. Call tools to inspect and modify the workspace.',
+    'Cite file paths relative to the workspace root. Keep edits minimal and reversible.',
+    'When you are done, return a single final text answer that the operator can read on the CLI.',
+].join(' ');
+const PLAN_TOOLS_NOTE = 'PLAN MODE IS READ-ONLY. You may call read, grep, glob. Calls to write, edit, or bash will be refused and end the run. Produce a written plan, not changes.';
+const EDIT_FLOW_RULES = [
+    'Before calling edit on a file you have not yet read this session, call read first — the edit tool fails otherwise.',
+    'Prefer edit over write when changing existing files; write only for newly created files.',
+    'After your last tool call, summarise what you changed and what the operator should review.',
+].join(' ');
+export function systemPromptFor(kind) {
+    const base = baseSystemPromptFor(kind);
+    const snapshot = formatBackgroundJobsSnapshot(getJobRegistrySafely());
+    if (!snapshot)
+        return base;
+    return `${base}\n\n${snapshot}`;
+}
+function baseSystemPromptFor(kind) {
+    switch (kind) {
+        case 'code':
+            return [
+                COMMON_LOCAL_FIRST_PREAMBLE,
+                'Command: `pugi code`. The operator gave you a feature request or refactor. Implement it end-to-end.',
+                EDIT_FLOW_RULES,
+                'If the request is ambiguous, ask one clarifying question by returning a text answer instead of editing.',
+            ].join('\n\n');
+        case 'explain':
+            return [
+                COMMON_LOCAL_FIRST_PREAMBLE,
+                'Command: `pugi explain`. The operator pointed you at code or a concept. Read what you need, then produce a walkthrough.',
+                'You should not edit files. If you need to demonstrate a change, describe it in the final answer.',
+                'Keep the explanation to the operator\'s level — concise, with file:line references where useful.',
+            ].join('\n\n');
+        case 'fix':
+            return [
+                COMMON_LOCAL_FIRST_PREAMBLE,
+                'Command: `pugi fix`. The operator gave you a bug report or failing test. Investigate the root cause first, then apply the smallest patch that fixes it.',
+                EDIT_FLOW_RULES,
+                'Surface the root cause in your final answer so the operator can verify the diagnosis is correct.',
+            ].join('\n\n');
+        case 'plan':
+            return [
+                COMMON_LOCAL_FIRST_PREAMBLE,
+                'Command: `pugi plan`. The operator wants a plan, not an implementation.',
+                PLAN_TOOLS_NOTE,
+                'Produce a numbered list of steps with rough file targets and a brief risk note. Cite the files you consulted.',
+            ].join('\n\n');
+        case 'build':
+            return [
+                COMMON_LOCAL_FIRST_PREAMBLE,
+                'Command: `pugi build`. The operator wants you to scaffold a feature across multiple files.',
+                EDIT_FLOW_RULES,
+                'Group related edits, run lint/test via bash where it adds confidence, and list every file you created or modified in the final answer.',
+            ].join('\n\n');
+    }
+}
+/**
+ * Builds the BACKGROUND JOBS snapshot block injected at the tail of
+ * the system prompt. Sync because the surrounding `systemPromptFor`
+ * builder is sync (the engine adapter does not await prompt
+ * assembly) and the JobRegistry's `listSync()` is essentially free
+ * (single JSON file read with sync fs primitives). Returns an empty
+ * string if the registry cannot be reached so the prompt assembly
+ * never crashes when the ledger is unavailable.
+ */
+export function formatBackgroundJobsSnapshot(registry) {
+    if (!registry)
+        return '';
+    try {
+        const entries = registry.listSync();
+        return summarizeJobsForPrompt(entries);
+    }
+    catch {
+        return '';
+    }
+}
+function getJobRegistrySafely() {
+    try {
+        return getJobRegistry();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Anvil persona slug to invoke per command. Today every command routes
+ * to `oes-dev` (Sigma) — the Tier-2 reviewer persona already configured
+ * for Pugi runtime work. When we add per-command personas (e.g. `pugi-
+ * planner`, `pugi-coder`) this is the single switch to update.
+ */
+export function personaSlugFor(_kind) {
+    return 'oes-dev';
+}
+//# sourceMappingURL=prompts.js.map