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

package/dist/core/doctrine_resolver.js

@@ -0,0 +1,108 @@
+/**
+ * Doctrine resolver (alpha.59z.0).
+ *
+ * On-demand fetch of docrine blocks (long-form rules + reference
+ * material) so the system prompt does not have to carry them
+ * every turn. Same pattern as yujin.nac3.discover-schemas: the
+ * LLM sees a short pointer + calls the resolver when it needs
+ * the full text.
+ *
+ * Storage: docs/doctrine/{slug}.md -- one markdown file per
+ * doctrine block. Authored manually. Cached in-process; cache
+ * invalidates by mtime on each lookup (so dev iterations don't
+ * require restart).
+ *
+ * Known slugs (alpha.59z.0):
+ *  - workflow        -- 6 phases / 18 steps reference
+ *  - nac3-attrs      -- the 5 data-nac-* HTML attributes
+ *  - g-doc           -- generation doctrine for adopter apps
+ *
+ * More slugs added in alpha.59z.4 / .5 (pizarron-condensed,
+ * r8-modal, gates).
+ *
+ * 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);
+const DOCTRINE_DIR_HINTS = [
+    /* dist/core -> ../../docs/doctrine (repo root) */
+    path.resolve(__dirname, '..', '..', 'docs', 'doctrine'),
+    /* dist/core -> ../docs/doctrine (after copy_qa_assets bundles them) */
+    path.resolve(__dirname, '..', 'docs', 'doctrine'),
+    /* src/core -> ../../docs/doctrine */
+    path.resolve(__dirname, '..', '..', 'docs', 'doctrine'),
+    /* cwd / docs/doctrine */
+    path.resolve(process.cwd(), 'docs', 'doctrine'),
+];
+const _cache = new Map();
+/** Slug must be kebab-case, no path separators. Defensive against
+ *  path traversal -- the resolver only opens files inside the
+ *  doctrine dirs above. */
+function isValidSlug(slug) {
+    return /^[a-z0-9][a-z0-9-]{0,60}$/.test(slug);
+}
+async function resolveDoctrineFile(slug) {
+    for (const dir of DOCTRINE_DIR_HINTS) {
+        const p = path.join(dir, slug + '.md');
+        try {
+            const stat = await fs.stat(p);
+            if (stat.isFile()) {
+                return { path: p, mtimeMs: stat.mtimeMs };
+            }
+        }
+        catch { /* try next */ }
+    }
+    return null;
+}
+/** Force-clear cache. Used by tests. */
+export function _clearDoctrineCache() {
+    _cache.clear();
+}
+/** Fetch a single doctrine. Returns the markdown content. */
+export async function getDoctrine(slug) {
+    if (!isValidSlug(slug)) {
+        return { ok: false, slug, error: 'invalid slug -- must be kebab-case, max 60 chars' };
+    }
+    const file = await resolveDoctrineFile(slug);
+    if (!file) {
+        const list = await listDoctrineSlugs();
+        return { ok: false, slug, error: 'doctrine not found', available: list };
+    }
+    /* Cache check by mtime. */
+    const cached = _cache.get(slug);
+    if (cached && cached.mtimeMs === file.mtimeMs && cached.resolvedPath === file.path) {
+        return { ok: true, slug, content: cached.content, source: file.path };
+    }
+    const content = await fs.readFile(file.path, 'utf-8');
+    _cache.set(slug, { content, mtimeMs: file.mtimeMs, resolvedPath: file.path });
+    return { ok: true, slug, content, source: file.path };
+}
+/** Fetch multiple doctrines in one round (bulk). Same return shape
+ *  as nac3 discover-schemas: keyed object. */
+export async function getDoctrines(slugs) {
+    const out = {};
+    for (const s of slugs) {
+        out[s] = await getDoctrine(s);
+    }
+    return out;
+}
+/** List the available doctrine slugs (markdown files in any
+ *  doctrine dir). Used for the discovery verb. */
+export async function listDoctrineSlugs() {
+    const seen = new Set();
+    for (const dir of DOCTRINE_DIR_HINTS) {
+        try {
+            const files = await fs.readdir(dir);
+            for (const f of files) {
+                if (f.endsWith('.md'))
+                    seen.add(f.slice(0, -3));
+            }
+        }
+        catch { /* dir missing -- ok */ }
+    }
+    return Array.from(seen).sort();
+}
+//# sourceMappingURL=doctrine_resolver.js.map

package/dist/core/doctrine_resolver.js.map

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

package/dist/core/error_catalog.d.ts

