@pugi/cli 0.1.0-beta.1 → 0.1.0-beta.11

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

@@ -1,9 +1,10 @@
 import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { defaultEngineBudgets, runEngineLoop, } from '@pugi/sdk';
+import { runEngineLoop, } from '@pugi/sdk';
 import { FileReadCache } from '../file-cache.js';
 import { loadSettings } from '../settings.js';
 import { openSession, recordToolCall, recordToolResult } from '../session.js';
+import { resolveBudget } from './budgets.js';
 import { buildExecutor, buildToolsSchema } from './tool-bridge.js';
 import { personaSlugFor, systemPromptFor } from './prompts.js';
 /**
@@ -73,15 +74,21 @@ export class NativePugiEngineAdapter {
             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];
+        // β1a r1 (budget wiring, 2026-05-26): swap the legacy SDK per-
+        // command budget lookup for the Pl9 `resolveBudget()` pipeline so
+        // `.pugi/settings.json::budgets.<command>` overrides actually take
+        // effect at runtime + the HARD_MAX_* caps guard misconfigured
+        // envelopes pre-flight. Before this fix the β1 Pl9 module
+        // (`core/engine/budgets.ts`) was dead code — the adapter still
+        // read the per-command defaults from the SDK, so operators who
+        // set `budgets.code.maxTokens = 50000` in settings.json got the
+        // legacy 30k anyway and `assertBudgetWithinTier` never ran.
+        //
+        // Task-level token override (e.g. CLI `--max-tokens`) keeps
+        // precedence; tool-call ceiling falls through to the resolved
+        // budget so a careless caller cannot disable the call-count
+        // guard by setting only token count.
+        const budget = resolveBudget(kind, settings, task.budget?.tokens ? { maxTokens: task.budget.tokens } : undefined);
         yield {
             type: 'status',
             message: `Pugi engine starting: kind=${kind} budget=${budget.maxToolCalls} calls / ${budget.maxTokens} tokens`,
@@ -206,15 +213,48 @@ export class NativePugiEngineAdapter {
         try {
             outcome = await runEngineLoop({
                 client: this.options.client,
-                executor: buildExecutor({ kind, ctx: toolCtx }),
+                executor: buildExecutor({
+                    kind,
+                    ctx: toolCtx,
+                    sessionId: session.id,
+                    workspaceRoot: root,
+                    // Conservatively false unless the caller explicitly opted in
+                    // via constructor. Interactive ask-modal bridge is wired by
+                    // the REPL layer in β2; for now non-TTY envelope is the path.
+                    interactive: false,
+                    // β1a r1 (web_fetch gating): executor allowFetch matches the
+                    // schema-advertise gate so a settings.json opt-in actually
+                    // enables the call. Without this the model would not even
+                    // see the `web_fetch` tool, but a `pugi web` CLI dispatch
+                    // through the executor would still be allowed because the
+                    // tool registry is independent.
+                    allowFetch: settings.web?.fetch?.enabled === true,
+                }),
                 systemPrompt: systemPromptFor(kind),
                 userPrompt: task.prompt,
-                tools: buildToolsSchema(kind),
+                // β1a r1 (web_fetch gating): pass the OR of
+                // `.pugi/settings.json::web.fetch.enabled` and the runtime
+                // `allowFetch` flag (today the adapter is conservative — see
+                // `buildExecutor` call below). When neither is true the
+                // `web_fetch` tool is not advertised to the model at all.
+                tools: buildToolsSchema(kind, {
+                    allowFetch: settings.web?.fetch?.enabled === true,
+                }),
                 budget,
                 personaSlug: personaSlugFor(kind),
                 hooks,
                 temperature: this.options.temperature ?? 0.2,
                 signal: ctx.signal,
+                // β1 (audit E2): forward CLI sub-command + α6.10 routing tag +
+                // operator-pinned model so the runtime controller's DTO sees
+                // all three. `tag` derives 1:1 from `command` for now
+                // (`code → code`, `build → build_task`, etc.); future routing
+                // changes flip the mapping table without touching the call
+                // site. `model` is left undefined here — operator-pinned model
+                // pinning ships in β6 with persona routing.
+                command: kind,
+                tag: dispatchTagFor(kind),
+                model: this.options.model,
             });
         }
         catch (error) {
@@ -367,6 +407,66 @@ function toCommandKind(kind) {
         return 'build';
     return kind;
 }
+/**
+ * β1 (audit E2) → β1a r1 (engine tag contract fix, 2026-05-26): map a
+ * CLI command kind to its α6.10 dispatch tag.
+ *
+ * The admin-api controller (`pugi-engine.controller.ts`) routes per-tag
+ * to a model/persona pair via
+ * `apps/admin-api/src/mira/routing/dispatch-tag.ts::DISPATCH_TAGS`. The
+ * closed `EngineChatTag` vocabulary is
+ * `classify | reason | codegen | summarize | vision` — note that
+ * `code`, `fix`, `plan`, `build`, `explain` (CLI command names) are NOT
+ * in this set.
+ *
+ * Before this fix `dispatchTagFor()` returned the CLI command names
+ * as-is and the runtime DTO rejected the payload with HTTP 400
+ * (`tag must be one of: classify, reason, codegen, summarize, vision`)
+ * before ever reaching the routing layer. Every `pugi code/fix/plan/
+ * build/explain` against the live runtime returned `failed: HTTP 400`.
+ *
+ * Mapping rationale (each row keeps the most informative `tag` value
+ * for cost telemetry / model selection):
+ *
+ *   - `code`, `fix`       → `codegen` (edits / diffs / patches)
+ *   - `build_task`/`build` → `codegen` + `budget_hint: 'max'`
+ *     (scaffolding hits the 30-call / 80k-token ceiling — give the
+ *     router permission to pick the largest model in the tier)
+ *   - `plan`              → `reason` (no mutations, long-form thought)
+ *   - `explain`           → `summarize` (read-only walkthrough)
+ *
+ * `priority: 'realtime'` for every command — Pugi is an interactive
+ * CLI; background dispatch is reserved for the cabinet's RAG ingest
+ * cron path. `budget_hint: 'std'` is the default for the cost-balanced
+ * router row; only `build_task` opts up to `'max'`.
+ */
+export function dispatchTagFor(kind) {
+    switch (kind) {
+        case 'code':
+        case 'fix':
+            return { tag: 'codegen', priority: 'realtime', budget_hint: 'std' };
+        case 'build':
+            // `build_task` on the engine task kind side is the heavy
+            // scaffolding lane — biggest budget envelope, biggest model
+            // permitted via `budget_hint: 'max'`.
+            return { tag: 'codegen', priority: 'realtime', budget_hint: 'max' };
+        case 'plan':
+            return { tag: 'reason', priority: 'realtime', budget_hint: 'std' };
+        case 'explain':
+            return { tag: 'summarize', priority: 'realtime', budget_hint: 'std' };
+        default: {
+            // Exhaustiveness check — `EngineCommandKind` is a closed union,
+            // so the switch above covers every case. If a new command kind
+            // is added the compiler flags this branch and the map must be
+            // extended. Fall back to `reason` as the most conservative
+            // routing choice so a future kind addition cannot accidentally
+            // unlock a write-heavy model lane.
+            const exhaustive = kind;
+            void exhaustive;
+            return { tag: 'reason', priority: 'realtime', budget_hint: 'std' };
+        }
+    }
+}
 // 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

