@pugi/sdk 0.1.0-alpha.10

package/dist/engine-loop.js

@@ -0,0 +1,342 @@
+/**
+ * Engine loop protocol — the Pugi CLI's tool-use loop driver.
+ *
+ * The CLI's `NativePugiEngineAdapter` runs a structured tool-use loop against
+ * Anvil. Each turn the CLI sends the conversation transcript + a tools schema
+ * to the runtime; the runtime returns either a final text answer or a list of
+ * tool calls. The CLI executes the calls locally (read/write/edit/grep/glob/
+ * bash) against the workspace and feeds the results back in the next turn.
+ *
+ * This module defines the contracts shared by:
+ *   - CLI side: the loop driver (`runEngineLoop`) + budget enforcement.
+ *   - Runtime side: a thin proxy in front of `AnvilBridgeService.askPersona`.
+ *   - Tests: a fixture-based `EngineLoopClient` that returns canned responses
+ *     so the loop can be exercised without network.
+ *
+ * Local-first contract (ADR-0037):
+ *   - The CLI is the only side that touches the filesystem. The runtime
+ *     never sees raw file bytes — only the tool results that the local
+ *     loop chooses to surface back into the transcript.
+ *   - Budgets (`maxToolCalls`, `maxTokens`) are enforced client-side so a
+ *     runaway model cannot rack up Anvil cost without the operator noticing.
+ *   - The loop refuses to write/edit/bash when the command kind is `plan`.
+ *
+ * Why OpenAI-compatible shape (instead of Anthropic's tool_use blocks):
+ *   - Anvil's chat-completions endpoint is OpenAI-compatible; coercing to
+ *     OpenAI-style `tools` + `tool_calls` matches the upstream wire format
+ *     exactly. Providers that natively speak Anthropic (Claude) are wrapped
+ *     by Anvil's bridge layer — that translation is not the CLI's concern.
+ */
+import { z } from 'zod';
+/**
+ * Command surface that the CLI invokes. The runtime uses this to select a
+ * system prompt and persona behaviour:
+ *   - `code` — general edit+create. Budget: 20 tool calls / 50k tokens.
+ *   - `explain` — read-only walkthrough. Budget: 5 / 20k.
+ *   - `fix`  — bug investigation + targeted patch. Budget: 20 / 50k.
+ *   - `plan` — produce a plan artifact, no mutations. Budget: 3 / 30k.
+ *               Mutating tools refused even if the model requests them.
+ *   - `build` — multi-file scaffolding. Budget: 30 / 80k.
+ */
+export const engineCommandKindSchema = z.enum([
+    'code',
+    'explain',
+    'fix',
+    'plan',
+    'build',
+]);
+/**
+ * Per-command budget envelope. Hard caps enforced inside `runEngineLoop`:
+ *   - `maxToolCalls` — total executed tool calls across all turns.
+ *   - `maxTokens` — total tokens accumulated (prompt + completion) across
+ *     turns. Counted via `usage.totalTokens` reported by the runtime; when
+ *     the runtime reports `tokensUsed === 0` we fall back to a
+ *     `transcript-chars / 4` heuristic so a runtime that omits usage
+ *     accounting (older Anvil builds, fixture clients, providers that
+ *     return null usage on tool_use responses) still trips the budget
+ *     instead of looping forever. Code Reviewer P2 retro 2026-05-23.
+ *
+ * The loop terminates with `status: 'budget_exhausted'` when either cap is
+ * exceeded. The caller decides whether that is a failure or a normal stop.
+ */
+export const engineBudgetSchema = z.object({
+    maxToolCalls: z.number().int().positive(),
+    maxTokens: z.number().int().positive(),
+});
+/**
+ * Canonical per-command budgets. Tuned to keep Anvil cost predictable while
+ * still giving `build` enough headroom to scaffold a small feature.
+ *
+ *   code/fix → 20 calls / 50k tokens
+ *   explain  → 5 calls  / 20k tokens
+ *   plan     → 8 calls  / 30k tokens   (read-only)
+ *   build    → 30 calls / 80k tokens
+ *
+ * Dogfood note 2026-05-24: `plan` was originally budgeted at 3 tool calls
+ * on the assumption that the model would issue 1-2 read calls + emit the
+ * plan. Real-world traces show 3-4 glob/grep calls disappear into repo
+ * surveying alone — the model produces zero plan output and the artifact
+ * file says `[budget_exhausted]`. Bumping to 8 buys breathing room for
+ * decently-sized repos while still bounding cost. plan stays read-only at
+ * the sentinel level — the call-count change does not weaken safety.
+ */
+export const defaultEngineBudgets = {
+    code: { maxToolCalls: 20, maxTokens: 50_000 },
+    explain: { maxToolCalls: 5, maxTokens: 20_000 },
+    fix: { maxToolCalls: 20, maxTokens: 50_000 },
+    plan: { maxToolCalls: 8, maxTokens: 30_000 },
+    build: { maxToolCalls: 30, maxTokens: 80_000 },
+};
+/**
+ * Message role shape — mirrors OpenAI's chat-completions schema with a
+ * `tool` role for tool result frames. Pugi's runtime proxy maps these to
+ * AnvilBridgeMessage (which has the same shape modulo `name` carrying the
+ * tool_call_id for tool frames).
+ */
+export const engineLoopMessageSchema = z.object({
+    role: z.enum(['system', 'user', 'assistant', 'tool']),
+    content: z.string(),
+    /** Optional model-emitted tool calls when `role === 'assistant'`. */
+    toolCalls: z
+        .array(z.object({
+        id: z.string().min(1),
+        name: z.string().min(1),
+        arguments: z.string(),
+    }))
+        .optional(),
+    /** Tool call id this `tool` frame is responding to. */
+    toolCallId: z.string().optional(),
+    /** Tool name this `tool` frame is responding to. */
+    toolName: z.string().optional(),
+});
+/**
+ * OpenAI-compatible tool definition. The CLI builds this from
+ * `toolRegistry`. `parameters` is a JSON Schema object — we keep it as
+ * `unknown` here so the SDK stays JSON-Schema-version-agnostic.
+ */
+export const engineLoopToolSchema = z.object({
+    name: z.string().min(1),
+    description: z.string().min(1),
+    parameters: z.unknown(),
+});
+/**
+ * Core driver. Pure transport-agnostic loop:
+ *
+ *   1. Prepend system + user messages.
+ *   2. Call `client.send(transcript, tools)`.
+ *   3. If response is `text` → return completed.
+ *   4. If response is `tool_use` → execute each call via `executor`,
+ *      append the assistant + tool frames to the transcript, increment
+ *      counters, loop.
+ *   5. After every turn check budgets; bail if exceeded.
+ *
+ * No filesystem access lives here — the CLI's `engine-tools.ts` is the
+ * sole place that touches disk. Keeping the loop pure makes it trivial
+ * to unit-test with a fixture client.
+ */
+export async function runEngineLoop(input) {
+    const transcript = [
+        { role: 'system', content: input.systemPrompt },
+        { role: 'user', content: input.userPrompt },
+    ];
+    let toolCallCount = 0;
+    let tokensUsed = 0;
+    let turnsUsed = 0;
+    while (true) {
+        if (input.signal?.aborted) {
+            return {
+                status: 'failed',
+                finalText: '',
+                toolCallCount,
+                tokensUsed,
+                turnsUsed,
+                reason: 'aborted',
+            };
+        }
+        input.hooks?.onTurnStart?.(turnsUsed, transcript.length);
+        const response = await input.client.send(transcript, input.tools, {
+            personaSlug: input.personaSlug,
+            maxTokens: Math.max(1024, input.budget.maxTokens - tokensUsed),
+            temperature: input.temperature,
+            signal: input.signal,
+        });
+        turnsUsed += 1;
+        input.hooks?.onTurnComplete?.(turnsUsed - 1, response);
+        if (response.stop === 'error') {
+            return {
+                status: 'failed',
+                finalText: '',
+                toolCallCount,
+                tokensUsed,
+                turnsUsed,
+                reason: `${response.code}: ${response.message}`,
+            };
+        }
+        // Token accounting. Anvil's chat-completions response normally
+        // carries `usage.totalTokens`; older builds and some providers
+        // (notably the OpenRouter passthrough on `tool_use` turns) return
+        // 0. Without a fallback the budget gate would never trip, which
+        // is the exact failure Code Reviewer P2 retro 2026-05-23 flagged.
+        // We use a `transcript-chars / 4` heuristic — coarse but in the
+        // right order of magnitude for English/TS text, and the gate's
+        // job is to bound runaway loops, not to bill cents.
+        if (response.tokensUsed > 0) {
+            tokensUsed += response.tokensUsed;
+        }
+        else {
+            const heuristicChars = transcript.reduce((sum, m) => sum + m.content.length, 0) +
+                (response.stop === 'text'
+                    ? response.content.length
+                    : response.assistantMessage.content.length);
+            tokensUsed = Math.ceil(heuristicChars / 4);
+        }
+        if (tokensUsed > input.budget.maxTokens) {
+            return {
+                status: 'budget_exhausted',
+                finalText: response.stop === 'text' ? response.content : '',
+                toolCallCount,
+                tokensUsed,
+                turnsUsed,
+                reason: `token budget exceeded (${tokensUsed} > ${input.budget.maxTokens})`,
+            };
+        }
+        if (response.stop === 'text') {
+            return {
+                status: 'completed',
+                finalText: response.content,
+                toolCallCount,
+                tokensUsed,
+                turnsUsed,
+            };
+        }
+        // tool_use — append assistant message verbatim then execute each call.
+        transcript.push(response.assistantMessage);
+        const calls = response.assistantMessage.toolCalls ?? [];
+        if (calls.length === 0) {
+            // Model claimed tool_use but produced no calls — treat as final text
+            // with an empty answer so we do not loop forever.
+            return {
+                status: 'completed',
+                finalText: response.assistantMessage.content,
+                toolCallCount,
+                tokensUsed,
+                turnsUsed,
+            };
+        }
+        for (const call of calls) {
+            if (toolCallCount >= input.budget.maxToolCalls) {
+                return {
+                    status: 'budget_exhausted',
+                    finalText: '',
+                    toolCallCount,
+                    tokensUsed,
+                    turnsUsed,
+                    reason: `tool call budget exhausted (${toolCallCount} >= ${input.budget.maxToolCalls})`,
+                };
+            }
+            toolCallCount += 1;
+            input.hooks?.onToolCall?.(call);
+            try {
+                const result = await input.executor({
+                    name: call.name,
+                    arguments: call.arguments,
+                    callId: call.id,
+                });
+                input.hooks?.onToolResult?.({ id: call.id, name: call.name }, { ok: true, content: result });
+                transcript.push({
+                    role: 'tool',
+                    content: result,
+                    toolCallId: call.id,
+                    toolName: call.name,
+                });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                input.hooks?.onToolResult?.({ id: call.id, name: call.name }, { ok: false, error: message });
+                // Plan-mode refusals surface as a distinct outcome so the CLI can
+                // mark the run blocked rather than failed. The executor MUST raise
+                // an Error whose message starts with the sentinel below for plan
+                // refusals; any other thrown error is treated as a recoverable
+                // tool error and fed back to the model.
+                if (message.startsWith('PLAN_MODE_REFUSED:')) {
+                    return {
+                        status: 'tool_refused',
+                        finalText: '',
+                        toolCallCount,
+                        tokensUsed,
+                        turnsUsed,
+                        reason: message,
+                    };
+                }
+                transcript.push({
+                    role: 'tool',
+                    content: `error: ${message}`,
+                    toolCallId: call.id,
+                    toolName: call.name,
+                });
+            }
+        }
+    }
+}
+/* ------------------------------------------------------------------ */
+/* Wire format: POST /api/pugi/engine                                  */
+/* ------------------------------------------------------------------ */
+/**
+ * Server wire request — what `AnvilEngineLoopClient` POSTs to
+ * `POST /api/pugi/engine` on every turn. Sprint 2E proxy endpoint
+ * mirrors this Zod schema admin-api-side so the contract has a single
+ * source of truth.
+ *
+ * Required fields:
+ *   - `messages` — transcript so far (system + user + assistant + tool).
+ *   - `tools` — tool registry the runtime is allowed to invoke for this
+ *     turn. The CLI strips mutating tools when `command === 'plan'`;
+ *     the server defends against forged bodies via a second-layer check.
+ *   - `personaSlug` — persona to invoke; the server uses this for
+ *     persona system-prompt injection + consensus-tier resolution.
+ *
+ * Optional fields (the CLI only supplies a subset today; the schema
+ * accepts every documented knob so Sprint 3+ tooling can opt in
+ * without a contract change):
+ *   - `command` — engine command kind. When present the server picks a
+ *     per-command model from `PUGI_ENGINE_MODEL_<COMMAND>` env or
+ *     hardcoded default. When absent the server falls back to the
+ *     persona's `defaultModel`.
+ *   - `model` — explicit model override. Wins over `command` resolution.
+ *     Useful for tier-aware operators who want to pin a model.
+ *   - `maxTokens` — upper bound on completion size for this turn.
+ *   - `temperature` — sampling temperature for this turn.
+ */
+export const engineLoopServerRequestSchema = z.object({
+    personaSlug: z.string().min(1).max(128),
+    messages: z.array(engineLoopMessageSchema).min(1),
+    tools: z.array(engineLoopToolSchema).max(64),
+    command: engineCommandKindSchema.optional(),
+    model: z.string().min(1).max(256).optional(),
+    maxTokens: z.number().int().positive().max(200_000).optional(),
+    temperature: z.number().min(0).max(2).optional(),
+});
+/**
+ * Server wire response — what the admin-api Sprint 2E endpoint returns
+ * for every turn. The shape matches what `AnvilEngineLoopClient` parses:
+ *
+ *   - `stop === 'text'` — model produced a final answer, loop terminates.
+ *   - `stop === 'tool_use'` — model emitted `toolCalls`, CLI executes
+ *     them locally and feeds results back next turn.
+ *   - `stop === 'length'` — completion truncated by `maxTokens`. The
+ *     CLI treats this as final text and stops; surface partial content.
+ */
+export const engineLoopServerResponseSchema = z.object({
+    stop: z.enum(['text', 'tool_use', 'length']),
+    content: z.string(),
+    toolCalls: z
+        .array(z.object({
+        id: z.string().min(1),
+        name: z.string().min(1),
+        arguments: z.string(),
+    }))
+        .optional(),
+    tokensUsed: z.number().int().nonnegative(),
+    model: z.string().min(1),
+});
+//# sourceMappingURL=engine-loop.js.map