@@ -0,0 +1,80 @@
+/**
+ * F104 -- Error UX Discipline catalog (alpha.59z.15: i18n-aware).
+ *
+ * Every Forge error surface (chat panel, CLI stderr, modal toast,
+ * SSE event, worker HTTP response) MUST produce a ForgeError
+ * object with the 4 mandatory fields below + optional cmd / docs.
+ *
+ * alpha.59z.15 -- catalog entries reference i18n keys instead of
+ * Spanish-only strings. renderForgeError() accepts an optional
+ * `lang` parameter and resolves via tForLang() with Spanish
+ * fallback. The worker emits {code, context} only; the client
+ * hydrates with its user language.
+ *
+ * Codes are append-only. Catalog keys live in
+ * src/i18n/catalogs/<lang>.json under "error.<code>.what|why|fix|cmd"
+ * and "error_ui.*" for the formatter labels.
+ */
+import { type SupportedLanguage } from '../i18n/index.js';
+export type ForgeErrorSeverity = 'info' | 'warning' | 'error' | 'fatal';
+export interface ForgeError {
+    /** Stable machine code. Append-only. Used by telemetry + docs. */
+    code: string;
+    /** Human-readable summary of what happened. Localised. */
+    what: string;
+    /** Root cause -- why this happened. Localised. */
+    why: string;
+    /** Concrete action the user can take to fix or work around. Localised. */
+    fix: string;
+    /** Severity for renderer styling. */
+    severity: ForgeErrorSeverity;
+    /** Optional exact CLI command the user can copy + run. Localised. */
+    cmd?: string;
+    /** Optional path to local doc (resolved by the panel to docs/errors/<code>.html). */
+    docs_path?: string;
+    /** Optional seconds-until-retry-allowed (e.g. for rate limits). */
+    retry_in_sec?: number;
+    /** Optional context: variables interpolated into what/why/fix at render time. */
+    context?: Record<string, string | number | boolean>;
+}
+/** Frontier tier monthly token cap reached (managed brain only). */
+export declare const E_CAP_FRONTIER_EXHAUSTED = "E_CAP_FRONTIER_EXHAUSTED";
+/** Eco tier monthly token cap reached (managed brain only). */
+export declare const E_CAP_ECO_EXHAUSTED = "E_CAP_ECO_EXHAUSTED";
+/** The tier requested is not enabled on this plan. */
+export declare const E_TIER_NOT_IN_PLAN = "E_TIER_NOT_IN_PLAN";
+/** The LLM response was truncated -- ran out of output tokens mid-reply. */
+export declare const E_RESPONSE_TRUNCATED = "E_RESPONSE_TRUNCATED";
+/** The R8 modal trace_id is stale or has no pending approval. */
+export declare const E_MODAL_TRACE_STALE = "E_MODAL_TRACE_STALE";
+/** BYOK key required but missing from the Vault. */
+export declare const E_BYOK_KEY_MISSING = "E_BYOK_KEY_MISSING";
+/** The HITO 4 worker is unreachable (network / DNS / outage). */
+export declare const E_WORKER_UNREACHABLE = "E_WORKER_UNREACHABLE";
+/** Vault decryption failed -- master key wrong or file corrupted. */
+export declare const E_VAULT_DECRYPT_FAILED = "E_VAULT_DECRYPT_FAILED";
+/** shell.exec was classified destructive but user rejected the modal. */
+export declare const E_SHELL_EXEC_REJECTED = "E_SHELL_EXEC_REJECTED";
+/** No active project registered + the verb requires a project root. */
+export declare const E_PROJECT_NOT_REGISTERED = "E_PROJECT_NOT_REGISTERED";
+/** Build a ForgeError from a code + context.
+ *
+ *  @param code     Stable error code (E_*).
+ *  @param context  Variables interpolated into what/why/fix/cmd
+ *                  (e.g. {plan, cap, used, tier, ...}).
+ *  @param lang     Optional target language. Falls back to the
+ *                  current i18n session language; falls back
+ *                  again to 'es' (the canonical source). */
+export declare function renderForgeError(code: string, context?: Record<string, string | number | boolean>, lang?: SupportedLanguage): ForgeError;
+/** Return the list of registered codes (for tests / docs generator). */
+export declare function listErrorCodes(): string[];
+/** Type guard. */
+export declare function isForgeError(x: unknown): x is ForgeError;
+/** Get the catalog entry metadata for a code (severity, docs path, etc).
+ *  Returns null if the code is unknown. */
+export declare function getCatalogEntry(code: string): {
+    severity: ForgeErrorSeverity;
+    docs_path: string;
+    has_cmd: boolean;
+} | null;
+//# sourceMappingURL=error_catalog.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"error_catalog.d.ts","sourceRoot":"","sources":["../../src/core/error_catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAY,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAEpE,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;AAExE,MAAM,WAAW,UAAU;IACzB,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAC;IACZ,0EAA0E;IAC1E,GAAG,EAAE,MAAM,CAAC;IACZ,qCAAqC;IACrC,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,qEAAqE;IACrE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qFAAqF;IACrF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;CACrD;AAMD,oEAAoE;AACpE,eAAO,MAAM,wBAAwB,6BAA6B,CAAC;AACnE,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,wBAAwB,CAAC;AACzD,sDAAsD;AACtD,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AACvD,4EAA4E;AAC5E,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAC3D,iEAAiE;AACjE,eAAO,MAAM,mBAAmB,wBAAwB,CAAC;AACzD,oDAAoD;AACpD,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AACvD,iEAAiE;AACjE,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAC3D,qEAAqE;AACrE,eAAO,MAAM,sBAAsB,2BAA2B,CAAC;AAC/D,yEAAyE;AACzE,eAAO,MAAM,qBAAqB,0BAA0B,CAAC;AAC7D,uEAAuE;AACvE,eAAO,MAAM,wBAAwB,6BAA6B,CAAC;AA2EnE;;;;;;;4DAO4D;AAC5D,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAM,EACvD,IAAI,CAAC,EAAE,iBAAiB,GACvB,UAAU,CA4BZ;AAcD,wEAAwE;AACxE,wBAAgB,cAAc,IAAI,MAAM,EAAE,CAEzC;AAED,kBAAkB;AAClB,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,UAAU,CAOxD;AAED;2CAC2C;AAC3C,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,kBAAkB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAI1H"}

