@pugi/cli 0.1.0-beta.4 → 0.1.0-beta.40

package/dist/core/engine/anvil-client.js

@@ -1,3 +1,10 @@
+// PR-CLI-SERVER-VERSION-HANDSHAKE (#225). The interceptor stamps the
+// outbound X-Pugi-Cli-Version header, inspects the inbound recommended/
+// server-version headers, and throws PugiCliUpgradeRequiredError on a
+// 426 server response. The top-level catch in `runtime/cli.ts` /
+// `index.ts` renders the upgrade message and exits 1.
+import { assertNotUpgradeRequired, injectClientVersionHeader, inspectVersionResponse, } from '../transport/version-interceptor.js';
+import { PUGI_CLI_VERSION } from '../../runtime/version.js';
 /**
  * Anvil-backed engine loop client.
  *
@@ -54,23 +61,77 @@ export class AnvilEngineLoopClient {
             options.signal.addEventListener('abort', onAbort);
         const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs);
         try {
+            // PR-CLI-SERVER-VERSION-HANDSHAKE (#225). Stamp the outbound
+            // X-Pugi-Cli-Version header so the admin-api middleware can
+            // decide whether to honour, soft-warn, or 426 this request.
+            const outboundHeaders = injectClientVersionHeader({
+                'content-type': 'application/json',
+                authorization: `Bearer ${this.config.apiKey}`,
+                'user-agent': 'pugi-cli/0.0.1',
+            }, PUGI_CLI_VERSION);
             const res = await fetch(url, {
                 method: 'POST',
-                headers: {
-                    'content-type': 'application/json',
-                    authorization: `Bearer ${this.config.apiKey}`,
-                    'user-agent': 'pugi-cli/0.0.1',
-                },
+                headers: outboundHeaders,
                 body: JSON.stringify({
                     personaSlug: options.personaSlug,
                     messages,
                     tools,
                     maxTokens: options.maxTokens,
                     temperature: options.temperature,
+                    // β1 (audit E2): the admin-api `EngineRequestDto` accepts
+                    // these optional fields (see `pugi-engine.controller.ts:230`
+                    // EngineRequestDto schema). Before this fix the CLI dropped
+                    // them, which forced the controller to fall back to legacy
+                    // per-persona resolution + emit `command="(none)"` in its
+                    // structured logs. `undefined` keys are stripped by
+                    // `JSON.stringify` so the payload stays clean for fixture
+                    // clients that exact-match the body shape.
+                    command: options.command,
+                    // β1a r1: `tag` is `EngineDispatchTag` object shape now —
+                    // `JSON.stringify` serialises it as `{tag, priority?,
+                    // budget_hint?}` matching `EngineDispatchTagDto`. Previously
+                    // this was a bare string and the server's `IsIn` validator
+                    // rejected every payload with HTTP 400.
+                    tag: options.tag,
+                    model: options.model,
                 }),
                 signal: controller.signal,
             });
             const text = await res.text();
+            // PR-CLI-SERVER-VERSION-HANDSHAKE: cache server-recommended +
+            // server-version headers so UpdateBanner / `pugi doctor` can
+            // surface them, then short-circuit on 426 by throwing
+            // PugiCliUpgradeRequiredError. The throw bubbles to the
+            // top-level catch in index.ts which renders the upgrade banner.
+            // The getter shim handles both real `Response` (`.headers.get`)
+            // and minimal fixture/stub responses (`.headers?.[name]`) so
+            // existing transport tests that mock `fetch` with `{status, text}`
+            // don't need to grow a Headers polyfill just to keep passing.
+            //
+            // Cache poison guard: skip the inspect step on 426. A hostile
+            // upstream (proxy with a compromised cert pin, or a transient MITM
+            // on a coffee-shop network) could otherwise forge an
+            // `X-Pugi-Cli-Upgrade-Recommended` header alongside a 426 status
+            // and poison `cachedServerRecommendation` for the rest of the REPL
+            // session — `UpdateBanner` would then surface attacker-chosen
+            // version strings to the operator. The 426 body still carries the
+            // legitimate `recommendedVersion` field, which assertNotUpgrade-
+            // Required parses + throws with, so the operator-facing banner
+            // remains accurate via the error path.
+            if (res.status !== 426) {
+                inspectVersionResponse((name) => {
+                    const h = res.headers;
+                    if (h && typeof h.get === 'function') {
+                        return h.get(name);
+                    }
+                    if (h && typeof h === 'object') {
+                        const lowered = h[name.toLowerCase()];
+                        return lowered ?? null;
+                    }
+                    return null;
+                });
+            }
+            assertNotUpgradeRequired(res.status, text, PUGI_CLI_VERSION);
             if (res.status === 200) {
                 try {
                     const json = JSON.parse(text);
@@ -119,6 +180,55 @@ export class AnvilEngineLoopClient {
                 };
             }
             if (res.status === 401 || res.status === 403) {
+                // 403 has two distinct causes:
+                //   1. genuinely invalid / expired token (auth_missing) — the
+                //      old default.
+                //   2. tenant authenticated successfully but the privacy mode
+                //      (strict / balanced policy) refused upstream LLM dispatch.
+                //      The admin-api returns
+                //      `{ code: 'privacy_strict_upstream_blocked', mode, model,
+                //         message: '...switch via pugi config set privacy=...' }`.
+                //      Reported as `auth_missing` the user runs `pugi login`
+                //      again, which does nothing — the actual fix is a privacy-
+                //      mode change. Parse the body and route accordingly.
+                // (2026-05-27 P0.3 — dogfood surfaced this on /api/pugi/engine
+                // for a strict-mode tenant; see memory feedback_no_fake_dispatch_promises
+                // for the broader "misleading error" pattern.)
+                try {
+                    const parsed = text ? JSON.parse(text) : null;
+                    // 2026-05-27 dogfood cycle 2: distinct error code for the
+                    // infra-side "PII scrubber down" case. Previously the engine
+                    // server returned `privacy_strict_upstream_blocked` here even
+                    // when the tenant was on BALANCED (the scrubber crash forced
+                    // a fail-closed). Operators chased the wrong fix ("switch
+                    // privacy") for hours. Server now emits
+                    // `pii_scrubber_unavailable` — surface a distinct remediation
+                    // that points at the infra side, not the operator's privacy
+                    // posture.
+                    if (parsed?.code === 'pii_scrubber_unavailable') {
+                        return {
+                            stop: 'error',
+                            code: 'privacy_blocked',
+                            message: parsed.message ?? 'PII scrubber unavailable; privacy filter refused dispatch.',
+                            remediation: 'Infra-side issue (not your tenant privacy mode). Wait for ops to restore ' +
+                                'the PiiScrubberService, OR temporarily switch your tenant to permissive via ' +
+                                '`pugi config set privacy=permissive`.',
+                        };
+                    }
+                    if (parsed?.code === 'privacy_strict_upstream_blocked' || parsed?.code === 'privacy_blocked') {
+                        return {
+                            stop: 'error',
+                            code: 'privacy_blocked',
+                            message: parsed.message ?? 'Tenant privacy mode forbids upstream LLM dispatch.',
+                            remediation: 'pugi config set privacy=balanced — OR configure a self-hosted Anvil model.',
+                        };
+                    }
+                }
+                catch {
+                    // Body not JSON — fall through to the generic auth_missing
+                    // branch below; the 200-char text echo on `failed` will at
+                    // least give the operator the raw response to triage.
+                }
                 return {
                     stop: 'error',
                     code: 'auth_missing',

package/dist/core/engine/budgets.js

@@ -0,0 +1,98 @@
+/**
+ * β1 defaults. Source of truth for the per-command budget envelope.
+ * The runtime is allowed to look these up directly (no need to round
+ * trip through settings.json when no override is in play).
+ *
+ * 2026-05-28 bump (post-Wave-7 hooks-v2 + 6-perm-modes + auto-classifier
+ * added ~12K tokens of system-prompt + tools-schema overhead per turn):
+ * `code` 30k → 80k и `fix` 30k → 50k so a single-file refactor on a
+ * 1000-line source file no longer exhausts the budget on turn 2.
+ * Empirical: smoke `pugi code "сделай snake.html"` on beta.37 burned
+ * 36k/30k after 2 tool calls; beta.36 same task closed in 8k. The Wave-7
+ * additions are good (Claude Code parity), but the budget cap did not move with
+ * them. Claude Code's `code` default is ~80k; matching that restores headroom.
+ */
+export const beta1DefaultBudgets = {
+    fix: { maxTokens: 50_000, maxToolCalls: 20 },
+    code: { maxTokens: 80_000, maxToolCalls: 20 },
+    build: { maxTokens: 200_000, maxToolCalls: 30 },
+    plan: { maxTokens: 200_000, maxToolCalls: 8 },
+    explain: { maxTokens: 20_000, maxToolCalls: 5 },
+    review_triple: { maxTokens: 100_000, maxToolCalls: 10 },
+};
+/**
+ * Hard upper bounds. Anything above this is treated as user error
+ * (likely a typo or misplaced decimal) and rejected by
+ * `assertBudgetWithinTier`. Stops a careless settings.json edit from
+ * silently authorising a 100M-token run.
+ */
+export const HARD_MAX_TOKENS = 5_000_000;
+export const HARD_MAX_TOOL_CALLS = 500;
+/**
+ * Compute the effective budget for a given command, applying:
+ *   1. β1 defaults
+ *   2. settings.json `budgets.<command>` partial overrides
+ *   3. task-level override (caller-provided, e.g. CLI `--max-tokens`)
+ *
+ * Throws `BudgetConfigError` when the resolved budget exceeds the
+ * HARD_MAX_* caps so misconfigured settings.json fails fast.
+ */
+export function resolveBudget(command, settings, override) {
+    const base = beta1DefaultBudgets[command];
+    const settingsBudget = readSettingsBudget(settings, command);
+    const resolved = {
+        maxTokens: override?.maxTokens ??
+            settingsBudget?.maxTokens ??
+            base.maxTokens,
+        maxToolCalls: override?.maxToolCalls ??
+            settingsBudget?.maxToolCalls ??
+            base.maxToolCalls,
+    };
+    assertBudgetWithinTier(command, resolved);
+    return resolved;
+}
+export class BudgetConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'BudgetConfigError';
+    }
+}
+export function assertBudgetWithinTier(command, budget) {
+    if (!Number.isFinite(budget.maxTokens) || budget.maxTokens <= 0) {
+        throw new BudgetConfigError(`budget[${command}].maxTokens must be a positive number, got ${budget.maxTokens}`);
+    }
+    if (!Number.isFinite(budget.maxToolCalls) || budget.maxToolCalls <= 0) {
+        throw new BudgetConfigError(`budget[${command}].maxToolCalls must be a positive number, got ${budget.maxToolCalls}`);
+    }
+    if (budget.maxTokens > HARD_MAX_TOKENS) {
+        throw new BudgetConfigError(`budget[${command}].maxTokens=${budget.maxTokens} exceeds hard cap ${HARD_MAX_TOKENS}`);
+    }
+    if (budget.maxToolCalls > HARD_MAX_TOOL_CALLS) {
+        throw new BudgetConfigError(`budget[${command}].maxToolCalls=${budget.maxToolCalls} exceeds hard cap ${HARD_MAX_TOOL_CALLS}`);
+    }
+}
+/**
+ * Pull a settings.json budget override for the given command, with
+ * defensive typing. `PugiSettings` does not yet declare `budgets`
+ * formally (β1 is the first sprint to land it) so we cast via unknown
+ * and validate each field at the boundary.
+ */
+function readSettingsBudget(settings, command) {
+    if (!settings)
+        return undefined;
+    const root = settings.budgets;
+    if (!root || typeof root !== 'object' || Array.isArray(root))
+        return undefined;
+    const map = root;
+    const entry = map[command];
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+        return undefined;
+    const e = entry;
+    const out = {};
+    if (typeof e['maxTokens'] === 'number')
+        out.maxTokens = e['maxTokens'];
+    if (typeof e['maxToolCalls'] === 'number')
+        out.maxToolCalls = e['maxToolCalls'];
+    return out;
+}
+//# sourceMappingURL=budgets.js.map

