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

package/dist/core/retro/plane-collector.js

@@ -0,0 +1,274 @@
+/**
+ * Plane REST client for `pugi retro`.
+ *
+ * Read-only by default — lists closed + created issues, cycles, and
+ * modules in the configured project. `postRetroToPlane` is the only
+ * mutating surface and is gated by --post-plane.
+ *
+ * Config is read from `.pugi/settings.json` + env (precedence: env
+ * overrides settings). The REST shape mirrors the admin-api's
+ * PlaneService: `X-API-Key: <token>` header, `redirect: 'manual'` so
+ * a malicious 3xx never carries the token to an attacker-chosen host.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+const SETTINGS_REL = '.pugi/settings.json';
+const DEFAULT_BASE_URL = 'https://plane.pugi.io';
+const DEFAULT_WORKSPACE = 'pugi-customers';
+/** Marker embedded into every retro post so we can detect a prior
+ * post for the same date+seq and short-circuit to idempotent. */
+export function buildRetroMarker(dateLabel, sequence) {
+    return `pugi-retro-id: ${dateLabel}-${sequence}`;
+}
+export function resolvePlaneConfig(root, env = process.env) {
+    const settings = readSettings(root);
+    const baseUrl = (env.PLANE_BASE_URL ?? settings.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+    const apiKey = env.PLANE_API_KEY ?? settings.apiKey ?? '';
+    const workspaceSlug = env.PLANE_WORKSPACE_SLUG ?? settings.workspaceSlug ?? DEFAULT_WORKSPACE;
+    const projectId = env.PLANE_PROJECT_ID ?? settings.projectId ?? '';
+    if (!apiKey) {
+        return { ok: false, reason: 'PLANE_API_KEY not configured' };
+    }
+    if (!projectId) {
+        return { ok: false, reason: 'PLANE_PROJECT_ID not configured' };
+    }
+    return {
+        ok: true,
+        config: { baseUrl, apiKey, workspaceSlug, projectId },
+    };
+}
+function readSettings(root) {
+    const path = join(root, SETTINGS_REL);
+    if (!existsSync(path))
+        return {};
+    try {
+        const body = JSON.parse(readFileSync(path, 'utf8'));
+        const plane = body.plane;
+        if (!plane || typeof plane !== 'object')
+            return {};
+        const slice = plane;
+        const baseUrl = typeof slice.baseUrl === 'string' ? slice.baseUrl : undefined;
+        const apiKey = typeof slice.apiKey === 'string' ? slice.apiKey : undefined;
+        const workspaceSlug = typeof slice.workspaceSlug === 'string' ? slice.workspaceSlug : undefined;
+        const projectId = typeof slice.projectId === 'string' ? slice.projectId : undefined;
+        return { baseUrl, apiKey, workspaceSlug, projectId };
+    }
+    catch {
+        return {};
+    }
+}
+async function planeRequest(config, path, init, fetchImpl) {
+    const url = `${config.baseUrl}/api/v1${path.startsWith('/') ? path : `/${path}`}`;
+    const headers = {
+        'X-API-Key': config.apiKey,
+        Accept: 'application/json',
+    };
+    if (init.body !== undefined) {
+        headers['Content-Type'] = 'application/json';
+    }
+    const merged = {
+        ...init,
+        headers: { ...headers, ...init.headers },
+        // Mirror admin-api PlaneService — never auto-follow redirects so a
+        // compromised upstream cannot redirect us with the API key in tow.
+        redirect: 'manual',
+    };
+    const res = await fetchImpl(url, merged);
+    if (res.status >= 300 && res.status < 400) {
+        throw new Error(`plane_unexpected_redirect_${res.status}`);
+    }
+    if (!res.ok) {
+        // P1 (triple-review 2026-06-04, ): never echo upstream body.
+        // It may contain the API key if the operator misconfigured the URL
+        // with a query-string token, or any future Plane request-id header
+        // that surfaces the bearer. Generic shape only.
+        throw new Error(`plane_upstream_${res.status}`);
+    }
+    if (res.status === 204) {
+        // P3 → P1 (triple-review 2026-06-04 round 2): 204 has two meanings.
+        // On GET = empty collection → return []. On POST/PATCH = no body
+        // returned, but `postRetroToPlane` requires the created resource id
+        // back, so casting `[]` to a single `RawPlaneIssue` and reading
+        // `.id` would silently produce `''` and break idempotency. Throw
+        // when 204 lands on a mutation method instead.
+        const method = (init.method ?? 'GET').toUpperCase();
+        if (method !== 'GET' && method !== 'HEAD') {
+            throw new Error(`plane_unexpected_204_on_${method.toLowerCase()}`);
+        }
+        return [];
+    }
+    return (await res.json());
+}
+async function listIssues(config, query, fetchImpl) {
+    const out = [];
+    let path = `/workspaces/${config.workspaceSlug}/projects/${config.projectId}/issues/${query}`;
+    while (path) {
+        const page = await planeRequest(config, path, { method: 'GET' }, fetchImpl);
+        if (Array.isArray(page)) {
+            out.push(...page);
+            path = undefined;
+        }
+        else {
+            out.push(...(page.results ?? []));
+            // We do not support cross-host pagination here (admin-api does); for
+            // retros, the first page is sufficient at our typical issue counts.
+            path = undefined;
+        }
+    }
+    return out;
+}
+function toIssueRef(raw, statesById) {
+    const stateId = raw.state_id ?? raw.state;
+    const state = stateId ? statesById.get(stateId) : undefined;
+    return {
+        id: raw.id ?? '',
+        sequenceId: typeof raw.sequence_id === 'number' ? raw.sequence_id : 0,
+        name: raw.name ?? '',
+        stateId,
+        stateName: state?.name,
+        stateGroup: state?.group,
+        createdAt: raw.created_at,
+        completedAt: raw.completed_at ?? undefined,
+    };
+}
+async function listStates(config, fetchImpl) {
+    const path = `/workspaces/${config.workspaceSlug}/projects/${config.projectId}/states/`;
+    const page = await planeRequest(config, path, { method: 'GET' }, fetchImpl);
+    if (Array.isArray(page))
+        return page;
+    return page.results ?? [];
+}
+async function listCycles(config, fetchImpl) {
+    const path = `/workspaces/${config.workspaceSlug}/projects/${config.projectId}/cycles/`;
+    const page = await planeRequest(config, path, { method: 'GET' }, fetchImpl);
+    if (Array.isArray(page))
+        return page;
+    return page.results ?? [];
+}
+async function listModules(config, fetchImpl) {
+    const path = `/workspaces/${config.workspaceSlug}/projects/${config.projectId}/modules/`;
+    const page = await planeRequest(config, path, { method: 'GET' }, fetchImpl);
+    if (Array.isArray(page))
+        return page;
+    return page.results ?? [];
+}
+function pickActiveCycle(cycles, now) {
+    const nowMs = now.getTime();
+    let chosen;
+    for (const c of cycles) {
+        if (!c.start_date || !c.end_date)
+            continue;
+        const start = Date.parse(c.start_date);
+        const end = Date.parse(c.end_date);
+        if (!Number.isFinite(start) || !Number.isFinite(end))
+            continue;
+        if (start <= nowMs && nowMs <= end) {
+            chosen = c;
+            break;
+        }
+    }
+    if (!chosen)
+        return undefined;
+    const total = chosen.total_issues ?? 0;
+    const completed = chosen.completed_issues ?? 0;
+    const progressPercent = total === 0 ? 0 : Math.round((completed / total) * 100);
+    return {
+        id: chosen.id ?? '',
+        name: chosen.name ?? '',
+        startDate: chosen.start_date,
+        endDate: chosen.end_date,
+        progressPercent,
+    };
+}
+export async function collectPlaneSlice(options) {
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    const sinceIso = options.since.toISOString();
+    const states = await listStates(options.config, fetchImpl);
+    const statesById = new Map();
+    for (const s of states)
+        if (s.id)
+            statesById.set(s.id, s);
+    const [closedRaw, createdRaw, cyclesRaw, modulesRaw] = await Promise.all([
+        listIssues(options.config, `?state__group=completed&completed_at__gte=${encodeURIComponent(sinceIso)}`, fetchImpl),
+        listIssues(options.config, `?created_at__gte=${encodeURIComponent(sinceIso)}`, fetchImpl),
+        listCycles(options.config, fetchImpl),
+        listModules(options.config, fetchImpl),
+    ]);
+    const closedIssues = closedRaw.map((r) => toIssueRef(r, statesById));
+    const createdIssues = createdRaw.map((r) => toIssueRef(r, statesById));
+    const modules = modulesRaw.map((m) => ({
+        id: m.id ?? '',
+        name: m.name ?? '',
+        issueCount: m.total_issues ?? 0,
+    }));
+    const activeCycle = pickActiveCycle(cyclesRaw, new Date());
+    return {
+        closedIssues,
+        createdIssues,
+        activeCycle,
+        modules,
+        oversizedModules: [],
+        prToIssueLinks: [],
+        sprintVelocity: {
+            closedCount: closedIssues.length,
+            createdCount: createdIssues.length,
+            netDelta: closedIssues.length - createdIssues.length,
+        },
+    };
+}
+/** Pick a state in the `backlog` group so the post lands in the right
+ * column. Falls back to the first available state if no backlog state
+ * is found (Plane lets operators rename groups, but `group=backlog`
+ * is the canonical default).
+ */
+async function pickBacklogStateId(config, fetchImpl) {
+    const states = await listStates(config, fetchImpl);
+    const backlog = states.find((s) => s.group === 'backlog');
+    if (backlog?.id)
+        return backlog.id;
+    const first = states[0];
+    return first?.id;
+}
+export async function postRetroToPlane(options) {
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    const marker = buildRetroMarker(options.dateLabel, options.sequence);
+    const issueName = `Retro ${options.dateLabel} (seq ${options.sequence})`;
+    // Idempotency probe: list recent issues, look for the marker in
+    // description_html or the canonical issue name.
+    const recent = await listIssues(options.config, `?name__icontains=${encodeURIComponent(`Retro ${options.dateLabel}`)}`, fetchImpl);
+    for (const raw of recent) {
+        const haystack = `${raw.name ?? ''}\n${raw.description_html ?? ''}`;
+        if (haystack.includes(marker)) {
+            return {
+                url: buildIssueUrl(options.config, raw.id ?? ''),
+                issueId: raw.id ?? '',
+                alreadyExists: true,
+            };
+        }
+    }
+    const stateId = await pickBacklogStateId(options.config, fetchImpl);
+    const descriptionHtml = `<!-- ${marker} -->\n<pre>${escapeHtml(options.markdown)}</pre>`;
+    const body = {
+        name: issueName,
+        description_html: descriptionHtml,
+        priority: 'none',
+    };
+    if (stateId)
+        body.state = stateId;
+    const created = await planeRequest(options.config, `/workspaces/${options.config.workspaceSlug}/projects/${options.config.projectId}/issues/`, { method: 'POST', body: JSON.stringify(body) }, fetchImpl);
+    return {
+        url: buildIssueUrl(options.config, created.id ?? ''),
+        issueId: created.id ?? '',
+        alreadyExists: false,
+    };
+}
+function buildIssueUrl(config, issueId) {
+    return `${config.baseUrl}/${config.workspaceSlug}/projects/${config.projectId}/issues/${issueId}`;
+}
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
+//# sourceMappingURL=plane-collector.js.map

package/dist/core/retro/pr-issue-link.js

@@ -0,0 +1,65 @@
+/**
+ * PR-to-issue link extractor for `pugi retro`.
+ *
+ * Walks the harvested commits and matches `[A-Z]+-\d+` markers in
+ * subject + body — same shape as the existing admin-api state-sync
+ * cron uses for `PUGI-N` matches. Enrichment joins the matched ref
+ * against the Plane issue collection (when --plane is on) so the
+ * narrative can show "PR ↔ issue" pairs.
+ */
+const ISSUE_REF_RE = /\b([A-Z][A-Z0-9]*-\d+)\b/g;
+/** Extract every `<PREFIX>-<NUM>` token from a haystack. Order is
+ * preserved (first occurrence wins); duplicates collapse.
+ */
+export function extractIssueRefs(haystack) {
+    const out = [];
+    const seen = new Set();
+    ISSUE_REF_RE.lastIndex = 0;
+    let m;
+    while ((m = ISSUE_REF_RE.exec(haystack)) !== null) {
+        const ref = m[1];
+        if (!ref)
+            continue;
+        if (seen.has(ref))
+            continue;
+        seen.add(ref);
+        out.push(ref);
+    }
+    return out;
+}
+/** Build PR-to-issue links from a commit list. When `issues` is
+ * empty the links carry `planeIssue: undefined`; this lets the
+ * renderer surface the refs even without Plane enrichment.
+ */
+export function enrichLinks(commits, issues) {
+    // Build a quick lookup from sequenceId + project-prefix to PlaneIssueRef.
+    // We don't know the project's identifier here, so we match by the
+    // numeric tail of `<PREFIX>-<seq>` against `issue.sequenceId`.
+    const bySequence = new Map();
+    for (const issue of issues) {
+        bySequence.set(issue.sequenceId, issue);
+    }
+    const links = [];
+    const seen = new Set();
+    for (const commit of commits) {
+        const haystack = `${commit.subject}\n${commit.body}`;
+        const refs = extractIssueRefs(haystack);
+        for (const ref of refs) {
+            const dedupeKey = `${commit.sha}:${ref}`;
+            if (seen.has(dedupeKey))
+                continue;
+            seen.add(dedupeKey);
+            const tailMatch = /-(\d+)$/.exec(ref);
+            const seq = tailMatch ? Number.parseInt(tailMatch[1] ?? '0', 10) : NaN;
+            const planeIssue = Number.isFinite(seq) ? bySequence.get(seq) : undefined;
+            links.push({
+                prSha: commit.sha,
+                prSubject: commit.subject,
+                issueRef: ref,
+                planeIssue,
+            });
+        }
+    }
+    return links;
+}
+//# sourceMappingURL=pr-issue-link.js.map

package/dist/core/retro/types.js

@@ -0,0 +1,16 @@
+/**
+ * Shared types for `pugi retro` — engineering retrospective command.
+ *
+ * The retro pipeline runs in three stages:
+ *   1. Git collection (git-collector.ts) → RawCommit[]
+ *   2. Metric aggregation (metrics.ts) → RetroMetrics
+ *   3. Render + persist (narrative.ts) → markdown + JSON snapshot
+ *
+ * Optional Plane enrichment (plane-collector.ts) populates a PlaneSlice
+ * which the renderer joins onto the markdown if --plane was passed.
+ *
+ * All timestamps are ISO 8601 strings. Numeric fields default to 0
+ * (never undefined) so the renderer never branches on absence.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/retry-budget/budget.js

@@ -0,0 +1,284 @@
+/**
+ * — Per-command tool retry budget (the upstream tool parity).
+ *
+ * the upstream tool limits the number of times the model may retry the SAME
+ * tool with the SAME arguments inside a single operator-input cycle.
+ * Once the cap is hit, the dispatcher hard-refuses and surfaces a
+ * sentinel string telling the model that this exact call has exhausted
+ * its retry budget. The model is expected (via system-prompt rule) to
+ * either change approach or ask the operator for guidance instead of
+ * looping forever on a transient failure.
+ *
+ * Why per-cycle, not per-session: a retry budget that persists across
+ * operator turns would surprise the operator. After the operator says
+ * "try again" the model rightly retries; the budget must reset when a
+ * fresh brief arrives. The simplest reset boundary is the executor
+ * lifetime — `buildExecutor` is called once per `runEngineLoop` and
+ * the loop drives exactly one operator-input cycle. Constructing the
+ * budget inside `buildExecutor` therefore gives us per-cycle scoping
+ * "for free" via closure lifetime; no external clear() call is needed
+ * from production callsites. The exported `clear()` exists so tests
+ * and a future hook surface (PreToolUse) can introspect the state.
+ *
+ * Hash design: same tool + same canonical args = same bucket. We
+ * canonicalise the args record by sorting object keys (stable across
+ * model output ordering) and then sha256 the JSON. The model emits
+ * `arguments` as a raw JSON string; we parse, canonicalise, hash. If
+ * parse fails we hash the raw string verbatim — that way an
+ * unparseable repeat still counts toward the cap (otherwise the model
+ * could loop on syntactic noise variants forever).
+ *
+ * Env overrides:
+ *  PUGI_RETRY_BUDGET_<TOOLNAME>=<N>  — override a single tool's cap.
+ *                                       Toolname matches DEFAULT_CAPS
+ *                                       keys verbatim, uppercased
+ *                                       (PUGI_RETRY_BUDGET_BASH=8).
+ *  PUGI_RETRY_BUDGET_DEFAULT=<N>     — override the fallback cap for
+ *                                       any tool not in DEFAULT_CAPS.
+ *  PUGI_RETRY_BUDGET_DISABLED=1      — warn-only mode. `shouldAllow`
+ *                                       still records but always
+ *                                       returns `allowed: true`. The
+ *                                       count is preserved so
+ *                                       diagnostics can still surface
+ *                                       the pattern.
+ */
+import { createHash } from 'node:crypto';
+/**
+ * Default per-tool retry caps. Tuned per the upstream behavior :
+ *
+ *  bash      — 5 (most volatile; transient flakes common)
+ *  edit      — 3 (deterministic; repeat = real bug)
+ *  write     — 3 (same)
+ *  read      — 10 (cheap; legitimate re-reads after edits)
+ *  search/grep/glob — 10 (cheap; exploration loop)
+ *  web_fetch — 5 (transient network; not infinite)
+ *  default   — 5 (any tool not in the table)
+ *
+ * Operators override per-tool via `PUGI_RETRY_BUDGET_<NAME>` env vars.
+ * Caps are bounded `[1, 1000]` after override to defend against typo
+ * runaway (e.g. `PUGI_RETRY_BUDGET_BASH=5000000`).
+ */
+export const DEFAULT_CAPS = Object.freeze({
+    bash: 5,
+    edit: 3,
+    write: 3,
+    read: 10,
+    search: 10,
+    grep: 10,
+    glob: 10,
+    web_fetch: 5,
+    default: 5,
+});
+/**
+ * Lower / upper bound for any resolved cap. Defends against:
+ *  - PUGI_RETRY_BUDGET_BASH=0    -> first call instantly denied
+ *  - PUGI_RETRY_BUDGET_BASH=99999 -> effectively unbounded loop
+ */
+export const MIN_CAP = 1;
+export const MAX_CAP = 1000;
+/**
+ * Per-cycle retry budget. One instance per `buildExecutor` call.
+ *
+ * Not thread-safe: the executor is single-threaded by construction
+ * (Node event loop + sequential await in dispatcher). If a future
+ * executor parallelises tool dispatch it must serialise the budget
+ * mutation explicitly.
+ */
+export class RetryBudget {
+    counts = new Map();
+    capCache = new Map();
+    env;
+    programmaticCaps;
+    constructor(options = {}) {
+        this.env = options.env ?? process.env;
+        this.programmaticCaps = options.caps ?? {};
+    }
+    /**
+     * Returns true when PUGI_RETRY_BUDGET_DISABLED=1. In disabled mode
+     * `shouldAllow` still records attempts but always allows the
+     * dispatch — useful for operators triaging a false-positive without
+     * a code change.
+     */
+    isDisabled() {
+        return this.env.PUGI_RETRY_BUDGET_DISABLED === '1';
+    }
+    /**
+     * Record one dispatch attempt. Idempotent on the bucket key (tool
+     * + argHash). Call this BEFORE the dispatch (or after `shouldAllow`
+     * but before `dispatch()` resolves) so a thrown dispatch counts.
+     */
+    recordAttempt(toolName, argHash) {
+        const key = `${toolName}::${argHash}`;
+        const next = (this.counts.get(key) ?? 0) + 1;
+        this.counts.set(key, next);
+        return next;
+    }
+    /**
+     * Returns the current count for (tool, argHash) WITHOUT mutating.
+     */
+    peek(toolName, argHash) {
+        return this.counts.get(`${toolName}::${argHash}`) ?? 0;
+    }
+    /**
+     * Resolve the effective cap for a tool.
+     *
+     * Precedence:
+     *  1. PUGI_RETRY_BUDGET_<TOOL_UPPER>=<N> (env)
+     *  2. programmaticCaps[toolName]         (constructor)
+     *  3. DEFAULT_CAPS[toolName]             (this module)
+     *  4. PUGI_RETRY_BUDGET_DEFAULT=<N>      (env fallback)
+     *  5. DEFAULT_CAPS.default               (final fallback)
+     *
+     * Bounded by [MIN_CAP, MAX_CAP] post-resolution. Invalid (NaN, ≤0,
+     * non-integer) env values are ignored and the next layer wins.
+     */
+    capFor(toolName) {
+        const cached = this.capCache.get(toolName);
+        if (cached !== undefined)
+            return cached;
+        const envKey = `PUGI_RETRY_BUDGET_${toolName.toUpperCase()}`;
+        const envCap = parseCapEnv(this.env[envKey]);
+        const programmaticCap = this.programmaticCaps[toolName];
+        const defaultCap = DEFAULT_CAPS[toolName];
+        const fallbackEnvCap = parseCapEnv(this.env.PUGI_RETRY_BUDGET_DEFAULT);
+        // DEFAULT_CAPS.default is hard-coded above; cast keeps the type-
+        // narrower happy without leaking `| undefined` through the index
+        // access (tsc cannot prove the literal key exists).
+        const finalFallback = DEFAULT_CAPS.default;
+        let resolved;
+        if (envCap !== undefined) {
+            resolved = envCap;
+        }
+        else if (programmaticCap !== undefined) {
+            resolved = programmaticCap;
+        }
+        else if (defaultCap !== undefined) {
+            resolved = defaultCap;
+        }
+        else {
+            resolved = fallbackEnvCap ?? finalFallback;
+        }
+        const bounded = Math.min(MAX_CAP, Math.max(MIN_CAP, resolved));
+        this.capCache.set(toolName, bounded);
+        return bounded;
+    }
+    /**
+     * Should this dispatch be allowed? Caller passes the current count
+     * BEFORE recording — i.e. shouldAllow returns true when count < cap,
+     * then recordAttempt fires, bringing count up to cap. The next
+     * identical call sees count === cap and is refused.
+     *
+     * In disabled mode `allowed` is forced to true; `count` and `cap`
+     * still reflect reality so logs / diagnostics can spot the pattern.
+     */
+    shouldAllow(toolName, argHash) {
+        const cap = this.capFor(toolName);
+        const count = this.peek(toolName, argHash);
+        const disabled = this.isDisabled();
+        const allowed = disabled ? true : count < cap;
+        return { allowed, count, cap, argHash, disabled };
+    }
+    /** Reset all state. Used between operator-input cycles when the
+     * budget instance is reused (most callers throw the instance away
+     * per cycle, so clear() is mostly for tests and hook surfaces). */
+    clear() {
+        this.counts.clear();
+        this.capCache.clear();
+    }
+    /**
+     * Snapshot the current state for diagnostics. Returns a plain
+     * object so it round-trips through JSON.stringify cleanly.
+     */
+    snapshot() {
+        const out = [];
+        for (const [key, count] of this.counts) {
+            const sep = key.indexOf('::');
+            if (sep < 0)
+                continue;
+            out.push({ tool: key.slice(0, sep), argHash: key.slice(sep + 2), count });
+        }
+        return out;
+    }
+}
+/**
+ * Hash the model's tool-call arguments into a stable key. Same
+ * canonical args = same hash regardless of JSON whitespace / key
+ * order. Unparseable JSON is hashed verbatim so the budget still
+ * catches syntactically degenerate retry loops.
+ */
+export function hashArgs(argsRaw) {
+    const canonical = canonicalise(argsRaw);
+    return createHash('sha256').update(canonical).digest('hex');
+}
+/**
+ * Canonicalise a raw JSON arg string. Object keys are sorted
+ * recursively. Arrays preserve order (semantic). Primitives untouched.
+ * On parse failure, returns the original string prefixed with `raw:`
+ * so a malformed-args repeat still hashes to the same bucket.
+ */
+function canonicalise(argsRaw) {
+    try {
+        const parsed = JSON.parse(argsRaw);
+        return JSON.stringify(sortKeys(parsed));
+    }
+    catch {
+        return `raw:${argsRaw}`;
+    }
+}
+function sortKeys(value) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    const obj = value;
+    const sorted = {};
+    for (const k of Object.keys(obj).sort()) {
+        sorted[k] = sortKeys(obj[k]);
+    }
+    return sorted;
+}
+/**
+ * Parse and bound a `PUGI_RETRY_BUDGET_*` env var. Returns `undefined`
+ * for any non-positive-integer string so the resolver can fall
+ * through to the next precedence layer. Bounded by [MIN_CAP, MAX_CAP]
+ * is NOT applied here — `capFor` clamps after the final layer wins,
+ * matching the "operator typo defends against runaway" requirement
+ * without silently swallowing a meaningful low value (e.g.
+ * `PUGI_RETRY_BUDGET_BASH=1` should clamp to MIN_CAP=1, which it
+ * does naturally since 1 >= MIN_CAP).
+ */
+function parseCapEnv(raw) {
+    if (raw === undefined || raw === '')
+        return undefined;
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n <= 0)
+        return undefined;
+    return n;
+}
+/**
+ * Sentinel emitted to the model when the budget is exhausted. The
+ * format is stable so the engine adapter, spec layer, and operator
+ * dashboards can pattern-match on it.
+ */
+export function retryBudgetExhaustedSentinel(toolName, cap) {
+    return `RETRY_BUDGET_EXHAUSTED: ${toolName} exceeded ${cap} attempts with these args. Operator must intervene.`;
+}
+/**
+ * Typed error thrown by the tool-bridge when the cap is hit. Carries
+ * the sentinel string so the engine loop can pattern-match without
+ * re-parsing. `instanceof RetryBudgetExhausted` is the canonical
+ * downstream test.
+ */
+export class RetryBudgetExhausted extends Error {
+    toolName;
+    cap;
+    argHash;
+    constructor(toolName, cap, argHash) {
+        super(retryBudgetExhaustedSentinel(toolName, cap));
+        this.name = 'RetryBudgetExhausted';
+        this.toolName = toolName;
+        this.cap = cap;
+        this.argHash = argHash;
+    }
+}
+//# sourceMappingURL=budget.js.map

package/dist/core/retry-budget/index.js

@@ -0,0 +1,5 @@
+/**
+ * — Tool retry budget. Public surface.
+ */
+export { DEFAULT_CAPS, MIN_CAP, MAX_CAP, RetryBudget, RetryBudgetExhausted, hashArgs, retryBudgetExhaustedSentinel, } from './budget.js';
+//# sourceMappingURL=index.js.map