package/dist/core/error_catalog.js

@@ -0,0 +1,168 @@
+/**
+ * F104 -- Error UX Discipline catalog (alpha.59z.15: i18n-aware).
+ *
+ * Every Forge error surface (chat panel, CLI stderr, modal toast,
+ * SSE event, worker HTTP response) MUST produce a ForgeError
+ * object with the 4 mandatory fields below + optional cmd / docs.
+ *
+ * alpha.59z.15 -- catalog entries reference i18n keys instead of
+ * Spanish-only strings. renderForgeError() accepts an optional
+ * `lang` parameter and resolves via tForLang() with Spanish
+ * fallback. The worker emits {code, context} only; the client
+ * hydrates with its user language.
+ *
+ * Codes are append-only. Catalog keys live in
+ * src/i18n/catalogs/<lang>.json under "error.<code>.what|why|fix|cmd"
+ * and "error_ui.*" for the formatter labels.
+ */
+import { tForLang } from '../i18n/index.js';
+/* ===================================================================
+ * Error code catalog
+ * ================================================================ */
+/** Frontier tier monthly token cap reached (managed brain only). */
+export const E_CAP_FRONTIER_EXHAUSTED = 'E_CAP_FRONTIER_EXHAUSTED';
+/** Eco tier monthly token cap reached (managed brain only). */
+export const E_CAP_ECO_EXHAUSTED = 'E_CAP_ECO_EXHAUSTED';
+/** The tier requested is not enabled on this plan. */
+export const E_TIER_NOT_IN_PLAN = 'E_TIER_NOT_IN_PLAN';
+/** The LLM response was truncated -- ran out of output tokens mid-reply. */
+export const E_RESPONSE_TRUNCATED = 'E_RESPONSE_TRUNCATED';
+/** The R8 modal trace_id is stale or has no pending approval. */
+export const E_MODAL_TRACE_STALE = 'E_MODAL_TRACE_STALE';
+/** BYOK key required but missing from the Vault. */
+export const E_BYOK_KEY_MISSING = 'E_BYOK_KEY_MISSING';
+/** The HITO 4 worker is unreachable (network / DNS / outage). */
+export const E_WORKER_UNREACHABLE = 'E_WORKER_UNREACHABLE';
+/** Vault decryption failed -- master key wrong or file corrupted. */
+export const E_VAULT_DECRYPT_FAILED = 'E_VAULT_DECRYPT_FAILED';
+/** shell.exec was classified destructive but user rejected the modal. */
+export const E_SHELL_EXEC_REJECTED = 'E_SHELL_EXEC_REJECTED';
+/** No active project registered + the verb requires a project root. */
+export const E_PROJECT_NOT_REGISTERED = 'E_PROJECT_NOT_REGISTERED';
+const CATALOG = {
+    [E_CAP_FRONTIER_EXHAUSTED]: {
+        key_prefix: 'error.cap_frontier_exhausted',
+        has_cmd: true, severity: 'error',
+        docs_path: 'docs/errors/E_CAP_FRONTIER_EXHAUSTED.html',
+    },
+    [E_CAP_ECO_EXHAUSTED]: {
+        key_prefix: 'error.cap_eco_exhausted',
+        has_cmd: true, severity: 'error',
+        docs_path: 'docs/errors/E_CAP_ECO_EXHAUSTED.html',
+    },
+    [E_TIER_NOT_IN_PLAN]: {
+        key_prefix: 'error.tier_not_in_plan',
+        has_cmd: true, severity: 'error',
+        docs_path: 'docs/errors/E_TIER_NOT_IN_PLAN.html',
+    },
+    [E_RESPONSE_TRUNCATED]: {
+        key_prefix: 'error.response_truncated',
+        has_cmd: true, severity: 'warning',
+        docs_path: 'docs/errors/E_RESPONSE_TRUNCATED.html',
+    },
+    [E_MODAL_TRACE_STALE]: {
+        key_prefix: 'error.modal_trace_stale',
+        has_cmd: true, severity: 'warning',
+        docs_path: 'docs/errors/E_MODAL_TRACE_STALE.html',
+    },
+    [E_BYOK_KEY_MISSING]: {
+        key_prefix: 'error.byok_key_missing',
+        has_cmd: true, severity: 'error',
+        docs_path: 'docs/errors/E_BYOK_KEY_MISSING.html',
+    },
+    [E_WORKER_UNREACHABLE]: {
+        key_prefix: 'error.worker_unreachable',
+        has_cmd: true, severity: 'error',
+        docs_path: 'docs/errors/E_WORKER_UNREACHABLE.html',
+    },
+    [E_VAULT_DECRYPT_FAILED]: {
+        key_prefix: 'error.vault_decrypt_failed',
+        has_cmd: true, severity: 'fatal',
+        docs_path: 'docs/errors/E_VAULT_DECRYPT_FAILED.html',
+    },
+    [E_SHELL_EXEC_REJECTED]: {
+        key_prefix: 'error.shell_exec_rejected',
+        has_cmd: false, severity: 'info',
+        docs_path: 'docs/errors/E_SHELL_EXEC_REJECTED.html',
+    },
+    [E_PROJECT_NOT_REGISTERED]: {
+        key_prefix: 'error.project_not_registered',
+        has_cmd: true, severity: 'error',
+        docs_path: 'docs/errors/E_PROJECT_NOT_REGISTERED.html',
+    },
+};
+/* ===================================================================
+ * Public API
+ * ================================================================ */
+/** Build a ForgeError from a code + context.
+ *
+ *  @param code     Stable error code (E_*).
+ *  @param context  Variables interpolated into what/why/fix/cmd
+ *                  (e.g. {plan, cap, used, tier, ...}).
+ *  @param lang     Optional target language. Falls back to the
+ *                  current i18n session language; falls back
+ *                  again to 'es' (the canonical source). */
+export function renderForgeError(code, context = {}, lang) {
+    const entry = CATALOG[code];
+    if (!entry) {
+        /* Unknown code -- emit a stub from the i18n catalog so the
+         * message is also localised. */
+        return {
+            code,
+            what: lang ? tForLang(lang, 'error_ui.unknown.what', { code }) : tForLang('es', 'error_ui.unknown.what', { code }),
+            why: lang ? tForLang(lang, 'error_ui.unknown.why', { code }) : tForLang('es', 'error_ui.unknown.why', { code }),
+            fix: lang ? tForLang(lang, 'error_ui.unknown.fix', { code }) : tForLang('es', 'error_ui.unknown.fix', { code }),
+            severity: 'error',
+            context,
+        };
+    }
+    const params = ctxToParams(context);
+    const resolveKey = (suffix) => lang ? tForLang(lang, entry.key_prefix + '.' + suffix, params)
+        : tForLang('es', entry.key_prefix + '.' + suffix, params);
+    return {
+        code,
+        what: resolveKey('what'),
+        why: resolveKey('why'),
+        fix: resolveKey('fix'),
+        cmd: entry.has_cmd ? resolveKey('cmd') : undefined,
+        severity: entry.severity,
+        docs_path: entry.docs_path,
+        context,
+    };
+}
+/** The i18n interpolate() helper accepts string | number; coerce
+ *  booleans to "true"/"false" so callers can pass {is_admin: true}
+ *  without TypeScript yelling. */
+function ctxToParams(context) {
+    const out = {};
+    for (const [k, v] of Object.entries(context)) {
+        if (typeof v === 'boolean')
+            out[k] = v ? 'true' : 'false';
+        else
+            out[k] = v;
+    }
+    return out;
+}
+/** Return the list of registered codes (for tests / docs generator). */
+export function listErrorCodes() {
+    return Object.keys(CATALOG);
+}
+/** Type guard. */
+export function isForgeError(x) {
+    if (!x || typeof x !== 'object')
+        return false;
+    const e = x;
+    return typeof e.code === 'string'
+        && typeof e.what === 'string'
+        && typeof e.why === 'string'
+        && typeof e.fix === 'string';
+}
+/** Get the catalog entry metadata for a code (severity, docs path, etc).
+ *  Returns null if the code is unknown. */
+export function getCatalogEntry(code) {
+    const entry = CATALOG[code];
+    if (!entry)
+        return null;
+    return { severity: entry.severity, docs_path: entry.docs_path, has_cmd: entry.has_cmd };
+}
+//# sourceMappingURL=error_catalog.js.map