package/dist/core/engine/context-prefix.js

@@ -0,0 +1,155 @@
+/** Hard cap on the rendered `<context>` block, bytes. */
+export const CONTEXT_PREFIX_MAX_BYTES = 5 * 1024;
+/** Hard cap on working-set entries surfaced in the prefix. */
+export const CONTEXT_PREFIX_MAX_WORKING_SET = 50;
+/** Hard cap on per-dir markdown files surfaced inline. */
+export const CONTEXT_PREFIX_MAX_MARKDOWN = 3;
+/** Per-markdown-file inline excerpt cap, bytes. Keeps any one file from dominating. */
+export const CONTEXT_PREFIX_MAX_PER_MARKDOWN_BYTES = 1024;
+/**
+ * Build the `<context>` block. Always returns a result — when there
+ * is nothing to surface (no cwd hint, no working set, no per-dir
+ * files), returns `{ block: '', bytes: 0, truncated: false, counts: ... }`
+ * so the caller can short-circuit the splice cleanly.
+ *
+ * Determinism: same input always produces byte-identical output. The
+ * working-set order comes from the caller's summary; we preserve it
+ * verbatim. Per-dir files are sorted by `distanceFromCwd` ascending
+ * (closest first) so two equal `TraversedMarkdown` arrays produce
+ * identical blocks.
+ */
+export function buildContextPrefix(input) {
+    const lines = [];
+    let bytes = 0;
+    let truncated = false;
+    // Walk a write-then-measure loop so we never overflow the byte cap.
+    // Each push checks budget; when full, set `truncated = true` and
+    // stop. The opener / closer tags always fit (small) — we reserve
+    // their byte cost up-front from the budget.
+    const opener = '<context>';
+    const closer = '</context>';
+    const reservedTagBytes = Buffer.byteLength(opener, 'utf8') + 1 + Buffer.byteLength(closer, 'utf8') + 1;
+    let budget = CONTEXT_PREFIX_MAX_BYTES - reservedTagBytes;
+    if (budget < 0) {
+        return {
+            block: '',
+            bytes: 0,
+            truncated: false,
+            counts: {
+                workingSetIncluded: 0,
+                workingSetTotal: input.workingSet?.length ?? 0,
+                markdownIncluded: 0,
+                markdownTotal: input.traversedMarkdown?.length ?? 0,
+            },
+        };
+    }
+    const pushLine = (line) => {
+        const lineBytes = Buffer.byteLength(line, 'utf8') + 1; // newline
+        if (lineBytes > budget) {
+            truncated = true;
+            return false;
+        }
+        lines.push(line);
+        budget -= lineBytes;
+        bytes += lineBytes;
+        return true;
+    };
+    // cwd — always cheap, always first.
+    pushLine(`cwd: ${input.cwdRelative || '.'}`);
+    // intent hint, if provided.
+    if (input.intentHint) {
+        pushLine(`intent: ${input.intentHint}`);
+    }
+    // Working set — render `open-files:` only when there is at least one entry.
+    const wsTotal = input.workingSet?.length ?? 0;
+    let wsIncluded = 0;
+    if (wsTotal > 0 && input.workingSet) {
+        const wsCap = Math.min(CONTEXT_PREFIX_MAX_WORKING_SET, wsTotal);
+        pushLine('open-files:');
+        for (let i = 0; i < wsCap; i += 1) {
+            const entry = input.workingSet[i];
+            if (!entry)
+                continue;
+            const ok = pushLine(`  - ${entry.absPath}`);
+            if (!ok)
+                break;
+            wsIncluded += 1;
+        }
+        if (wsTotal > wsCap) {
+            pushLine(`  ... (+${wsTotal - wsCap} more)`);
+            truncated = truncated || true;
+        }
+    }
+    // Per-dir markdown — closest-first, max 3, each capped to 1 KB excerpt.
+    const mdTotal = input.traversedMarkdown?.length ?? 0;
+    let mdIncluded = 0;
+    if (mdTotal > 0 && input.traversedMarkdown) {
+        const sorted = [...input.traversedMarkdown].sort((a, b) => a.distanceFromCwd - b.distanceFromCwd);
+        const top = sorted.slice(0, CONTEXT_PREFIX_MAX_MARKDOWN);
+        if (top.length > 0) {
+            pushLine('per-dir-conventions:');
+            for (const md of top) {
+                // Header line names the source file for traceability.
+                const header = `  [${md.resolvedPath}]`;
+                if (!pushLine(header))
+                    break;
+                // Excerpt: cap to 1 KB, single-line collapse (replace newlines
+                // with " | " so the YAML-ish block stays parseable by humans).
+                const excerpt = excerpt1KB(md.content);
+                // Indent two spaces so it nests under the file header.
+                const indented = excerpt.split('\n').map((l) => `    ${l}`).join('\n');
+                if (!pushLine(indented))
+                    break;
+                mdIncluded += 1;
+            }
+            if (mdTotal > top.length) {
+                pushLine(`  ... (+${mdTotal - top.length} more files; closest-3 shown)`);
+                truncated = truncated || true;
+            }
+        }
+    }
+    if (lines.length === 0) {
+        return {
+            block: '',
+            bytes: 0,
+            truncated: false,
+            counts: {
+                workingSetIncluded: 0,
+                workingSetTotal: wsTotal,
+                markdownIncluded: 0,
+                markdownTotal: mdTotal,
+            },
+        };
+    }
+    const block = [opener, ...lines, closer].join('\n');
+    const totalBytes = Buffer.byteLength(block, 'utf8');
+    return {
+        block,
+        bytes: totalBytes,
+        truncated,
+        counts: {
+            workingSetIncluded: wsIncluded,
+            workingSetTotal: wsTotal,
+            markdownIncluded: mdIncluded,
+            markdownTotal: mdTotal,
+        },
+    };
+}
+/**
+ * Splice a built context block onto the front of a user message.
+ * Empty block → message returned verbatim (no leading blank line, no
+ * empty `<context>` tag).
+ */
+export function spliceContextPrefix(block, userMessage) {
+    if (block.length === 0)
+        return userMessage;
+    return `${block}\n\n${userMessage}`;
+}
+function excerpt1KB(content) {
+    const capped = content.length <= CONTEXT_PREFIX_MAX_PER_MARKDOWN_BYTES
+        ? content
+        : content.slice(0, CONTEXT_PREFIX_MAX_PER_MARKDOWN_BYTES);
+    // Trim trailing newlines so the YAML-ish render stays tight.
+    return capped.replace(/\s+$/g, '');
+}
+//# sourceMappingURL=context-prefix.js.map

