@nac3/forge-cli 0.2.0-alpha.9 → 0.2.1-alpha.60

package/dist/core/shell_classifier.js

@@ -0,0 +1,159 @@
+/**
+ * shell_classifier.ts -- categorize a shell command into one of
+ * four risk buckets (alpha.59d).
+ *
+ * Buckets:
+ *   destructive    -- modifies / removes user data, force-pushes,
+ *                     etc. Always requires approval.
+ *   elevation      -- sudo / gsudo / runas / su. Always approval.
+ *   network        -- curl/wget/npm-install/etc that touches the
+ *                     network. Pablo's rule: approve always.
+ *   safe           -- ls, cd, pwd, git status, etc. Auto-approves
+ *                     (subject to Danger Zone toggle in limits).
+ *
+ * The classifier is intentionally CONSERVATIVE: when in doubt it
+ * escalates to a higher-risk bucket. False positives cost the
+ * user an extra approval prompt; false negatives could execute
+ * unwanted changes silently.
+ *
+ * Pattern matching is regex-based + token-aware. It does NOT
+ * try to parse shell grammar perfectly -- it catches the obvious
+ * dangerous shapes (rm -rf /, force flags, sudo prefix, network
+ * binaries, etc).
+ *
+ * ASCII-only.
+ */
+/* Tokens that mark a destructive intent regardless of shell. */
+const DESTRUCTIVE_TOKENS = [
+    /* rm with recursive + force is the canonical "blast radius" command. */
+    { pat: /\brm\s+(?:-[a-zA-Z]*r[a-zA-Z]*\s|-[a-zA-Z]*f[a-zA-Z]*\s|--force\s|--recursive\s)/i, reason: 'rm -r/-f' },
+    /* Bare rm against a path is still destructive. */
+    { pat: /\brm\s+(?!--help|--version)/i, reason: 'rm' },
+    { pat: /\brmdir\b/i, reason: 'rmdir' },
+    { pat: /\bmv\s+(?!--help)/i, reason: 'mv (could overwrite)' },
+    { pat: /\bdd\s+if=/i, reason: 'dd' },
+    { pat: /\bshred\b/i, reason: 'shred' },
+    { pat: />\s*\/dev\/sd[a-z]/i, reason: 'redirect to raw device' },
+    { pat: />\s*\/etc\//i, reason: 'write to /etc' },
+    /* git destructive ops. */
+    { pat: /\bgit\s+push\s+(?:[^|;&]*\s)?--force\b/i, reason: 'git push --force' },
+    { pat: /\bgit\s+push\s+(?:[^|;&]*\s)?-f\b/i, reason: 'git push -f' },
+    { pat: /\bgit\s+reset\s+(?:[^|;&]*\s)?--hard\b/i, reason: 'git reset --hard' },
+    { pat: /\bgit\s+clean\s+(?:[^|;&]*-[a-zA-Z]*f)/i, reason: 'git clean -f' },
+    { pat: /\bgit\s+branch\s+(?:[^|;&]*\s)?-D\b/, reason: 'git branch -D' },
+    /* Postgres / mysql blunt instruments. */
+    { pat: /\bDROP\s+(TABLE|DATABASE|SCHEMA)\b/i, reason: 'DROP TABLE/DATABASE' },
+    { pat: /\bTRUNCATE\s+TABLE\b/i, reason: 'TRUNCATE TABLE' },
+    /* npm publish, cargo publish, etc -- one-way. */
+    { pat: /\bnpm\s+publish\b/i, reason: 'npm publish' },
+    { pat: /\bpnpm\s+publish\b/i, reason: 'pnpm publish' },
+    /* skip hooks / signing -- bypass safety. */
+    { pat: /--no-verify\b/, reason: '--no-verify' },
+    { pat: /--no-gpg-sign\b/, reason: '--no-gpg-sign' },
+    /* chmod / chown on system paths. */
+    { pat: /\bchmod\s+(?:[^|;&]*\s)?(?:777|-R\b)/i, reason: 'chmod 777 / -R' },
+    /* Windows blast tokens. */
+    { pat: /\bdel\s+\/[fsq]/i, reason: 'del /f /s /q' },
+    { pat: /\brmdir\s+\/[sq]/i, reason: 'rmdir /s /q' },
+    { pat: /\bformat\s+[a-z]:/i, reason: 'format C:' },
+];
+/* Privilege elevation: sudo / runas / etc. Always approval. */
+const ELEVATION_TOKENS = [
+    { pat: /^\s*sudo\b/, reason: 'sudo prefix' },
+    { pat: /\|\s*sudo\b/, reason: 'piped to sudo' },
+    { pat: /^\s*gsudo\b/i, reason: 'gsudo prefix' },
+    { pat: /^\s*runas\b/i, reason: 'runas prefix' },
+    { pat: /^\s*su\b/, reason: 'su prefix' },
+    { pat: /\bdoas\b/, reason: 'doas' },
+];
+/* Network egress / installs. Per Pablo: approve always. */
+const NETWORK_TOKENS = [
+    { pat: /\bcurl\b/i, reason: 'curl' },
+    { pat: /\bwget\b/i, reason: 'wget' },
+    { pat: /\bInvoke-WebRequest\b/i, reason: 'Invoke-WebRequest' },
+    { pat: /\bIwr\b/, reason: 'iwr' },
+    { pat: /\bnc\b\s|netcat\b/, reason: 'nc/netcat' },
+    /* package managers that hit the network. */
+    { pat: /\bnpm\s+(install|i|ci|update|upgrade|add)\b/i, reason: 'npm install' },
+    { pat: /\bpnpm\s+(install|add|update|i\b)/i, reason: 'pnpm install' },
+    { pat: /\byarn\s+(add|install|upgrade)\b/i, reason: 'yarn install' },
+    { pat: /\bpip\s+(install|download)\b/i, reason: 'pip install' },
+    { pat: /\bpip3\s+(install|download)\b/i, reason: 'pip3 install' },
+    { pat: /\bpoetry\s+(add|install|update)\b/i, reason: 'poetry install' },
+    { pat: /\bbrew\s+(install|upgrade|tap)\b/i, reason: 'brew install' },
+    { pat: /\bapt(-get)?\s+(install|update|upgrade)\b/i, reason: 'apt install' },
+    { pat: /\bcargo\s+(install|update|publish)\b/i, reason: 'cargo install' },
+    { pat: /\bgo\s+(get|install)\b/i, reason: 'go get/install' },
+    { pat: /\bgit\s+(clone|fetch|pull|push)\b/i, reason: 'git network op' },
+    /* docker pulls + runs from registry. */
+    { pat: /\bdocker\s+(pull|run|build|push)\b/i, reason: 'docker network op' },
+];
+/* Tokens that mark the command as command-and-pipe-to-shell --
+ *  the worst case (curl | bash). Always destructive + network. */
+const PIPE_TO_SHELL = /\|\s*(?:bash|sh|zsh|fish|pwsh|powershell)\b/i;
+/* Common safe read-only / pwd-style commands. Just a fast path
+ *  to skip the heavier scans for trivial cases. NOT used as a
+ *  whitelist -- the scanners still run + can over-rule. */
+const SAFE_TOKENS = [
+    /^\s*(ls|dir|pwd|cd|echo|cat|less|more|head|tail|wc|date|whoami|hostname|uname)\b/i,
+    /^\s*git\s+(status|log|diff|branch\b(?!.*-D)|show|describe|stash\s+list)\b/i,
+    /^\s*node\s+--version\b/i,
+    /^\s*npm\s+(?:--version|-v|ls|list|outdated)\b/i,
+    /^\s*python3?\s+--version\b/i,
+];
+export function classifyShellCommand(command) {
+    const reasons = [];
+    const trimmed = (command || '').trim();
+    if (!trimmed) {
+        return { bucket: 'safe', reasons: ['empty'], requires_approval: false };
+    }
+    /* Worst-case: pipe to shell. Treat as destructive. */
+    if (PIPE_TO_SHELL.test(trimmed)) {
+        return {
+            bucket: 'destructive',
+            reasons: ['pipe to shell interpreter'],
+            requires_approval: true,
+        };
+    }
+    /* Elevation takes precedence -- sudo X is dangerous regardless
+     *  of what X does. */
+    for (const { pat, reason } of ELEVATION_TOKENS) {
+        if (pat.test(trimmed)) {
+            return { bucket: 'elevation', reasons: [reason], requires_approval: true };
+        }
+    }
+    /* Destructive sweep. */
+    for (const { pat, reason } of DESTRUCTIVE_TOKENS) {
+        if (pat.test(trimmed))
+            reasons.push(reason);
+    }
+    if (reasons.length > 0) {
+        return { bucket: 'destructive', reasons, requires_approval: true };
+    }
+    /* Network sweep. */
+    const netReasons = [];
+    for (const { pat, reason } of NETWORK_TOKENS) {
+        if (pat.test(trimmed))
+            netReasons.push(reason);
+    }
+    if (netReasons.length > 0) {
+        return { bucket: 'network', reasons: netReasons, requires_approval: true };
+    }
+    /* Safe fast-path. */
+    for (const p of SAFE_TOKENS) {
+        if (p.test(trimmed))
+            return { bucket: 'safe', reasons: ['known safe pattern'], requires_approval: false };
+    }
+    /* Unknown -> default to safe but flag for the user. The
+     *  approval gate at the caller is what decides if approval is
+     *  required; safe bucket means "don't force approval, but
+     *  caller may still require it if 'always approve shell' is
+     *  on or Danger Zone is off + the operator wants total
+     *  control". */
+    return { bucket: 'safe', reasons: ['unclassified -- defaulted safe'], requires_approval: false };
+}
+/* Test seam. */
+export const _patterns = {
+    DESTRUCTIVE_TOKENS, ELEVATION_TOKENS, NETWORK_TOKENS, SAFE_TOKENS, PIPE_TO_SHELL,
+};
+//# sourceMappingURL=shell_classifier.js.map

package/dist/core/shell_classifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell_classifier.js","sourceRoot":"","sources":["../../src/core/shell_classifier.ts"],"names":[],"mappings":"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"}

package/dist/core/sq_resolver.d.ts

@@ -0,0 +1,14 @@
+/** Force-clear caches. Used by tests. */
+export declare function _clearSqResolverCaches(): void;
+/** Return the active SQ rule slugs for a given step, merged with
+ *  the always-active cross-cutting set. Deduped. */
+export declare function activeRulesForStep(stepDescriptor: string | number | null | undefined): Promise<string[]>;
+/** Render a compact "ACTIVE SQ RULES" block for the system prompt.
+ *  Format: `SQ <slug>  <title>` one per line. Returns empty when
+ *  no rules apply (e.g., yaml missing). */
+export declare function renderActiveRulesBlock(stepDescriptor: string | number | null | undefined): Promise<string>;
+/** Render the ACTIVE SQ RULES block from an explicit slug list.
+ *  Used when the workflow state declares `active_sq_rules` directly
+ *  (alpha.59z.5 F1 -- skip the step inference path). */
+export declare function renderRulesBlockBySlugs(slugs: string[]): Promise<string>;
+//# sourceMappingURL=sq_resolver.d.ts.map

package/dist/core/sq_resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sq_resolver.d.ts","sourceRoot":"","sources":["../../src/core/sq_resolver.ts"],"names":[],"mappings":"AA2JA,yCAAyC;AACzC,wBAAgB,sBAAsB,IAAI,IAAI,CAG7C;AAsBD;oDACoD;AACpD,wBAAsB,kBAAkB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAU9G;AAED;;2CAE2C;AAC3C,wBAAsB,sBAAsB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAGhH;AAED;;wDAEwD;AACxD,wBAAsB,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAwB9E"}

package/dist/core/sq_resolver.js

@@ -0,0 +1,230 @@
+/**
+ * SQ rules resolver (alpha.59y.3).
+ *
+ * Given the current workflow step, returns the subset of SQ rules
+ * that apply, with their one-line title from docs/SQ.md.
+ *
+ * Source of truth:
+ *   docs/SQ_BY_STEP.yaml -- manual matrix (step -> rule_slugs)
+ *   docs/SQ.md           -- rule titles (parsed from ### headings)
+ *
+ * Output (renderActiveRulesBlock) goes into the workflow inject
+ * block so the LLM sees ONLY the rules that matter at the current
+ * step + the always-active cross-cutting rules. Keeps the prompt
+ * compact + relevant.
+ *
+ * ASCII-only.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+/** docs/ lives at repo root; dist files run from dist/core; tsx
+ *  runs from src/core. Walk up until we find docs/SQ.md. */
+function resolveDocsDir() {
+    let cur = __dirname;
+    for (let i = 0; i < 8; i++) {
+        const candidate = path.join(cur, 'docs', 'SQ.md');
+        /* fs.existsSync would be nice but we are async; instead we
+         *  hop levels and let readFile fail later if not found. */
+        if (cur === path.parse(cur).root)
+            break;
+        cur = path.dirname(cur);
+    }
+    /* Fallback: cwd. */
+    return path.resolve(process.cwd(), 'docs');
+}
+const DOCS_DIR_HINTS = [
+    /* dist/core -> ../../docs (repo root) when running from source repo */
+    path.resolve(__dirname, '..', '..', 'docs'),
+    /* dist/core -> ../docs (when copy_qa_assets put docs alongside core) */
+    path.resolve(__dirname, '..', 'docs'),
+    /* src/core -> ../../docs */
+    path.resolve(__dirname, '..', '..', 'docs'),
+    /* cwd / docs */
+    path.resolve(process.cwd(), 'docs'),
+];
+async function readDoc(name) {
+    for (const dir of DOCS_DIR_HINTS) {
+        try {
+            const p = path.join(dir, name);
+            const s = await fs.readFile(p, 'utf-8');
+            return s;
+        }
+        catch { /* try next */ }
+    }
+    return null;
+}
+let _yamlCache = null;
+let _titlesCache = null;
+/** Parse our limited YAML subset (top-level keys with arrays of
+ *  strings). We control the file, so no need for a real YAML lib.
+ *  Lines starting with '#' are comments. */
+function parseYaml(text) {
+    const out = {};
+    let currentKey = null;
+    let currentArr = [];
+    for (const rawLine of text.split(/\r?\n/)) {
+        const line = rawLine.replace(/\r/g, '');
+        /* Skip blank + comments. */
+        if (!line.trim() || line.trim().startsWith('#'))
+            continue;
+        /* Top-level key (no indent): `name:` */
+        if (/^[a-zA-Z0-9_]+:/.test(line)) {
+            if (currentKey)
+                out[currentKey] = currentArr;
+            currentKey = line.split(':')[0].trim();
+            currentArr = [];
+            continue;
+        }
+        /* Array entry: `  - "0.1"` */
+        const m = line.match(/^\s*-\s*"?([^"#]+)"?/);
+        if (m && currentKey) {
+            const val = m[1].trim();
+            if (val)
+                currentArr.push(val);
+        }
+    }
+    if (currentKey)
+        out[currentKey] = currentArr;
+    return out;
+}
+/** Parse `### N.N Title` headings from SQ.md, returns slug->title map. */
+function parseSqTitles(text) {
+    const m = new Map();
+    for (const line of text.split(/\r?\n/)) {
+        /* Match either `### 0.1 Title` or `### 14 Title` */
+        const r = line.match(/^###\s+(\d+(?:\.\d+)?)\s+(.+?)\s*$/);
+        if (r)
+            m.set(r[1], r[2].trim());
+        /* Also catch `## N. Title` (top-level section names). */
+        const r2 = line.match(/^##\s+(\d+)\.\s+(.+?)\s*$/);
+        if (r2)
+            m.set(r2[1], r2[2].trim());
+    }
+    return m;
+}
+/** alpha.59z.42 -- parse `G<N>: Title` lines from docs/doctrine/gates.md.
+ *  Returns slug -> title (e.g. "G2" -> "No minimum brain (LLM) key in vault").
+ *  The scenario fixtures use richer slugs like "G2-vault-min-keys" which
+ *  also resolve here via the normaliseGateSlug step. */
+function parseGateTitles(text) {
+    const m = new Map();
+    for (const line of text.split(/\r?\n/)) {
+        const r = line.match(/^(G\d+):\s+(.+?)\s*$/);
+        if (r)
+            m.set(r[1], r[2].trim());
+    }
+    return m;
+}
+/** Strip the descriptive suffix from gate slugs: "G2-vault-min-keys" -> "G2".
+ *  Non-gate slugs (purely numeric SQ rules) are returned unchanged. */
+function normaliseGateSlug(slug) {
+    const m = slug.match(/^(G\d+)(?:[-_].*)?$/);
+    return m ? m[1] : slug;
+}
+async function loadYaml() {
+    if (_yamlCache)
+        return _yamlCache;
+    const t = await readDoc('SQ_BY_STEP.yaml');
+    if (!t) {
+        _yamlCache = {};
+        return _yamlCache;
+    }
+    _yamlCache = parseYaml(t);
+    return _yamlCache;
+}
+async function loadTitles() {
+    if (_titlesCache)
+        return _titlesCache;
+    const t = await readDoc('SQ.md');
+    const m = t ? parseSqTitles(t) : new Map();
+    /* alpha.59z.42 -- merge gate titles from doctrine/gates.md so
+     *  active_sq_rules entries like "G2-vault-min-keys" resolve to
+     *  the gate description. Gates are part of the same "rule
+     *  enforcement at this step" surface from the brain's POV. */
+    const gates = await readDoc(path.join('doctrine', 'gates.md'));
+    if (gates) {
+        const gateTitles = parseGateTitles(gates);
+        for (const [k, v] of gateTitles.entries())
+            m.set(k, v);
+    }
+    _titlesCache = m;
+    return _titlesCache;
+}
+/** Force-clear caches. Used by tests. */
+export function _clearSqResolverCaches() {
+    _yamlCache = null;
+    _titlesCache = null;
+}
+/** Canonicalise a step descriptor to the YAML key. Accepts:
+ *  - 'step_15_block_dev' (already canonical)
+ *  - 15 (number; we resolve by scanning yaml keys starting with `step_15_`)
+ *  - 'phase_v' (returns null -- not granular enough)
+ */
+function canonicalStepKey(yaml, descriptor) {
+    if (typeof descriptor === 'string' && descriptor.startsWith('step_')) {
+        return descriptor in yaml ? descriptor : null;
+    }
+    if (typeof descriptor === 'number') {
+        const prefix = 'step_' + descriptor + '_';
+        for (const k of Object.keys(yaml)) {
+            if (k.startsWith(prefix))
+                return k;
+        }
+        /* Also try plain "step_<N>" without slug. */
+        return 'step_' + descriptor in yaml ? 'step_' + descriptor : null;
+    }
+    return null;
+}
+/** Return the active SQ rule slugs for a given step, merged with
+ *  the always-active cross-cutting set. Deduped. */
+export async function activeRulesForStep(stepDescriptor) {
+    const yaml = await loadYaml();
+    const cross = yaml['cross_cutting'] || [];
+    if (stepDescriptor === null || stepDescriptor === undefined) {
+        return cross.slice();
+    }
+    const key = canonicalStepKey(yaml, stepDescriptor);
+    const stepRules = key ? (yaml[key] || []) : [];
+    const merged = new Set([...cross, ...stepRules]);
+    return Array.from(merged);
+}
+/** Render a compact "ACTIVE SQ RULES" block for the system prompt.
+ *  Format: `SQ <slug>  <title>` one per line. Returns empty when
+ *  no rules apply (e.g., yaml missing). */
+export async function renderActiveRulesBlock(stepDescriptor) {
+    const slugs = await activeRulesForStep(stepDescriptor);
+    return renderRulesBlockBySlugs(slugs);
+}
+/** Render the ACTIVE SQ RULES block from an explicit slug list.
+ *  Used when the workflow state declares `active_sq_rules` directly
+ *  (alpha.59z.5 F1 -- skip the step inference path). */
+export async function renderRulesBlockBySlugs(slugs) {
+    if (slugs.length === 0)
+        return '';
+    const titles = await loadTitles();
+    const lines = [];
+    lines.push('ACTIVE SQ RULES (subset of docs/SQ.md) -- ENFORCE actively:');
+    for (const slug of slugs) {
+        /* alpha.59z.42 -- accept rich gate slugs like
+         *  "G2-vault-min-keys" + resolve to the base gate description
+         *  from docs/doctrine/gates.md. SQ rules (numeric slugs) pass
+         *  through unchanged. The `[GATE]` marker is appended inline
+         *  so the brain treats it as a hard block while the existing
+         *  "SQ <slug>" prefix stays stable for tests + consumers. */
+        const lookup = normaliseGateSlug(slug);
+        const title = titles.get(lookup) || '(no title found)';
+        const gateMarker = lookup.startsWith('G') ? ' [GATE -- hard block]' : '';
+        lines.push('SQ ' + lookup.padEnd(5) + ' ' + title + gateMarker);
+    }
+    lines.push('');
+    lines.push('Enforcement: these rules are AUTHORITATIVE for this turn.');
+    lines.push('If the user asks to violate one (skip tests, ignore docs,');
+    lines.push('paste secrets, advance past a [GATE], etc), you MUST refuse +');
+    lines.push('cite the rule by its SQ number + explain the cost briefly.');
+    lines.push('Do NOT simply comply -- the user expects you to defend the rules.');
+    return lines.join('\n');
+}
+//# sourceMappingURL=sq_resolver.js.map

package/dist/core/sq_resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sq_resolver.js","sourceRoot":"","sources":["../../src/core/sq_resolver.ts"],"names":[],"mappings":"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"}

package/dist/core/truncation_detector.d.ts

@@ -0,0 +1,68 @@
+/**
+ * F104 -- Truncation detector.
+ *
+ * Detects when an LLM response was cut off by the max_tokens cap.
+ * Pablo's insight 2026-06-03: instead of trusting the provider's
+ * stop_reason field (which varies in shape across Anthropic /
+ * OpenAI / Google / xAI / Mistral / DeepSeek / Cohere), compare
+ * the reported output_tokens against the requested max_tokens
+ * with a small safety margin. If output_tokens >= max_tokens -
+ * MARGIN, treat the response as truncated.
+ *
+ * Rationale:
+ *   - Provider-agnostic: every provider reports output_tokens
+ *     (or input_tokens we can derive output from). stop_reason
+ *     names + values differ.
+ *   - Robust: simple arithmetic, no string parsing.
+ *   - Conservative: we use a small margin to catch boundary
+ *     cases (e.g. response landed at 8190 of 8192 -- almost
+ *     certainly truncated even if the model finished a sentence
+ *     by chance).
+ *
+ * ASCII-only.
+ */
+/** Default margin: how close to max_tokens counts as truncation.
+ *  A response within 32 tokens of the cap is treated as truncated.
+ *  Tuned to catch boundary cases without false positives on
+ *  responses that legitimately end near the cap. */
+export declare const TRUNCATION_MARGIN_TOKENS = 32;
+export interface TruncationDetection {
+    /** True if the response is treated as truncated. */
+    truncated: boolean;
+    /** Reason text for diagnostics. Empty if not truncated. */
+    reason: string;
+    /** The output tokens the provider reported. */
+    output_tokens: number;
+    /** The max_tokens limit the caller requested. */
+    max_tokens: number;
+    /** How many tokens away from the cap (max_tokens - output_tokens). */
+    margin: number;
+}
+/** Inspect a response. Returns {truncated: true, ...} when the
+ *  output_tokens are within MARGIN of max_tokens, OR when the
+ *  provider's stop_reason explicitly says max_tokens (as a
+ *  secondary signal -- the arithmetic check is primary).
+ *
+ *  Both args are required. If the caller does not know
+ *  max_tokens (e.g. a streaming response from a provider that
+ *  refused to honour the cap), pass 0 and we return
+ *  {truncated: false} -- we cannot detect without it. */
+export declare function detectTruncation(opts: {
+    output_tokens: number;
+    max_tokens: number;
+    stop_reason?: string;
+    margin?: number;
+}): TruncationDetection;
+/** Helper to format the truncation banner appended to user-visible
+ *  responses. Returns empty string if not truncated.
+ *
+ *  The banner is intentionally short -- it does NOT include the
+ *  full ForgeError block; the renderer wires that separately via
+ *  renderForgeError(E_RESPONSE_TRUNCATED, {...}). This helper is
+ *  for the trailing inline note.
+ *
+ *  alpha.59z.15 -- localised via i18n. The banner text comes from
+ *  `error.response_truncated.banner` in src/i18n/catalogs/*.json
+ *  with {max} and {suggested} substituted in. */
+export declare function truncationBanner(d: TruncationDetection, lang?: import('../i18n/index.js').SupportedLanguage): Promise<string>;
+//# sourceMappingURL=truncation_detector.d.ts.map

package/dist/core/truncation_detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"truncation_detector.d.ts","sourceRoot":"","sources":["../../src/core/truncation_detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;oDAGoD;AACpD,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAE3C,MAAM,WAAW,mBAAmB;IAClC,oDAAoD;IACpD,SAAS,EAAE,OAAO,CAAC;IACnB,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,aAAa,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;yDAQyD;AACzD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,mBAAmB,CA4DtB;AAED;;;;;;;;;;iDAUiD;AACjD,wBAAsB,gBAAgB,CACpC,CAAC,EAAE,mBAAmB,EACtB,IAAI,CAAC,EAAE,OAAO,kBAAkB,EAAE,iBAAiB,GAClD,OAAO,CAAC,MAAM,CAAC,CAQjB"}

package/dist/core/truncation_detector.js

@@ -0,0 +1,115 @@
+/**
+ * F104 -- Truncation detector.
+ *
+ * Detects when an LLM response was cut off by the max_tokens cap.
+ * Pablo's insight 2026-06-03: instead of trusting the provider's
+ * stop_reason field (which varies in shape across Anthropic /
+ * OpenAI / Google / xAI / Mistral / DeepSeek / Cohere), compare
+ * the reported output_tokens against the requested max_tokens
+ * with a small safety margin. If output_tokens >= max_tokens -
+ * MARGIN, treat the response as truncated.
+ *
+ * Rationale:
+ *   - Provider-agnostic: every provider reports output_tokens
+ *     (or input_tokens we can derive output from). stop_reason
+ *     names + values differ.
+ *   - Robust: simple arithmetic, no string parsing.
+ *   - Conservative: we use a small margin to catch boundary
+ *     cases (e.g. response landed at 8190 of 8192 -- almost
+ *     certainly truncated even if the model finished a sentence
+ *     by chance).
+ *
+ * ASCII-only.
+ */
+/** Default margin: how close to max_tokens counts as truncation.
+ *  A response within 32 tokens of the cap is treated as truncated.
+ *  Tuned to catch boundary cases without false positives on
+ *  responses that legitimately end near the cap. */
+export const TRUNCATION_MARGIN_TOKENS = 32;
+/** Inspect a response. Returns {truncated: true, ...} when the
+ *  output_tokens are within MARGIN of max_tokens, OR when the
+ *  provider's stop_reason explicitly says max_tokens (as a
+ *  secondary signal -- the arithmetic check is primary).
+ *
+ *  Both args are required. If the caller does not know
+ *  max_tokens (e.g. a streaming response from a provider that
+ *  refused to honour the cap), pass 0 and we return
+ *  {truncated: false} -- we cannot detect without it. */
+export function detectTruncation(opts) {
+    const output = Math.max(0, Math.floor(opts.output_tokens || 0));
+    const max = Math.max(0, Math.floor(opts.max_tokens || 0));
+    const margin = Math.max(0, opts.margin ?? TRUNCATION_MARGIN_TOKENS);
+    if (max === 0) {
+        /* Unknown cap -- can't decide via arithmetic. Fall back to
+         * the stop_reason signal alone. */
+        if (opts.stop_reason === 'max_tokens' || opts.stop_reason === 'length') {
+            return {
+                truncated: true,
+                reason: 'provider reported stop_reason=' + opts.stop_reason + ' (max_tokens unknown to caller)',
+                output_tokens: output,
+                max_tokens: max,
+                margin: 0,
+            };
+        }
+        return {
+            truncated: false,
+            reason: '',
+            output_tokens: output,
+            max_tokens: max,
+            margin: 0,
+        };
+    }
+    const distance = max - output;
+    if (distance <= margin) {
+        return {
+            truncated: true,
+            reason: 'output_tokens=' + output + ' is within ' + margin + ' of max_tokens=' + max
+                + (opts.stop_reason ? ' (provider stop_reason=' + opts.stop_reason + ')' : ''),
+            output_tokens: output,
+            max_tokens: max,
+            margin: distance,
+        };
+    }
+    /* Secondary signal: even if arithmetic says we have headroom,
+     * trust the provider if it explicitly says it stopped due to
+     * max_tokens (provider may have inflated output_tokens
+     * estimate, or applied a stricter internal cap). */
+    if (opts.stop_reason === 'max_tokens' || opts.stop_reason === 'length') {
+        return {
+            truncated: true,
+            reason: 'provider reported stop_reason=' + opts.stop_reason + ' (arithmetic would have allowed continuation: ' + distance + ' tokens of headroom)',
+            output_tokens: output,
+            max_tokens: max,
+            margin: distance,
+        };
+    }
+    return {
+        truncated: false,
+        reason: '',
+        output_tokens: output,
+        max_tokens: max,
+        margin: distance,
+    };
+}
+/** Helper to format the truncation banner appended to user-visible
+ *  responses. Returns empty string if not truncated.
+ *
+ *  The banner is intentionally short -- it does NOT include the
+ *  full ForgeError block; the renderer wires that separately via
+ *  renderForgeError(E_RESPONSE_TRUNCATED, {...}). This helper is
+ *  for the trailing inline note.
+ *
+ *  alpha.59z.15 -- localised via i18n. The banner text comes from
+ *  `error.response_truncated.banner` in src/i18n/catalogs/*.json
+ *  with {max} and {suggested} substituted in. */
+export async function truncationBanner(d, lang) {
+    if (!d.truncated)
+        return '';
+    const { tForLang } = await import('../i18n/index.js');
+    const text = tForLang(lang ?? 'es', 'error.response_truncated.banner', {
+        max: d.max_tokens,
+        suggested: d.max_tokens * 2,
+    });
+    return '\n\n' + text;
+}
+//# sourceMappingURL=truncation_detector.js.map

package/dist/core/truncation_detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"truncation_detector.js","sourceRoot":"","sources":["../../src/core/truncation_detector.ts"],"names":[],"mappings":"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"}