@pugi/cli 0.1.0-beta.10 → 0.1.0-beta.100

package/dist/core/engine/budgets.js

@@ -0,0 +1,220 @@
+/**
+ * Auto-compact (mid-loop transcript summarization) default trip point as
+ * a fraction of the per-command `maxTokens` envelope. CEO P1 #14 (CC
+ * parity): when transcript char-count tokens cross 75% of the budget,
+ * the engine loop drops the middle turns and inserts a deterministic
+ * `[auto-compact]` sentinel so the loop can continue без the model
+ * tripping the `budget_exhausted` terminal status mid-build.
+ *
+ * Empirically — `pugi code "big refactor"` hits the 80k cap on turn 4-5
+ * and refuses to finish; `pugi fix` does the same at 50k. Auto-compact
+ * keeps the recent N turns + a one-line gist of the dropped tool calls
+ * so the model retains the most recent state without paying for the
+ * full prefix.
+ *
+ * Operators can opt out / retune via `.pugi/settings.json`:
+ *
+ *  {
+ *    "autoCompact": { "enabled": true, "thresholdRatio": 0.75 }
+ *  }
+ *
+ * Bad values fall back silently to the default — the engine loop never
+ * crashes on a malformed settings field (mirrors `resolveBudget`).
+ */
+export const AUTO_COMPACT_THRESHOLD_RATIO = 0.75;
+export const DEFAULT_SUMMARY_MODEL = 'gemini-2.5-flash';
+export const DEFAULT_AUTO_COMPACT_CONFIG = {
+    enabled: true,
+    thresholdRatio: AUTO_COMPACT_THRESHOLD_RATIO,
+    summaryMode: 'llm',
+    summaryModel: DEFAULT_SUMMARY_MODEL,
+    summaryFallbackToStats: true,
+};
+/**
+ * Pull the auto-compact override from `.pugi/settings.json`. Uses the
+ * same defensive-cast pattern as `readSettingsBudget` so an unknown
+ * field shape silently falls back к defaults (the gate is a comfort
+ * feature; a malformed settings line must not break the engine loop).
+ *
+ * Returns the merged config — caller never sees `undefined`.
+ */
+export function resolveAutoCompactConfig(settings) {
+    if (!settings)
+        return DEFAULT_AUTO_COMPACT_CONFIG;
+    const root = settings.autoCompact;
+    if (!root || typeof root !== 'object' || Array.isArray(root)) {
+        return DEFAULT_AUTO_COMPACT_CONFIG;
+    }
+    const r = root;
+    const enabledRaw = r['enabled'];
+    const thresholdRaw = r['thresholdRatio'];
+    const summaryModeRaw = r['summaryMode'];
+    const summaryModelRaw = r['summaryModel'];
+    const summaryFallbackRaw = r['summaryFallbackToStats'];
+    const enabled = typeof enabledRaw === 'boolean'
+        ? enabledRaw
+        : DEFAULT_AUTO_COMPACT_CONFIG.enabled;
+    let thresholdRatio = DEFAULT_AUTO_COMPACT_CONFIG.thresholdRatio;
+    if (typeof thresholdRaw === 'number' && Number.isFinite(thresholdRaw)) {
+        if (thresholdRaw > 0 && thresholdRaw <= 1) {
+            thresholdRatio = thresholdRaw;
+        }
+    }
+    // PR E: defensive parse for the new summary knobs. Unknown values
+    // fall back to defaults so a malformed settings line never breaks
+    // the engine loop — mirrors the original parse posture above.
+    const summaryMode = summaryModeRaw === 'stats' || summaryModeRaw === 'llm'
+        ? summaryModeRaw
+        : DEFAULT_AUTO_COMPACT_CONFIG.summaryMode;
+    const summaryModel = typeof summaryModelRaw === 'string' && summaryModelRaw.length > 0
+        ? summaryModelRaw
+        : DEFAULT_AUTO_COMPACT_CONFIG.summaryModel;
+    const summaryFallbackToStats = typeof summaryFallbackRaw === 'boolean'
+        ? summaryFallbackRaw
+        : DEFAULT_AUTO_COMPACT_CONFIG.summaryFallbackToStats;
+    return {
+        enabled,
+        thresholdRatio,
+        summaryMode,
+        summaryModel,
+        summaryFallbackToStats,
+    };
+}
+/**
+ * β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).
+ *
+ * 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 (the upstream tool parity), but the budget cap did not move with
+ * them. the upstream tool's `code` default is ~80k; matching that restores headroom.
+ */
+export const beta1DefaultBudgets = {
+    // bump (CEO #44, post-auto-compact #14 + prompt-cache #15):
+    // auto-compact at 75% threshold + cache_control on stable prefix mean
+    // real per-call token use is ~30-40% lower than legacy. Bump headroom
+    // so multi-file refactors no longer trip the cap. Anvil clamps per-call
+    // max_tokens to 128k (PR) so the engine envelope still safe.
+    // CEO escalation 2026-06-05 round 2: "почему другие модели пишут
+    // днями? ты ограничиваешь токены?" — the upstream / Codex / Aider have
+    // NO per-task budget cap. They auto-compact at ~75% threshold and
+    // continue indefinitely. Pugi's 400K cap was still a regression vs
+    // industry expectation. Raise к the HARD_MAX_TOKENS ceiling (5M) for
+    // code/fix/build so the engine loop effectively runs until completion
+    // or until the operator aborts. Auto-compact (#14, shipped) reclaims
+    // headroom mid-loop. Token cost still tracked + tier-gated upstream;
+    // this lifts only the in-process loop ceiling.
+    fix: { maxTokens: 2_000_000, maxToolCalls: 200 },
+    code: { maxTokens: 5_000_000, maxToolCalls: 500 },
+    build: { maxTokens: 5_000_000, maxToolCalls: 500 },
+    plan: { maxTokens: 500_000, maxToolCalls: 30 },
+    explain: { maxTokens: 200_000, maxToolCalls: 20 },
+    review_triple: { maxTokens: 300_000, maxToolCalls: 20 },
+};
+/**
+ * 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`,
+ *     `--max-turns`, or the resolved intensity profile)
+ *
+ * Throws `BudgetConfigError` when the resolved budget exceeds the
+ * HARD_MAX_* caps so misconfigured settings.json fails fast.
+ *
+ * Triple-review P1 follow-up : `maxTurns` propagates through this
+ * resolver so the SDK's `runEngineLoop` actually receives the per-tier
+ * cap that the intensity dial advertises. Override precedence matches
+ * the other knobs: explicit task override > settings.json > undefined
+ * (legacy behaviour: no turn cap, only tokens + tool-calls).
+ */
+export function resolveBudget(command, settings, override) {
+    const base = beta1DefaultBudgets[command];
+    const settingsBudget = readSettingsBudget(settings, command);
+    const resolvedMaxTurns = override?.maxTurns ?? settingsBudget?.maxTurns ?? undefined;
+    const resolved = {
+        maxTokens: override?.maxTokens ??
+            settingsBudget?.maxTokens ??
+            base.maxTokens,
+        maxToolCalls: override?.maxToolCalls ??
+            settingsBudget?.maxToolCalls ??
+            base.maxToolCalls,
+        ...(resolvedMaxTurns !== undefined ? { maxTurns: resolvedMaxTurns } : {}),
+    };
+    assertBudgetWithinTier(command, resolved);
+    return resolved;
+}
+export class BudgetConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'BudgetConfigError';
+    }
+}
+/**
+ * Hard upper bound on per-task LLM turns. Above this we reject the
+ * configuration as a likely typo. The marathon intensity preset is 200,
+ * so 1000 buys an order of magnitude of headroom for power-user overrides
+ * without authorising runaway loops.
+ */
+export const HARD_MAX_TURNS = 1000;
+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}`);
+    }
+    if (budget.maxTurns !== undefined) {
+        if (!Number.isFinite(budget.maxTurns) || budget.maxTurns <= 0) {
+            throw new BudgetConfigError(`budget[${command}].maxTurns must be a positive number, got ${budget.maxTurns}`);
+        }
+        if (budget.maxTurns > HARD_MAX_TURNS) {
+            throw new BudgetConfigError(`budget[${command}].maxTurns=${budget.maxTurns} exceeds hard cap ${HARD_MAX_TURNS}`);
+        }
+    }
+}
+/**
+ * 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'];
+    if (typeof e['maxTurns'] === 'number')
+        out.maxTurns = e['maxTurns'];
+    return out;
+}
+//# sourceMappingURL=budgets.js.map

package/dist/core/engine/compact-llm-summarizer.js

@@ -0,0 +1,124 @@
+/**
+ * Fixed system prompt. Stable so cache keys (if Anvil grows prompt-cache
+ * support for cheaper models) stay hot turn over turn.
+ */
+export const COMPACT_LLM_SYSTEM_PROMPT = 'You are summarizing a developer conversation between an operator and ' +
+    'an AI coding assistant. Output 3-5 sentences max preserving: 1) what ' +
+    'the operator wanted, 2) what was attempted or shipped, 3) any ' +
+    'corrections, 4) pending items. Cite file paths verbatim. No bullet ' +
+    'points; just prose. No preamble like "Here is the summary".';
+/** Character budget for the serialized dropped slice (approx 5K tokens). */
+export const COMPACT_LLM_INPUT_CHAR_BUDGET = 20_000;
+/** Head + tail split when the body exceeds the budget. */
+const COMPACT_LLM_HEAD_CHARS = 8_000;
+const COMPACT_LLM_TAIL_CHARS = 12_000;
+const COMPACT_LLM_TRUNCATION_MARKER = '\n\n[...truncated...]\n\n';
+/**
+ * Render the dropped slice into a single user-message body that the
+ * model can read top-down. Each turn is labelled by role; tool calls
+ * carry their name + truncated arguments so the summary can cite files
+ * by path. Tool result frames carry their truncated payload so the
+ * model sees what came back, not just what was asked.
+ *
+ * Exported for testability. Pure function — no fs / network.
+ */
+export function serializeDroppedTurns(dropped) {
+    const parts = [];
+    for (const m of dropped) {
+        if (m.role === 'assistant') {
+            const calls = m.toolCalls ?? [];
+            if (calls.length === 0) {
+                parts.push(`[assistant]\n${m.content}`);
+                continue;
+            }
+            const callLines = calls.map((c) => {
+                const argSnippet = c.arguments.length > 400
+                    ? `${c.arguments.slice(0, 400)}...[truncated]`
+                    : c.arguments;
+                return `  - tool=${c.name} args=${argSnippet}`;
+            });
+            const header = m.content ? `${m.content}\n` : '';
+            parts.push(`[assistant]\n${header}${callLines.join('\n')}`);
+        }
+        else if (m.role === 'tool') {
+            const snippet = m.content.length > 600
+                ? `${m.content.slice(0, 600)}...[truncated]`
+                : m.content;
+            parts.push(`[tool result name=${m.toolName ?? 'unknown'}]\n${snippet}`);
+        }
+        else if (m.role === 'user') {
+            parts.push(`[operator]\n${m.content}`);
+        }
+        else {
+            parts.push(`[system]\n${m.content}`);
+        }
+    }
+    return parts.join('\n\n');
+}
+/**
+ * Enforce the input character budget. When the body exceeds the
+ * budget we keep the first 8k chars and the last 12k chars with an
+ * explicit truncation marker. The tail is wider than the head because
+ * the most recent decisions are typically the highest-signal context.
+ *
+ * Exported for testability.
+ */
+export function truncateForLlm(body) {
+    if (body.length <= COMPACT_LLM_INPUT_CHAR_BUDGET)
+        return body;
+    const head = body.slice(0, COMPACT_LLM_HEAD_CHARS);
+    const tail = body.slice(body.length - COMPACT_LLM_TAIL_CHARS);
+    return `${head}${COMPACT_LLM_TRUNCATION_MARKER}${tail}`;
+}
+/**
+ * Drive a summary via the injected LLM call. Returns the trimmed
+ * narrative string on success, or `null` on any failure mode the
+ * caller should treat as "summary unavailable":
+ *
+ *  - call threw (network, timeout, transport error)
+ *  - call returned null / undefined
+ *  - call returned an empty or whitespace-only string
+ *  - call returned a value that is not a string (defensive guard)
+ *
+ * The caller (typically `maybeCompactAsync`) is responsible for
+ * deciding whether to fall back to the stats sentinel or abort
+ * compaction; this function only signals success/failure.
+ */
+export async function summarizeViaLLM(input, call) {
+    if (input.dropped.length === 0)
+        return null;
+    const body = truncateForLlm(serializeDroppedTurns(input.dropped));
+    if (body.length === 0)
+        return null;
+    let raw;
+    try {
+        raw = await call({
+            model: input.model,
+            systemPrompt: COMPACT_LLM_SYSTEM_PROMPT,
+            userMessage: body,
+            maxTokens: 500,
+            temperature: 0.3,
+            ...(input.signal ? { signal: input.signal } : {}),
+        });
+    }
+    catch {
+        return null;
+    }
+    if (typeof raw !== 'string')
+        return null;
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return null;
+    return trimmed;
+}
+/**
+ * Build a sentinel content string from an LLM-produced summary. We
+ * keep the `[auto-compact]` prefix so operator-side log scrapers
+ * (existing dashboards, `pugi doctor`) still recognise the line as
+ * a compaction event. The summary itself follows on a new line so
+ * structured parsers can split prefix from body if they want.
+ */
+export function renderLlmSentinel(summary) {
+    return `[auto-compact]\n${summary}`;
+}
+//# sourceMappingURL=compact-llm-summarizer.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/index.js

@@ -5,7 +5,7 @@ export * from './noop.js';
 export * from './prompts.js';
 export * from './tool-bridge.js';
 // Subagent dispatch helper. Engine adapter code calls this from a
-// future `task_dispatch` tool (alpha-5.7 REPL); the re-export keeps the
+// future `task_dispatch` tool ; the re-export keeps the
 // import path stable so adapter code does not have to reach into the
 // subagents submodule.
 export { spawnSubagent } from '../subagents/spawn.js';

package/dist/core/engine/intensity.js

@@ -0,0 +1,163 @@
+/**
+ * Intensity dial — single knob that derives max_turns, token budget,
+ * model tag, and parallel-agent posture for `pugi code/fix/build/plan/explain`.
+ *
+ * Spec: Pugi backlog. Pattern lifted from Karpathy's nanochat
+ * `--depth` flag — one dial that captures "how much do you want me to
+ * spend on this turn?" so operators do not have to tune four separate
+ * knobs in lockstep.
+ *
+ * Four discrete levels were chosen over a free-form integer:
+ *
+ *  - operators have a mental model for "quick / standard / deep / marathon"
+ *  - discrete tiers let us tune model + parallel-agent posture per tier
+ *    without exposing a continuous knob that has no meaning above 200 turns
+ *  - keeps env override (`PUGI_INTENSITY`) trivially parseable
+ *
+ * Defaults are conservative — the operator can always override any
+ * individual knob via the per-command flag (`--max-turns`, `--max-tokens`,
+ * `PUGI_ENGINE_MODEL_<COMMAND>`) and the explicit flag wins.
+ *
+ *  | level   | max_turns | budget tokens | model   | parallel agents |
+ *  |----------|-----------|---------------|----------|------------------|
+ *  | quick   |        3 |       30 000 | haiku   | off             |
+ *  | standard |       15 |       80 000 | sonnet  | off             |
+ *  | deep    |       50 |      200 000 | sonnet  | up to 3         |
+ *  | marathon |      200 |      800 000 | opus    | up to 3         |
+ *
+ * Model tags are abstract (`light`/`standard`/`heavy`). The CLI maps
+ * each tag to a concrete model slug via env override
+ * (`PUGI_INTENSITY_MODEL_<TAG>`) OR falls back to the per-persona default
+ * resolved by the admin-api runtime. We do NOT hard-code Anthropic /
+ * OpenAI slugs here — those move per provider release and would couple
+ * the CLI to the runtime's routing table. Operators pin a concrete model
+ * via `PUGI_ENGINE_MODEL_<COMMAND>` when they need exact control.
+ */
+export const INTENSITY_LEVELS = [
+    'quick',
+    'standard',
+    'deep',
+    'marathon',
+];
+export const DEFAULT_INTENSITY = 'standard';
+const PROFILES = {
+    quick: {
+        level: 'quick',
+        maxTurns: 3,
+        budgetTokens: 30_000,
+        modelTag: 'light',
+        allowParallelAgents: false,
+        maxParallelAgents: 0,
+    },
+    // CEO 2026-06-05: 80K standard exhausted React multi-file build mid-
+    // turn (120K hardcoded budget). Customers compare to the upstream = 200K
+    // context per session. Bump standard к 200K so default REPL doesn't
+    // trip mid-build; deep к 500K for complex multi-file refactors;
+    // marathon к 1.5M for long-running autonomous work.
+    standard: {
+        level: 'standard',
+        maxTurns: 30,
+        budgetTokens: 200_000,
+        modelTag: 'standard',
+        allowParallelAgents: false,
+        maxParallelAgents: 0,
+    },
+    deep: {
+        level: 'deep',
+        maxTurns: 80,
+        budgetTokens: 500_000,
+        modelTag: 'standard',
+        allowParallelAgents: true,
+        maxParallelAgents: 3,
+    },
+    marathon: {
+        level: 'marathon',
+        maxTurns: 300,
+        budgetTokens: 1_500_000,
+        modelTag: 'heavy',
+        allowParallelAgents: true,
+        maxParallelAgents: 3,
+    },
+};
+/**
+ * Look up the profile for a level. Pure — returns the same frozen
+ * object on every call so callers can reference-compare cheaply.
+ */
+export function profileFor(level) {
+    return PROFILES[level];
+}
+/**
+ * Resolve the effective per-task `maxTurns` cap.
+ *
+ * Precedence (triple-review P1 follow-up):
+ *  1. explicit `--max-turns=N` flag wins outright
+ *  2. otherwise the intensity profile's per-tier preset wins
+ *
+ * The function is pure so the CLI seam can call it inline and the test
+ * corpus can pin the precedence without spinning up a full adapter.
+ * Returning the resolved primitive instead of an object keeps the
+ * call site readable: `const turns = resolveMaxTurns(flags.maxTurns,
+ * profile);`. The CLI threads the result into `EngineTask.budget.turns`
+ * which the native-pugi adapter forwards to `EngineBudget.maxTurns` in
+ * the SDK loop.
+ */
+export function resolveMaxTurns(flagMaxTurns, profile) {
+    return flagMaxTurns ?? profile.maxTurns;
+}
+/**
+ * Type guard for the four-level enum. Rejects everything else,
+ * including capitalised variants — operators surface the typo at parse
+ * time rather than seeing the dial silently degrade to`standard`.
+ */
+export function isIntensityLevel(value) {
+    return (typeof value === 'string' &&
+        INTENSITY_LEVELS.includes(value));
+}
+/**
+ * Resolve the effective intensity level from CLI input + env fallback.
+ *
+ *  1. CLI `--intensity <level>` wins when supplied.
+ *  2. `PUGI_INTENSITY` env wins next when `envFallback` (default true).
+ *  3. `DEFAULT_INTENSITY` ('standard') is the final fallback.
+ *
+ * Explicit-flag typos throw — an operator who typed `--intensity marathn`
+ * gets an immediate, deterministic error rather than silently dropping
+ * to `standard`. This matches the rule for every other named CLI flag
+ * (single source of truth lives in `parseArgs`).
+ *
+ * Env-var typos WARN and fall back — `PUGI_INTENSITY` is shell state that
+ * can persist across many sessions (rc files, container env, CI matrix).
+ * A typo there used to throw on every invocation and prevent any `pugi`
+ * command from running at all; the warn-not-throw path keeps the CLI
+ * usable and surfaces the bad value once on stderr so the operator can
+ * fix their environment. Triple-review P1 follow-up .
+ *
+ * The `warn` hook is injectable so unit tests can capture the message
+ * without depending on `process.stderr`. Production callers pass nothing
+ * and the helper falls back to `process.stderr.write`.
+ */
+export function resolveIntensity(opts) {
+    if (opts.intensity !== undefined && opts.intensity !== '') {
+        if (!isIntensityLevel(opts.intensity)) {
+            throw new Error(`unknown --intensity "${opts.intensity}"; expected one of ${INTENSITY_LEVELS.join(', ')}`);
+        }
+        return opts.intensity;
+    }
+    const envFallback = opts.envFallback !== false;
+    if (envFallback) {
+        const fromEnv = process.env['PUGI_INTENSITY'];
+        if (fromEnv !== undefined && fromEnv !== '') {
+            if (!isIntensityLevel(fromEnv)) {
+                const message = `pugi: PUGI_INTENSITY="${fromEnv}" is not one of ${INTENSITY_LEVELS.join(', ')}; ignoring and using default (${DEFAULT_INTENSITY}).\n`;
+                const writer = opts.warn ?? ((m) => {
+                    process.stderr.write(m);
+                });
+                writer(message);
+                return DEFAULT_INTENSITY;
+            }
+            return fromEnv;
+        }
+    }
+    return DEFAULT_INTENSITY;
+}
+//# sourceMappingURL=intensity.js.map