package/dist/core/engine/intent.js

@@ -0,0 +1,260 @@
+/**
+ * β5a P1+P6 — CLI-side intent classifier: definitional vs operational.
+ *
+ * Background (CEO 2026-05-26 quality gate ≥80% vs Claude Code): the
+ * α7.X Phase 2 comparative eval surfaced a high-frequency Pugi loss
+ * mode where the model interpreted EVERY user message as an operational
+ * task and reached for tools. Concrete reproducer: when an operator
+ * asks "What is grep?", pre-β5a Pugi would issue a `bash` tool call
+ * (`man grep`, `grep --help`, sometimes a `glob` over `**`) instead
+ * of answering explanatorily. Claude Code answers in one paragraph,
+ * no tool calls. That single failure mode costs ~3 of the 23
+ * comparative fixtures.
+ *
+ * Root cause: the system prompt advertises tools as the primary way
+ * to make progress; without a counter-instruction, the model defaults
+ * to tools even for pure-knowledge questions. Prompt v2 (P6) adds
+ * definitional EXAMPLES in the prompt; this classifier is the
+ * deterministic safety net that flags definitional questions BEFORE
+ * the engine loop fires so we can:
+ *
+ *   1. Inject a one-line `<intent>definitional</intent>` marker into
+ *      the user message that the prompt explicitly teaches the model
+ *      to honour ("when you see this marker, answer in prose, do not
+ *      call tools").
+ *   2. Make the marker visible in the SSE stream so cabinet UI / eval
+ *      reports can show why a tool-free answer was correct.
+ *
+ * The classifier is intentionally simple — pure regex/keyword scoring,
+ * sub-millisecond, no LLM call, no fs reads. It must be:
+ *
+ *   - Deterministic (same input always → same output, the eval relies
+ *     on this for stable comparison runs).
+ *   - Conservative on the operational side. False-positive
+ *     definitional is mostly harmless (the model can still call tools
+ *     if needed — the marker is a hint, not a hard gate). False-
+ *     positive operational on a definitional question is what we are
+ *     fixing — biggest loss surface.
+ *
+ * Coverage: EN + RU (the two primary CLI languages per
+ * `feedback_chat_always_russian_no_drift.md`). Uses lowercase compare
+ * for keyword matches, anchored regex for prefix patterns. Stop-word
+ * agnostic — the question "what is X?" is the dominant template and
+ * survives every common stop-word filter.
+ *
+ * Out of scope: deciding WHICH tool to call when operational. That
+ * is the model's job. We only decide whether to suggest "no tools
+ * needed" up front.
+ */
+/**
+ * EN + RU definitional question openers. Anchored at start-of-string
+ * (after trim + lower) so a sentence-medial "what is" inside a larger
+ * operational sentence does not flip the verdict. Each entry is
+ * either a literal prefix or a RegExp matched against the lowercase
+ * trimmed input.
+ *
+ * Boundary policy: JS `\b` is ASCII-only — Cyrillic letters do not
+ * count as word characters, so `^объясни\b` matches "объясни" against
+ * a space follower BUT fails when the next char is a Cyrillic letter
+ * (which it never is at this position) and surprisingly fails on
+ * "объясни X" because `\b` between `и` (non-word in ASCII regex) and
+ * ` ` (non-word) is never a boundary. We use an explicit
+ * `(?=\s|$|[!?.,])` lookahead so Cyrillic prefixes match the same
+ * way ASCII ones do.
+ */
+const WB = '(?=\\s|$|[!?.,;:])';
+const DEFINITIONAL_PATTERNS = [
+    // EN
+    new RegExp(`^what\\s+(is|are|does|do)${WB}`),
+    new RegExp(`^who\\s+(is|are|was|were)${WB}`),
+    new RegExp(`^when\\s+(is|was|does|did)${WB}`),
+    new RegExp(`^where\\s+(is|are|does|did)${WB}`),
+    new RegExp(`^why\\s+(is|are|does|did)${WB}`),
+    new RegExp(`^how\\s+(does|do|did)\\s+\\S+\\s+work${WB}`),
+    new RegExp(`^explain\\s+(what|why|how)${WB}`),
+    new RegExp(`^define${WB}`),
+    new RegExp(`^tell\\s+me\\s+(what|about)${WB}`),
+    new RegExp(`^can\\s+you\\s+(tell\\s+me|explain|describe)${WB}`),
+    // RU
+    new RegExp(`^что\\s+(такое|это|значит)${WB}`),
+    new RegExp(`^кто\\s+(такой|такая|такие|это)${WB}`),
+    new RegExp(`^как\\s+работает${WB}`),
+    new RegExp(`^зачем${WB}`),
+    new RegExp(`^почему${WB}`),
+    new RegExp(`^объясни${WB}`),
+    new RegExp(`^расскажи\\s+(про|о|об)${WB}`),
+];
+/**
+ * Operational verbs that strongly imply a tool-use task. A match
+ * here overrides a weak definitional signal (e.g. "explain the bug
+ * and fix it" -> operational, not definitional).
+ */
+const OPERATIONAL_KEYWORDS = [
+    // EN
+    'fix', 'patch', 'add', 'remove', 'delete', 'create', 'build',
+    'implement', 'refactor', 'rename', 'migrate', 'deploy', 'install',
+    'run', 'test', 'debug', 'investigate', 'open a pr', 'commit',
+    'push', 'merge', 'review my', 'write a', 'write the', 'replace',
+    'update the', 'modify', 'edit', 'change the',
+    // RU
+    'почини', 'исправь', 'добавь', 'удали', 'создай', 'собери',
+    'реализуй', 'отрефактори', 'переименуй', 'мигрируй', 'задеплой',
+    'установи', 'запусти', 'протестируй', 'отладь', 'разберись',
+    'закоммить', 'смержи', 'напиши', 'замени', 'обнови', 'измени',
+    'отредактируй',
+];
+/**
+ * File-path / identifier signals that, when combined with any verb,
+ * push us toward operational regardless of question framing. A bare
+ * "what is" question that names a file (`what is in apps/admin-api/
+ * src/main.ts?`) reads as operational — the operator wants the file
+ * inspected, not a dictionary definition.
+ */
+const PATH_SIGNAL = /[./][a-z0-9_-]+\.(ts|tsx|js|jsx|json|md|yaml|yml|sh|py|prisma|css|scss|html|sql|env)\b/i;
+const CODE_SYMBOL_SIGNAL = /\b[A-Z][a-zA-Z0-9]+\.(prototype|find|create|run|build|register)\b/;
+/**
+ * Classify a single user message. Returns one of:
+ *
+ *   - `definitional` — high confidence the operator wants knowledge,
+ *     not edits. Prompt the model to answer in prose, no tools.
+ *   - `operational` — verbs / paths / explicit "fix X" framing.
+ *     Model decides tools as normal.
+ *   - `ambiguous` — neither side won decisively. The model gets no
+ *     extra hint; default behaviour applies. The marker is NOT
+ *     injected for ambiguous to keep the prompt cache stable.
+ *
+ * Confidence: rough heuristic — `1.0` when a pattern matched cleanly
+ * with no opposing signal; lower when both sides matched.
+ *
+ * Pure function, no side effects.
+ */
+export function classifyIntent(rawMessage) {
+    const trimmed = rawMessage.trim();
+    if (trimmed.length === 0) {
+        return {
+            intent: 'ambiguous',
+            confidence: 0,
+            matched: [],
+            rationale: 'empty input',
+        };
+    }
+    const lower = trimmed.toLowerCase();
+    const matched = [];
+    let definitionalScore = 0;
+    let operationalScore = 0;
+    let hasDefinitionalOpener = false;
+    for (const pattern of DEFINITIONAL_PATTERNS) {
+        if (pattern.test(lower)) {
+            // Three points — heavier than a single operational keyword
+            // match (two) so a definitional opener cannot be flipped by
+            // ONE incidental verb appearing as part of a noun phrase
+            // (e.g. "what does prisma MIGRATE do" — the verb "migrate"
+            // here names a subcommand, not an action the operator wants
+            // executed). Operational still wins when multiple operational
+            // signals stack (verb + path + imperative).
+            definitionalScore += 3;
+            matched.push(`def:${pattern.source}`);
+            hasDefinitionalOpener = true;
+            break; // a single anchored prefix is enough
+        }
+    }
+    // ?-terminated short utterance with no verbs is a strong
+    // definitional signal even without a what/who/why opener.
+    if (lower.endsWith('?') && lower.split(/\s+/).length <= 6) {
+        definitionalScore += 1;
+        matched.push('def:short-question');
+    }
+    // A definitional opener PLUS an explicit `?` terminator together
+    // form a pure question. Verbs mentioned inside ("what does prisma
+    // MIGRATE do?") are sub-noun-phrase references, not commands —
+    // boost definitional so the verb-keyword scoring below cannot tie.
+    if (hasDefinitionalOpener && lower.endsWith('?')) {
+        definitionalScore += 2;
+        matched.push('def:opener+question');
+    }
+    for (const keyword of OPERATIONAL_KEYWORDS) {
+        if (lower.includes(keyword)) {
+            operationalScore += 2;
+            matched.push(`op:${keyword}`);
+            break;
+        }
+    }
+    if (PATH_SIGNAL.test(trimmed)) {
+        operationalScore += 1;
+        matched.push('op:path-signal');
+    }
+    if (CODE_SYMBOL_SIGNAL.test(trimmed)) {
+        operationalScore += 1;
+        matched.push('op:code-symbol');
+    }
+    // Imperative ("do X") without any question framing is operational.
+    if (!lower.endsWith('?') && /^(please\s+)?(do|run|make|let'?s)\b/.test(lower)) {
+        operationalScore += 1;
+        matched.push('op:imperative');
+    }
+    // Decision.
+    if (definitionalScore === 0 && operationalScore === 0) {
+        return {
+            intent: 'ambiguous',
+            confidence: 0,
+            matched,
+            rationale: 'no rules matched',
+        };
+    }
+    if (definitionalScore > operationalScore + 1) {
+        return {
+            intent: 'definitional',
+            confidence: clamp01(definitionalScore / (definitionalScore + operationalScore + 1)),
+            matched,
+            rationale: `definitional ${definitionalScore} > operational ${operationalScore}`,
+        };
+    }
+    if (operationalScore >= definitionalScore) {
+        return {
+            intent: 'operational',
+            confidence: clamp01(operationalScore / (definitionalScore + operationalScore + 1)),
+            matched,
+            rationale: `operational ${operationalScore} >= definitional ${definitionalScore}`,
+        };
+    }
+    // Definitional won but margin is tight — keep but lower confidence.
+    return {
+        intent: 'definitional',
+        confidence: clamp01(definitionalScore / (definitionalScore + operationalScore + 1)) * 0.7,
+        matched,
+        rationale: `definitional ${definitionalScore} marginal over operational ${operationalScore}`,
+    };
+}
+/**
+ * Marker the engine wraps the user message in when the classifier
+ * picked `definitional`. The system prompt v2 teaches the model to
+ * answer in prose when it sees this marker.
+ *
+ * Format choice: angle-bracket pseudo-XML, matches the existing
+ * `<context>` / `<privacy-mode>` markers in the prompt — consistent
+ * marker grammar across the codebase keeps the model attentive.
+ */
+export const DEFINITIONAL_MARKER_OPEN = '<intent kind="definitional">';
+export const DEFINITIONAL_MARKER_CLOSE = '</intent>';
+/**
+ * Wrap a user message with the intent marker when the classifier
+ * fires `definitional`. Returns the original message verbatim for
+ * the `operational` and `ambiguous` cases — we never lie to the
+ * model about ambiguity, and we never restrict the model's tool
+ * use on an unrelated operational task.
+ */
+export function applyIntentMarker(message, intent) {
+    if (intent !== 'definitional')
+        return message;
+    return `${DEFINITIONAL_MARKER_OPEN}\n${message}\n${DEFINITIONAL_MARKER_CLOSE}`;
+}
+function clamp01(value) {
+    if (!Number.isFinite(value))
+        return 0;
+    if (value < 0)
+        return 0;
+    if (value > 1)
+        return 1;
+    return value;
+}
+//# sourceMappingURL=intent.js.map