package/dist/core/engine/prompts.js

@@ -22,6 +22,14 @@ import { getJobRegistry, summarizeJobsForPrompt, } from '../jobs/registry.js';
 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).',
+    // R1 fix (2026-05-26, PR #413 r1, Fix 5 Option B): only advertise the
+    // tools currently wired in `tool-bridge.ts::WIRED_TOOLS`. α7.7 ships
+    // apply_patch / lsp_* / worktree_* as CLI-only surfaces (`pugi patch`,
+    // `pugi lsp`, `pugi worktree`); wiring them into the engine loop is
+    // deferred to β2 (apply_patch), β4 (LSP tools), β7 (worktree tools)
+    // per the consolidated sprint plan. Advertising them in the system
+    // prompt without a matching executor entry caused Mira to attempt
+    // calls that returned `unknown_tool` — broken eval surface.
     '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.',

package/dist/core/engine/tool-bridge.js

@@ -1,5 +1,9 @@
 import { editTool, globTool, grepTool, OperatorAbortedError, readTool, writeTool, } from '../../tools/file-tools.js';
 import { bashToolSync } from '../../tools/bash.js';
+import { askUser } from '../../tools/ask-user.js';
+import { skillInvoke, skillList } from '../../tools/skill-tool.js';
+import { taskCreate, taskGet, taskList, taskUpdate, } from '../../tools/tasks.js';
+import { webFetchTool } from '../../tools/web-fetch.js';
 /**
  * Tool-bridge: turns the abstract tool registry into:
  *   1. An OpenAI-shaped tools schema for `EngineLoopClient.send`.
@@ -23,16 +27,49 @@ import { bashToolSync } from '../../tools/bash.js';
 /**
  * Read-only subset surfaced to plan-mode. Mutating tools (write, edit,
  * bash) are intentionally absent so the model rarely tries them.
+ *
+ * β1: task_* + skill + ask_user_question + web_fetch are all read-only
+ * from the workspace's perspective (no file writes), so they stay
+ * available in plan mode. The ledger writes for `task_*` land in
+ * `.pugi/sessions/<id>/tasks.jsonl` which is metadata, not source.
  */