package/dist/core/error_catalog.js.map

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

package/dist/core/error_formatter.d.ts

@@ -0,0 +1,30 @@
+/**
+ * F104 -- Renderers for ForgeError surfaces.
+ *
+ * Three surfaces:
+ *   1. CLI stderr: formatForgeErrorCli(err) -> ANSI-coloured block.
+ *   2. Chat panel HTML: formatForgeErrorHtml(err) -> red block with
+ *      copy-cmd button. Safe HTML (escaped).
+ *   3. JSON wire (SSE / HTTP body): formatForgeErrorJson(err) ->
+ *      the ForgeError object itself, ready to JSON.stringify.
+ *
+ * ASCII-only.
+ */
+import type { ForgeError } from './error_catalog.js';
+import { type SupportedLanguage } from '../i18n/index.js';
+/** Format a ForgeError for CLI stderr output.
+ *  @param err   The error.
+ *  @param lang  Optional UI language for the labels. Default 'es'. */
+export declare function formatForgeErrorCli(err: ForgeError, lang?: SupportedLanguage): string;
+/** Format a ForgeError as safe HTML for the chat panel. The panel
+ *  is expected to have CSS for .forge-err / .forge-err--{severity}
+ *  / .forge-err__copy-btn etc; this returns ONLY the markup.
+ *  @param err   The error.
+ *  @param lang  Optional UI language for the labels. Default 'es'. */
+export declare function formatForgeErrorHtml(err: ForgeError, lang?: SupportedLanguage): string;
+/** Strip undefined keys for clean JSON serialisation. */
+export declare function formatForgeErrorJson(err: ForgeError): Record<string, unknown>;
+/** Serialise a ForgeError as a Server-Sent-Events block.
+ *  Stream consumers should listen for event: forge_error. */
+export declare function forgeErrorAsSseEvent(err: ForgeError): string;
+//# sourceMappingURL=error_formatter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"error_formatter.d.ts","sourceRoot":"","sources":["../../src/core/error_formatter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAsB,MAAM,oBAAoB,CAAC;AACzE,OAAO,EAAY,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AA+BpE;;sEAEsE;AACtE,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,GAAE,iBAAwB,GAAG,MAAM,CA4B3F;AAwBD;;;;sEAIsE;AACtE,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,GAAE,iBAAwB,GAAG,MAAM,CA4B5F;AAMD,yDAAyD;AACzD,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAa7E;AAMD;6DAC6D;AAC7D,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAG5D"}