-const READ_ONLY_TOOLS = new Set(['read', 'grep', 'glob']);
+const READ_ONLY_TOOLS = new Set([
+    'read',
+    'grep',
+    'glob',
+    'ask_user_question',
+    'skill',
+    'skills_list',
+    'task_create',
+    'task_get',
+    'task_list',
+    'task_update',
+    'web_fetch',
+]);
 /**
- * Tools we actually wire today. The registry has more entries
- * (task_*, skill, question) — those route through the runtime layer, not
- * the local filesystem, so they ship in a follow-up PR. M1 cornerstone is
- * the six core tools.
+ * Tools the engine loop dispatches. β1 expands the M1 cornerstone six
+ * (read/write/edit/grep/glob/bash) with task_* + ask_user_question +
+ * skill + skill list + web_fetch. The registry advertises these slots
+ * to the runtime; without dispatcher entries the model would call
+ * "unknown tool" errors.
  */
-const WIRED_TOOLS = new Set(['read', 'write', 'edit', 'grep', 'glob', 'bash']);
-export function buildToolsSchema(kind) {
+const WIRED_TOOLS = new Set([
+    'read',
+    'write',
+    'edit',
+    'grep',
+    'glob',
+    'bash',
+    'ask_user_question',
+    'skill',
+    'skills_list',
+    'task_create',
+    'task_get',
+    'task_list',
+    'task_update',
+    'web_fetch',
+]);
+export function buildToolsSchema(kind, options = { allowFetch: false }) {
     const planMode = kind === 'plan';
     const toolDefs = [
         {
@@ -72,6 +109,121 @@ export function buildToolsSchema(kind) {
             },
         },
     ];
+    // β1 T1/T6: TodoWrite (Pugi grammar = `task_*`). Append-only ledger
+    // at `.pugi/sessions/<id>/tasks.jsonl`.
+    toolDefs.push({
+        name: 'task_create',
+        description: 'Append a new task to the session todo ledger. Returns the assigned task id and full record. Mirrors Claude Code TodoWrite/create.',
+        parameters: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['title'],
+            properties: {
+                title: { type: 'string', description: 'Short imperative summary, max 2000 chars.' },
+                status: {
+                    type: 'string',
+                    enum: ['pending', 'in_progress', 'completed', 'cancelled'],
+                    description: 'Initial status. Default pending.',
+                },
+                notes: { type: 'string', description: 'Optional free-form context.' },
+            },
+        },
+    }, {
+        name: 'task_get',
+        description: 'Fetch a single task record by id. Returns null when absent.',
+        parameters: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['id'],
+            properties: { id: { type: 'string' } },
+        },
+    }, {
+        name: 'task_list',
+        description: 'List all tasks for the current session ordered by createdAt ascending.',
+        parameters: { type: 'object', additionalProperties: false, properties: {} },
+    }, {
+        name: 'task_update',
+        description: 'Mutate status/title/notes on an existing task. Throws on unknown id. Append-only journal.',
+        parameters: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['id'],
+            properties: {
+                id: { type: 'string' },
+                title: { type: 'string' },
+                status: {
+                    type: 'string',
+                    enum: ['pending', 'in_progress', 'completed', 'cancelled'],
+                },
+                notes: { type: 'string' },
+            },
+        },
+    });
+    // β1 T2: AskUserQuestion bridge. Returns picked answer in interactive
+    // mode, `[user_input_required]` envelope otherwise.
+    toolDefs.push({
+        name: 'ask_user_question',
+        description: 'Surface a 2-4 option modal to the operator. Interactive TTY: returns the chosen label(s). Non-TTY: returns a [user_input_required] envelope.',
+        parameters: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['question', 'options'],
+            properties: {
+                question: { type: 'string', description: 'Short, scannable question. Max 1000 chars.' },
+                options: {
+                    type: 'array',
+                    items: { type: 'string', maxLength: 200 },
+                    minItems: 2,
+                    maxItems: 4,
+                },
+                multiSelect: { type: 'boolean' },
+            },
+        },
+    });
+    // β1 T3: Skill tool — discover + invoke locally-installed skills.
+    toolDefs.push({
+        name: 'skills_list',
+        description: 'List installed skills (global + workspace). Returns name+description+scope.',
+        parameters: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                scope: { type: 'string', enum: ['all', 'global', 'workspace'] },
+            },
+        },
+    }, {
+        name: 'skill',
+        description: 'Load a skill body by name. Workspace scope wins over global. Body capped at 32KB.',
+        parameters: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['name'],
+            properties: { name: { type: 'string' } },
+        },
+    });
+    // β1 T5 → β1a r1 (gating fix, 2026-05-26): WebFetch wire-in. Schema
+    // mirrors the existing tool surface in
+    // `apps/pugi-cli/src/tools/web-fetch.ts`. SSRF guard runs inside the
+    // tool itself, but advertising the tool to the model when the tenant
+    // has not opted in is itself a privacy leak — the model could infer
+    // URL patterns and try to exfiltrate via the refused call's argument
+    // bytes. Only push the schema entry when the operator has explicitly
+    // enabled fetch (either via `.pugi/settings.json::web.fetch.enabled`
+    // or via `--allow-fetch`).
+    if (options.allowFetch) {
+        toolDefs.push({
+            name: 'web_fetch',
+            description: 'One-shot HTTP GET against an operator-supplied URL. Response is parsed to Markdown and wrapped in <untrusted-content> sentinel. Gated off by default.',
+            parameters: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['url'],
+                properties: {
+                    url: { type: 'string', description: 'Fully-qualified http(s) URL.' },
+                },
+            },
+        });
+    }
     if (!planMode) {
         toolDefs.push({
             name: 'write',
@@ -135,7 +287,8 @@ function requireString(obj, key) {
     return v;
 }
 export function buildExecutor(input) {
-    const { kind, ctx, hooks, sessionId } = input;
+    const { kind, ctx, hooks, sessionId, askUserBridge, interactive, allowFetch } = input;
+    const workspaceRoot = input.workspaceRoot ?? ctx.root;
     const planMode = kind === 'plan';
     return async ({ name, arguments: argsRaw }) => {
         if (!WIRED_TOOLS.has(name)) {
@@ -185,6 +338,21 @@ export function buildExecutor(input) {
         }
         const args = parseArgs(argsRaw);
         const dispatch = async () => {
+            // β1 T1/T2/T3/T5/T6: async-dispatch the new tool surface.
+            // task_*, skill, ask_user_question, web_fetch all live behind
+            // an async or async-compatible boundary.
+            if (name === 'task_create' || name === 'task_get' || name === 'task_list' || name === 'task_update') {
+                return dispatchTaskTool(name, args, { workspaceRoot, sessionId });
+            }
+            if (name === 'ask_user_question') {
+                return dispatchAskUser(args, { interactive: Boolean(interactive), bridge: askUserBridge });
+            }
+            if (name === 'skill' || name === 'skills_list') {
+                return dispatchSkillTool(name, args, { workspaceRoot });
+            }
+            if (name === 'web_fetch') {
+                return dispatchWebFetch(args, { ctx, allowFetch: Boolean(allowFetch) });
+            }
             return dispatchTool(name, args, ctx);
         };
         try {
@@ -342,4 +510,95 @@ function dispatchTool(name, args, ctx) {
             throw new Error(`unhandled tool: ${name}`);
     }
 }
+/* ----------------------------- β1 dispatchers ----------------------------- */
+function dispatchTaskTool(name, args, opts) {
+    if (!opts.sessionId) {
+        throw new Error(`${name}: no sessionId in scope — task ledger requires a session`);
+    }
+    const tctx = { workspaceRoot: opts.workspaceRoot, sessionId: opts.sessionId };
+    switch (name) {
+        case 'task_create': {
+            const title = requireString(args, 'title');
+            const status = optionalString(args, 'status');
+            const notes = optionalString(args, 'notes');
+            const record = taskCreate(tctx, {
+                title,
+                ...(status !== undefined ? { status: status } : {}),
+                ...(notes !== undefined ? { notes } : {}),
+            });
+            return JSON.stringify(record);
+        }
+        case 'task_get': {
+            const id = requireString(args, 'id');
+            const record = taskGet(tctx, id);
+            return record ? JSON.stringify(record) : 'null';
+        }
+        case 'task_list': {
+            const list = taskList(tctx);
+            return JSON.stringify(list);
+        }
+        case 'task_update': {
+            const id = requireString(args, 'id');
+            const title = optionalString(args, 'title');
+            const status = optionalString(args, 'status');
+            const notes = optionalString(args, 'notes');
+            const record = taskUpdate(tctx, {
+                id,
+                ...(title !== undefined ? { title } : {}),
+                ...(status !== undefined ? { status: status } : {}),
+                ...(notes !== undefined ? { notes } : {}),
+            });
+            return JSON.stringify(record);
+        }
+    }
+}
+async function dispatchAskUser(args, opts) {
+    const question = requireString(args, 'question');
+    const rawOptions = args['options'];
+    if (!Array.isArray(rawOptions)) {
+        throw new Error('ask_user_question: options must be an array');
+    }
+    const options = rawOptions.map((o, i) => {
+        if (typeof o !== 'string') {
+            throw new Error(`ask_user_question: options[${i}] must be a string`);
+        }
+        return o;
+    });
+    const multiSelect = args['multiSelect'] === true;
+    const result = await askUser({ interactive: opts.interactive, ...(opts.bridge ? { bridge: opts.bridge } : {}) }, { question, options, multiSelect });
+    return result.envelope;
+}
+async function dispatchSkillTool(name, args, opts) {
+    if (name === 'skills_list') {
+        const scopeArg = optionalString(args, 'scope');
+        const scope = scopeArg === 'global' || scopeArg === 'workspace' ? scopeArg : 'all';
+        const list = skillList({ workspaceRoot: opts.workspaceRoot }, { scope });
+        return JSON.stringify(list);
+    }
+    // name === 'skill' (invoke).
+    // β1a r1 (2026-05-26): `skillInvoke` is now async — it re-verifies
+    // the trust manifest sha256 against the on-disk body on every call.
+    // Bubble up `await` so a post-install tamper surfaces as a tool
+    // error the model sees, not a swallowed Promise<SkillInvokeResult>.
+    const skName = requireString(args, 'name');
+    const result = await skillInvoke({ workspaceRoot: opts.workspaceRoot }, { name: skName });
+    return JSON.stringify(result);
+}
+async function dispatchWebFetch(args, opts) {
+    const url = requireString(args, 'url');
+    const result = await webFetchTool({ url }, {
+        settings: opts.ctx.settings,
+        allowFetch: opts.allowFetch,
+    });
+    return JSON.stringify(result);
+}
+function optionalString(obj, key) {
+    const v = obj[key];
+    if (v === undefined || v === null)
+        return undefined;
+    if (typeof v !== 'string') {
+        throw new Error(`tool argument "${key}" must be a string when present`);
+    }
+    return v;
+}
 //# sourceMappingURL=tool-bridge.js.map