package/dist/core/error_formatter.js

@@ -0,0 +1,155 @@
+/**
+ * F104 -- Renderers for ForgeError surfaces.
+ *
+ * Three surfaces:
+ *   1. CLI stderr: formatForgeErrorCli(err) -> ANSI-coloured block.
+ *   2. Chat panel HTML: formatForgeErrorHtml(err) -> red block with
+ *      copy-cmd button. Safe HTML (escaped).
+ *   3. JSON wire (SSE / HTTP body): formatForgeErrorJson(err) ->
+ *      the ForgeError object itself, ready to JSON.stringify.
+ *
+ * ASCII-only.
+ */
+import { tForLang } from '../i18n/index.js';
+/* ===================================================================
+ * CLI formatter (ANSI colours, stderr-friendly)
+ * ================================================================ */
+function ansi(code, text) {
+    if (!process.stderr.isTTY)
+        return text;
+    return '\x1b[' + code + 'm' + text + '\x1b[0m';
+}
+function severityColour(s) {
+    switch (s) {
+        case 'info': return (t) => ansi('36', t); // cyan
+        case 'warning': return (t) => ansi('33', t); // yellow
+        case 'error': return (t) => ansi('31', t); // red
+        case 'fatal': return (t) => ansi('1;31', t); // bold red
+        default: return (t) => t;
+    }
+}
+function severityLabel(s, lang = 'es') {
+    switch (s) {
+        case 'info': return tForLang(lang, 'error_ui.severity.info');
+        case 'warning': return tForLang(lang, 'error_ui.severity.warning');
+        case 'error': return tForLang(lang, 'error_ui.severity.error');
+        case 'fatal': return tForLang(lang, 'error_ui.severity.fatal');
+        default: return tForLang(lang, 'error_ui.severity.error');
+    }
+}
+/** Format a ForgeError for CLI stderr output.
+ *  @param err   The error.
+ *  @param lang  Optional UI language for the labels. Default 'es'. */
+export function formatForgeErrorCli(err, lang = 'es') {
+    const col = severityColour(err.severity);
+    const sep = ansi('90', '-'.repeat(72)); // dim dashes
+    const head = col('[' + severityLabel(err.severity, lang) + '] ' + err.code);
+    const parts = [];
+    parts.push('');
+    parts.push(sep);
+    parts.push(head);
+    parts.push(sep);
+    parts.push(ansi('1', tForLang(lang, 'error_ui.label.what') + ':') + ' ' + err.what);
+    parts.push(ansi('1', tForLang(lang, 'error_ui.label.why') + ':') + ' ' + err.why);
+    parts.push(ansi('1', tForLang(lang, 'error_ui.label.fix') + ':') + ' ' + err.fix);
+    if (err.cmd) {
+        parts.push('');
+        parts.push(ansi('1', tForLang(lang, 'error_ui.label.cmd') + ':') + ' ' + ansi('32', err.cmd));
+    }
+    if (err.docs_path) {
+        parts.push('');
+        parts.push(ansi('90', tForLang(lang, 'error_ui.label.docs') + ': ' + err.docs_path));
+    }
+    if (typeof err.retry_in_sec === 'number' && err.retry_in_sec > 0) {
+        parts.push('');
+        parts.push(ansi('90', tForLang(lang, 'error_ui.label.retry') + ': ' + err.retry_in_sec + 's'));
+    }
+    parts.push(sep);
+    parts.push('');
+    return parts.join('\n');
+}
+/* ===================================================================
+ * HTML formatter (chat panel, safe)
+ * ================================================================ */
+function htmlEscape(s) {
+    return s.replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+function severityCssClass(s) {
+    switch (s) {
+        case 'info': return 'forge-err forge-err--info';
+        case 'warning': return 'forge-err forge-err--warn';
+        case 'error': return 'forge-err forge-err--error';
+        case 'fatal': return 'forge-err forge-err--fatal';
+        default: return 'forge-err';
+    }
+}
+/** Format a ForgeError as safe HTML for the chat panel. The panel
+ *  is expected to have CSS for .forge-err / .forge-err--{severity}
+ *  / .forge-err__copy-btn etc; this returns ONLY the markup.
+ *  @param err   The error.
+ *  @param lang  Optional UI language for the labels. Default 'es'. */
+export function formatForgeErrorHtml(err, lang = 'es') {
+    const cls = severityCssClass(err.severity);
+    const lvl = severityLabel(err.severity, lang);
+    const parts = [];
+    parts.push('<div class="' + cls + '" data-code="' + htmlEscape(err.code) + '">');
+    parts.push('  <div class="forge-err__head">');
+    parts.push('    <span class="forge-err__severity">' + htmlEscape(lvl) + '</span>');
+    parts.push('    <code class="forge-err__code">' + htmlEscape(err.code) + '</code>');
+    parts.push('  </div>');
+    parts.push('  <dl class="forge-err__body">');
+    parts.push('    <dt>' + htmlEscape(tForLang(lang, 'error_ui.label.what')) + '</dt><dd>' + htmlEscape(err.what) + '</dd>');
+    parts.push('    <dt>' + htmlEscape(tForLang(lang, 'error_ui.label.why')) + '</dt><dd>' + htmlEscape(err.why) + '</dd>');
+    parts.push('    <dt>' + htmlEscape(tForLang(lang, 'error_ui.label.fix')) + '</dt><dd>' + htmlEscape(err.fix) + '</dd>');
+    parts.push('  </dl>');
+    if (err.cmd) {
+        parts.push('  <div class="forge-err__cmd">');
+        parts.push('    <pre><code>' + htmlEscape(err.cmd) + '</code></pre>');
+        parts.push('    <button class="forge-err__copy-btn" data-cmd="' + htmlEscape(err.cmd) + '">' + htmlEscape(tForLang(lang, 'error_ui.copy_btn')) + '</button>');
+        parts.push('  </div>');
+    }
+    if (err.docs_path) {
+        parts.push('  <div class="forge-err__docs">' + htmlEscape(tForLang(lang, 'error_ui.label.docs')) + ': <code>' + htmlEscape(err.docs_path) + '</code></div>');
+    }
+    if (typeof err.retry_in_sec === 'number' && err.retry_in_sec > 0) {
+        parts.push('  <div class="forge-err__retry">' + htmlEscape(tForLang(lang, 'error_ui.label.retry')) + ' ' + err.retry_in_sec + 's</div>');
+    }
+    parts.push('</div>');
+    return parts.join('\n');
+}
+/* ===================================================================
+ * JSON wire format
+ * ================================================================ */
+/** Strip undefined keys for clean JSON serialisation. */
+export function formatForgeErrorJson(err) {
+    const out = {
+        code: err.code,
+        what: err.what,
+        why: err.why,
+        fix: err.fix,
+        severity: err.severity,
+    };
+    if (err.cmd)
+        out.cmd = err.cmd;
+    if (err.docs_path)
+        out.docs_path = err.docs_path;
+    if (typeof err.retry_in_sec === 'number')
+        out.retry_in_sec = err.retry_in_sec;
+    if (err.context && Object.keys(err.context).length > 0)
+        out.context = err.context;
+    return out;
+}
+/* ===================================================================
+ * SSE event helper
+ * ================================================================ */
+/** Serialise a ForgeError as a Server-Sent-Events block.
+ *  Stream consumers should listen for event: forge_error. */
+export function forgeErrorAsSseEvent(err) {
+    return 'event: forge_error\n'
+        + 'data: ' + JSON.stringify(formatForgeErrorJson(err)) + '\n\n';
+}
+//# sourceMappingURL=error_formatter.js.map

package/dist/core/error_formatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error_formatter.js","sourceRoot":"","sources":["../../src/core/error_formatter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,QAAQ,EAA0B,MAAM,kBAAkB,CAAC;AAEpE;;sEAEsE;AAEtE,SAAS,IAAI,CAAC,IAAY,EAAE,IAAY;IACtC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACvC,OAAO,OAAO,GAAG,IAAI,GAAG,GAAG,GAAG,IAAI,GAAG,SAAS,CAAC;AACjD,CAAC;AAED,SAAS,cAAc,CAAC,CAAqB;IAC3C,QAAQ,CAAC,EAAE,CAAC;QACV,KAAK,MAAM,CAAC,CAAI,OAAO,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAE,OAAO;QACrD,KAAK,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAE,SAAS;QACvD,KAAK,OAAO,CAAC,CAAG,OAAO,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAE,MAAM;QACpD,KAAK,OAAO,CAAC,CAAG,OAAO,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,WAAW;QAC1D,OAAO,CAAC,CAAQ,OAAO,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IAClC,CAAC;AACH,CAAC;AAED,SAAS,aAAa,CAAC,CAAqB,EAAE,OAA0B,IAAI;IAC1E,QAAQ,CAAC,EAAE,CAAC;QACV,KAAK,MAAM,CAAC,CAAI,OAAO,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC,CAAC;QAChE,KAAK,SAAS,CAAC,CAAC,OAAO,QAAQ,CAAC,IAAI,EAAE,2BAA2B,CAAC,CAAC;QACnE,KAAK,OAAO,CAAC,CAAG,OAAO,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC,CAAC;QACjE,KAAK,OAAO,CAAC,CAAG,OAAO,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC,CAAC;QACjE,OAAO,CAAC,CAAQ,OAAO,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC,CAAC;IACnE,CAAC;AACH,CAAC;AAED;;sEAEsE;AACtE,MAAM,UAAU,mBAAmB,CAAC,GAAe,EAAE,OAA0B,IAAI;IACjF,MAAM,GAAG,GAAG,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACzC,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAE,aAAa;IACtD,MAAM,IAAI,GAAG,GAAG,CAAC,GAAG,GAAG,aAAa,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;IAE5E,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjB,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;IACpF,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;IAClF,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;IAClF,IAAI,GAAG,CAAC,GAAG,EAAE,CAAC;QACZ,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,GAAG,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IAChG,CAAC;IACD,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;QAClB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC,GAAG,IAAI,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC;IACvF,CAAC;IACD,IAAI,OAAO,GAAG,CAAC,YAAY,KAAK,QAAQ,IAAI,GAAG,CAAC,YAAY,GAAG,CAAC,EAAE,CAAC;QACjE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC,GAAG,IAAI,GAAG,GAAG,CAAC,YAAY,GAAG,GAAG,CAAC,CAAC,CAAC;IACjG,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;sEAEsE;AAEtE,SAAS,UAAU,CAAC,CAAS;IAC3B,OAAO,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC;SACtB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC;SACvB,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAClC,CAAC;AAED,SAAS,gBAAgB,CAAC,CAAqB;IAC7C,QAAQ,CAAC,EAAE,CAAC;QACV,KAAK,MAAM,CAAC,CAAI,OAAO,2BAA2B,CAAC;QACnD,KAAK,SAAS,CAAC,CAAC,OAAO,2BAA2B,CAAC;QACnD,KAAK,OAAO,CAAC,CAAG,OAAO,4BAA4B,CAAC;QACpD,KAAK,OAAO,CAAC,CAAG,OAAO,4BAA4B,CAAC;QACpD,OAAO,CAAC,CAAQ,OAAO,WAAW,CAAC;IACrC,CAAC;AACH,CAAC;AAED;;;;sEAIsE;AACtE,MAAM,UAAU,oBAAoB,CAAC,GAAe,EAAE,OAA0B,IAAI;IAClF,MAAM,GAAG,GAAG,gBAAgB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC3C,MAAM,GAAG,GAAG,aAAa,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IAC9C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,cAAc,GAAG,GAAG,GAAG,eAAe,GAAG,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;IACjF,KAAK,CAAC,IAAI,CAAC,iCAAiC,CAAC,CAAC;IAC9C,KAAK,CAAC,IAAI,CAAC,wCAAwC,GAAG,UAAU,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC,CAAC;IACnF,KAAK,CAAC,IAAI,CAAC,oCAAoC,GAAG,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,CAAC;IACpF,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACvB,KAAK,CAAC,IAAI,CAAC,gCAAgC,CAAC,CAAC;IAC7C,KAAK,CAAC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC,CAAC,GAAG,WAAW,GAAG,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC;IAC1H,KAAK,CAAC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC,CAAC,GAAI,WAAW,GAAG,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,GAAI,OAAO,CAAC,CAAC;IAC1H,KAAK,CAAC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC,CAAC,GAAI,WAAW,GAAG,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC;IACzH,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACtB,IAAI,GAAG,CAAC,GAAG,EAAE,CAAC;QACZ,KAAK,CAAC,IAAI,CAAC,gCAAgC,CAAC,CAAC;QAC7C,KAAK,CAAC,IAAI,CAAC,iBAAiB,GAAG,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,eAAe,CAAC,CAAC;QACtE,KAAK,CAAC,IAAI,CAAC,oDAAoD,GAAG,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC;QAC9J,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACzB,CAAC;IACD,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;QAClB,KAAK,CAAC,IAAI,CAAC,iCAAiC,GAAG,UAAU,CAAC,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC,CAAC,GAAG,UAAU,GAAG,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,eAAe,CAAC,CAAC;IAC/J,CAAC;IACD,IAAI,OAAO,GAAG,CAAC,YAAY,KAAK,QAAQ,IAAI,GAAG,CAAC,YAAY,GAAG,CAAC,EAAE,CAAC;QACjE,KAAK,CAAC,IAAI,CAAC,kCAAkC,GAAG,UAAU,CAAC,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC,CAAC,GAAG,GAAG,GAAG,GAAG,CAAC,YAAY,GAAG,SAAS,CAAC,CAAC;IAC3I,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACrB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;sEAEsE;AAEtE,yDAAyD;AACzD,MAAM,UAAU,oBAAoB,CAAC,GAAe;IAClD,MAAM,GAAG,GAA4B;QACnC,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,GAAG,EAAG,GAAG,CAAC,GAAG;QACb,GAAG,EAAG,GAAG,CAAC,GAAG;QACb,QAAQ,EAAE,GAAG,CAAC,QAAQ;KACvB,CAAC;IACF,IAAI,GAAG,CAAC,GAAG;QAAE,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC;IAC/B,IAAI,GAAG,CAAC,SAAS;QAAE,GAAG,CAAC,SAAS,GAAG,GAAG,CAAC,SAAS,CAAC;IACjD,IAAI,OAAO,GAAG,CAAC,YAAY,KAAK,QAAQ;QAAE,GAAG,CAAC,YAAY,GAAG,GAAG,CAAC,YAAY,CAAC;IAC9E,IAAI,GAAG,CAAC,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC;QAAE,GAAG,CAAC,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;IAClF,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;sEAEsE;AAEtE;6DAC6D;AAC7D,MAAM,UAAU,oBAAoB,CAAC,GAAe;IAClD,OAAO,sBAAsB;UACtB,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,oBAAoB,CAAC,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC;AACvE,CAAC"}

package/dist/core/incomplete_detector.d.ts

@@ -0,0 +1,51 @@
+/**
+ * incomplete_detector.ts -- detects when an eco-tier reply looks
+ * confused / refused / truncated, so handleChat can escalate the
+ * turn to frontier without surfacing the bad reply to the user
+ * (alpha.57).
+ *
+ * The trigger is conservative on purpose. False positives mean
+ * we burn a frontier call when eco was fine; false negatives
+ * mean the user sees Gemini Lite's confused reply. We err on the
+ * "escalate" side only when there is a clear signal.
+ *
+ * Signals scanned:
+ *
+ *   1. Hallucinated-error phrases ("error de mapeo", "tuve un
+ *      error en el workflow", "i had an internal error",
+ *      "perdon, hubo un problema").
+ *   2. Refuse / dodge phrases ("no tengo suficiente informacion",
+ *      "necesito mas contexto para responder", "i need more
+ *      context to help with this", "no puedo procesar este
+ *      pedido", "no puedo ayudarte con eso").
+ *   3. Tool-round errors: any tool_round with is_error=true
+ *      whose error message looks like a schema / args failure
+ *      (typical Gemini misfire). NOT every tool error -- those
+ *      can be legitimate.
+ *   4. Length-vs-complexity mismatch: user prompt >= 120 chars
+ *      AND reply <= 60 chars AND no tool was called. That
+ *      signature reliably catches "I do not understand" replies.
+ *
+ * Output: { incomplete, signals[] }. The caller decides whether
+ * to escalate (it must also check the frontier budget cap).
+ *
+ * Cap: incomplete_detector runs ONLY when the served tier was
+ * eco. We never auto-escalate frontier -> something else.
+ *
+ * ASCII-only.
+ */
+import type { ToolRound } from '../chat/claude.js';
+export interface DetectInput {
+    /** The original user text that triggered the turn. */
+    user_text: string;
+    /** The reply the eco tier produced. */
+    reply_text: string;
+    /** Tool rounds the eco LLM executed during this turn. */
+    tool_rounds?: ToolRound[];
+}
+export interface DetectResult {
+    incomplete: boolean;
+    signals: string[];
+}
+export declare function detectIncomplete(input: DetectInput): DetectResult;
+//# sourceMappingURL=incomplete_detector.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"incomplete_detector.d.ts","sourceRoot":"","sources":["../../src/core/incomplete_detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD,MAAM,WAAW,WAAW;IAC1B,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,WAAW,CAAC,EAAE,SAAS,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAkDD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,YAAY,CAsDjE"}