agent-nuvira 2.6.14 → 2.7.0

package/dist/learning/routing-cache.js

@@ -0,0 +1,100 @@
+/**
+ * Routing decision cache (`src/learning/routing-cache.ts`) — AGENTIC_CAPABILITY_ASSESSMENT
+ * Addendum v4 Phase 2.
+ *
+ * The loop-first engine calls the AutoModelRouter on EVERY model turn. Each
+ * resolve() scores 22+ catalog providers across 5 dimensions (+ capability
+ * fit, context preflight, bandit sampling, registry filtering) — meaningful
+ * CPU work repeated for turns whose ROUTING INPUTS are identical.
+ *
+ * The cache keys on the STABLE routing inputs only — never the raw message
+ * text (every message is unique, so a message-keyed cache would never hit).
+ * Two turns hit the same entry when all of the following match:
+ *   agent type · task intent · complexity · preference mode · provider-health
+ *   signature (session exclusions + breaker + quota) · registry usable-count
+ * · cacheable resolve-option flags.
+ *
+ * Correctness rules:
+ * 1. Provider health is part of the KEY, so a provider failing mid-session
+ *    changes the key and can never be served a stale healthy-route.
+ * 2. TTL (default 30s) bounds staleness of everything NOT in the key
+ *    (benchmarks recorded by concurrent runs, bandit draws).
+ * 3. Non-deterministic layers are opt-out at the call site: when the caller
+ *    enables `useBandit` or `useMlRouter` with default settings, the cache
+ *    is still safe for SELECTION (deterministic at cold start) but a caller
+ *    may force-bypass via `bypass` for benchmark/explain flows that must
+ *    observe the live ranking.
+ * 4. `invalidateRoutingCache()` is called by the model registry refresh and
+ *    is safe to call anywhere — worst case one extra resolve.
+ */
+/** Module-level store — one cache per process (single-user CLI). */
+const store = new Map();
+/** Default TTL: short enough to bound staleness, long enough to cover a chat turn's repeated resolves. */
+export const DEFAULT_ROUTING_CACHE_TTL_MS = 30_000;
+/** Upper bound on entries — a pathological key-space cannot grow the map unbounded. */
+const MAX_ENTRIES = 256;
+/**
+ * Build the inputs signature from the STABLE routing inputs. Every part is
+ * stringified; null/undefined/'' parts are skipped (their absence IS signal —
+ * e.g. no NLU intent hint). Order-normalized: callers pass parts in a fixed
+ * order, but we join with '|' so collisions across part counts are visible.
+ */
+export function routingCacheSignature(parts) {
+    return parts
+        .map((p) => (p === null || p === undefined || p === '' ? '∅' : String(p)))
+        .join('|');
+}
+/**
+ * Get a cached routing decision. Returns undefined on miss/expiry.
+ * Expired entries are lazily dropped (no background sweeper — the CLI is
+ * single-user and resolve-frequency is bounded by turn count).
+ */
+export function getRoutingCache(signature) {
+    const entry = store.get(signature);
+    if (!entry)
+        return undefined;
+    if (Date.now() >= entry.expiresAt) {
+        store.delete(signature);
+        return undefined;
+    }
+    return entry.value;
+}
+/** Store a decision under a signature with the given TTL. */
+export function setRoutingCache(signature, value, ttlMs = DEFAULT_ROUTING_CACHE_TTL_MS) {
+    // Bound the map: drop the EXPIRED entries first, then (rare) evict oldest.
+    if (store.size >= MAX_ENTRIES) {
+        const now = Date.now();
+        for (const [k, v] of store) {
+            if (now >= v.expiresAt)
+                store.delete(k);
+        }
+        if (store.size >= MAX_ENTRIES) {
+            const oldest = store.keys().next().value;
+            if (oldest !== undefined)
+                store.delete(oldest);
+        }
+    }
+    store.set(signature, { value, expiresAt: Date.now() + Math.max(0, ttlMs), signature });
+}
+/**
+ * Memoize wrapper: return the cached decision for this signature, or compute
+ * + store. `compute` throwing propagates (never cache a failure — a transient
+ * registry read failure must not pin a degraded route for the TTL).
+ */
+export function withRoutingCache(signature, ttlMs, compute) {
+    const cached = getRoutingCache(signature);
+    if (cached !== undefined)
+        return cached;
+    const value = compute();
+    setRoutingCache(signature, value, ttlMs);
+    return value;
+}
+/** Clear the whole cache (registry refresh, tests, `nuvira models explain`). */
+export function invalidateRoutingCache() {
+    store.clear();
+}
+/** Test/inspection helper: current entry count. */
+export function routingCacheSize() {
+    return store.size;
+}
+//# sourceMappingURL=routing-cache.js.map

package/dist/learning/routing-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-cache.js","sourceRoot":"","sources":["../../src/learning/routing-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAUH,oEAAoE;AACpE,MAAM,KAAK,GAAG,IAAI,GAAG,EAAsC,CAAC;AAE5D,0GAA0G;AAC1G,MAAM,CAAC,MAAM,4BAA4B,GAAG,MAAM,CAAC;AAEnD,uFAAuF;AACvF,MAAM,WAAW,GAAG,GAAG,CAAC;AAExB;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAA0D;IAE1D,OAAO,KAAK;SACT,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;SACzE,IAAI,CAAC,GAAG,CAAC,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAI,SAAiB;IAClD,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,SAAS,CAAqC,CAAC;IACvE,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;QAClC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACxB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,KAAK,CAAC,KAAK,CAAC;AACrB,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,eAAe,CAAI,SAAiB,EAAE,KAAQ,EAAE,QAAgB,4BAA4B;IAC1G,2EAA2E;IAC3E,IAAI,KAAK,CAAC,IAAI,IAAI,WAAW,EAAE,CAAC;QAC9B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,KAAK,EAAE,CAAC;YAC3B,IAAI,GAAG,IAAI,CAAC,CAAC,SAAS;gBAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QAC1C,CAAC;QACD,IAAI,KAAK,CAAC,IAAI,IAAI,WAAW,EAAE,CAAC;YAC9B,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;YACzC,IAAI,MAAM,KAAK,SAAS;gBAAE,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IACD,KAAK,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC;AACzF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAC9B,SAAiB,EACjB,KAAyB,EACzB,OAAgB;IAEhB,MAAM,MAAM,GAAG,eAAe,CAAI,SAAS,CAAC,CAAC;IAC7C,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IACxC,MAAM,KAAK,GAAG,OAAO,EAAE,CAAC;IACxB,eAAe,CAAC,SAAS,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;IACzC,OAAO,KAAK,CAAC;AACf,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,sBAAsB;IACpC,KAAK,CAAC,KAAK,EAAE,CAAC;AAChB,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,gBAAgB;IAC9B,OAAO,KAAK,CAAC,IAAI,CAAC;AACpB,CAAC"}

package/dist/tools/loop-project-context.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Loop project context (`src/tools/loop-project-context.ts`) — AGENTIC_CAPABILITY_ASSESSMENT
+ * Addendum v4 Phase 1.4: Freebuff-pattern AMBIENT CONTEXT for the tool loop.
+ *
+ * The assessment's core finding: a single-loop agent needs the project shape
+ * in its context FROM TURN ZERO — a token-budgeted file tree, a git-state
+ * digest, and a deterministic project assessment — instead of spending an
+ * entire ReasonerAgent + ContextGathererAgent call to re-discover it.
+ *
+ * The dashboard already builds a snapshot (its project-context module) and
+ * injects it via `ctxOverrides.projectContext`; the CLI never sent one. This
+ * module is the CLI twin: bounded (~2K tokens), best-effort — a failure
+ * yields an EMPTY string, never a broken turn.
+ *
+ * Consumers: chat.ts `runChatAnswer` — when no explicit projectContext was
+ * provided and the cwd looks like a project, inject this as the
+ * `[Project context]` message. The dashboard path is unchanged.
+ *
+ * Design notes:
+ * - The tree walk is a bounded BFS (readdirSync, depth-capped, ignore-dir
+ *   filtered) rather than the orchestrator's full recursive builder — the
+ *   loop needs SHAPE, not a complete index, and must never take >50ms on a
+ *   huge repo. Entries past the line budget are truncated with an explicit
+ *   note (honest truncation, like Freebuff's `truncate-file-tree`).
+ * - Git digests run read-only commands with a 3s cap each and are omitted
+ *   entirely outside a git repo.
+ */
+/** True when the directory plausibly contains a project worth describing. */
+export declare function looksLikeProject(dir: string): boolean;
+/**
+ * Bounded BFS tree walk. Returns lines like `├── src/` with directories
+ * suffixed `/`, sorted dirs-first then files (deterministic ordering — the
+ * model sees a stable tree across turns, which keeps the prompt cache warm).
+ * Appends an ellipsis note when entries/depth were capped.
+ */
+export declare function walkBoundedTree(dir: string): string[];
+/**
+ * Build the bounded `[Project context]` block for the loop system context.
+ * Returns '' when the directory is not a project (caller injects nothing).
+ *
+ * Layout (Freebuff system-prompt parity):
+ *   ## Project   — cwd + deterministic assessment (language/framework/tests)
+ *   ## File tree — bounded BFS walk, honestly truncated
+ *   ## Git state — branch, dirty files, recent commits
+ */
+export declare function buildLoopProjectContext(dir: string): Promise<string>;
+//# sourceMappingURL=loop-project-context.d.ts.map

package/dist/tools/loop-project-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop-project-context.d.ts","sourceRoot":"","sources":["../../src/tools/loop-project-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAyBH,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAgBrD;AAaD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAwCrD;AAED;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAkE1E"}

package/dist/tools/loop-project-context.js

@@ -0,0 +1,210 @@
+/**
+ * Loop project context (`src/tools/loop-project-context.ts`) — AGENTIC_CAPABILITY_ASSESSMENT
+ * Addendum v4 Phase 1.4: Freebuff-pattern AMBIENT CONTEXT for the tool loop.
+ *
+ * The assessment's core finding: a single-loop agent needs the project shape
+ * in its context FROM TURN ZERO — a token-budgeted file tree, a git-state
+ * digest, and a deterministic project assessment — instead of spending an
+ * entire ReasonerAgent + ContextGathererAgent call to re-discover it.
+ *
+ * The dashboard already builds a snapshot (its project-context module) and
+ * injects it via `ctxOverrides.projectContext`; the CLI never sent one. This
+ * module is the CLI twin: bounded (~2K tokens), best-effort — a failure
+ * yields an EMPTY string, never a broken turn.
+ *
+ * Consumers: chat.ts `runChatAnswer` — when no explicit projectContext was
+ * provided and the cwd looks like a project, inject this as the
+ * `[Project context]` message. The dashboard path is unchanged.
+ *
+ * Design notes:
+ * - The tree walk is a bounded BFS (readdirSync, depth-capped, ignore-dir
+ *   filtered) rather than the orchestrator's full recursive builder — the
+ *   loop needs SHAPE, not a complete index, and must never take >50ms on a
+ *   huge repo. Entries past the line budget are truncated with an explicit
+ *   note (honest truncation, like Freebuff's `truncate-file-tree`).
+ * - Git digests run read-only commands with a 3s cap each and are omitted
+ *   entirely outside a git repo.
+ */
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { assessProject } from '../agents/prompt-assembly.js';
+/** Hard budget: the tree block is truncated to this many lines (~1.5K tokens). */
+const MAX_TREE_LINES = 60;
+/** Max tree depth (BFS) — deep node_modules-style nesting is noise at this budget. */
+const MAX_TREE_DEPTH = 4;
+/** Max entries per directory (a flat 300-file dir gets an ellipsis note). */
+const MAX_ENTRIES_PER_DIR = 25;
+/** Git status porcelain lines kept (a huge dirty tree truncates). */
+const MAX_GIT_STATUS_LINES = 30;
+/** Overall block budget (~2K tokens ≈ 8K chars) — hard-truncated with a note. */
+const MAX_BLOCK_CHARS = 8_000;
+/** Directories never worth showing in the ambient tree (build artifacts, deps). */
+const IGNORE_DIRS = new Set([
+    'node_modules', '.git', 'dist', 'build', '.next', 'out', 'coverage',
+    '.cache', '__pycache__', '.venv', 'venv', '.nuvira', '.turbo',
+]);
+/** True when the directory plausibly contains a project worth describing. */
+export function looksLikeProject(dir) {
+    try {
+        if (!existsSync(dir) || !statSync(dir).isDirectory())
+            return false;
+        const entries = readdirSync(dir);
+        if (entries.length === 0)
+            return false;
+        // A project has at least one source/config marker OR a .git dir — a bare
+        // home directory or an empty scratch dir adds noise, not signal.
+        const MARKERS = new Set([
+            'package.json', 'tsconfig.json', 'pyproject.toml', 'setup.py', 'requirements.txt',
+            'Cargo.toml', 'go.mod', 'pom.xml', 'build.gradle', 'Gemfile', 'composer.json',
+            '.git', 'Makefile', 'CMakeLists.txt', 'pubspec.yaml', 'mix.exs', 'buffconfig.json',
+        ]);
+        return entries.some((e) => MARKERS.has(e));
+    }
+    catch {
+        return false;
+    }
+}
+/** Run a read-only git command in `dir`; '' on any failure (best-effort). */
+function git(dir, args) {
+    try {
+        const r = spawnSync('git', args, { cwd: dir, encoding: 'utf-8', timeout: 3_000 });
+        if (r.status !== 0 || !r.stdout)
+            return '';
+        return r.stdout.trim();
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Bounded BFS tree walk. Returns lines like `├── src/` with directories
+ * suffixed `/`, sorted dirs-first then files (deterministic ordering — the
+ * model sees a stable tree across turns, which keeps the prompt cache warm).
+ * Appends an ellipsis note when entries/depth were capped.
+ */
+export function walkBoundedTree(dir) {
+    const lines = [];
+    let truncatedNote = false;
+    const walk = (current, prefix, depth) => {
+        if (depth > MAX_TREE_DEPTH || lines.length >= MAX_TREE_LINES) {
+            if (lines.length >= MAX_TREE_LINES)
+                truncatedNote = true;
+            return;
+        }
+        let entries;
+        try {
+            entries = readdirSync(current, { withFileTypes: true })
+                .filter((e) => !IGNORE_DIRS.has(e.name) && !e.name.startsWith('.'))
+                .map((e) => ({ name: e.name, isDir: e.isDirectory() }))
+                .sort((a, b) => (a.isDir === b.isDir ? a.name.localeCompare(b.name) : a.isDir ? -1 : 1));
+        }
+        catch {
+            return; // unreadable dir — skip silently
+        }
+        if (entries.length > MAX_ENTRIES_PER_DIR) {
+            entries = entries.slice(0, MAX_ENTRIES_PER_DIR);
+            truncatedNote = true;
+        }
+        entries.forEach((e, idx) => {
+            if (lines.length >= MAX_TREE_LINES) {
+                truncatedNote = true;
+                return;
+            }
+            const last = idx === entries.length - 1;
+            const tee = last ? '└── ' : '├── ';
+            lines.push(`${prefix}${tee}${e.name}${e.isDir ? '/' : ''}`);
+            if (e.isDir) {
+                walk(join(current, e.name), prefix + (last ? '    ' : '│   '), depth + 1);
+            }
+        });
+    };
+    walk(dir, '', 1);
+    if (truncatedNote)
+        lines.push('… (tree truncated to fit the context budget)');
+    return lines;
+}
+/**
+ * Build the bounded `[Project context]` block for the loop system context.
+ * Returns '' when the directory is not a project (caller injects nothing).
+ *
+ * Layout (Freebuff system-prompt parity):
+ *   ## Project   — cwd + deterministic assessment (language/framework/tests)
+ *   ## File tree — bounded BFS walk, honestly truncated
+ *   ## Git state — branch, dirty files, recent commits
+ */
+export async function buildLoopProjectContext(dir) {
+    try {
+        if (!looksLikeProject(dir))
+            return '';
+        const lines = [];
+        // ── Deterministic assessment (reuses the planner's own scanner) ──
+        try {
+            const a = assessProject(dir);
+            const bits = [];
+            if (a.language)
+                bits.push(`language: ${a.language}`);
+            if (a.framework)
+                bits.push(`framework: ${a.framework}`);
+            if (a.packageManager)
+                bits.push(`package manager: ${a.packageManager}`);
+            bits.push(a.isGreenfield ? 'empty/greenfield' : 'existing project');
+            bits.push(a.hasTests ? 'has tests' : 'no tests detected');
+            if (a.keyFiles?.length)
+                bits.push(`key files: ${a.keyFiles.slice(0, 8).join(', ')}`);
+            lines.push('## Project', `- path: ${dir}`, `- ${bits.join('; ')}`);
+        }
+        catch {
+            lines.push('## Project', `- path: ${dir}`);
+        }
+        // ── Bounded file tree ──
+        try {
+            const treeLines = walkBoundedTree(dir);
+            if (treeLines.length > 0) {
+                lines.push('## File tree', ...treeLines);
+            }
+        }
+        catch {
+            // Tree failure must never break the block — omit the section.
+        }
+        // ── Git state digest (read-only, 3s cap per command) ──
+        try {
+            const branchLine = git(dir, ['status', '--porcelain', '-b']).split('\n')[0] || '';
+            const statusLines = git(dir, ['status', '--porcelain']).split('\n').filter(Boolean);
+            const log = git(dir, ['log', '--oneline', '-5']).split('\n').filter(Boolean);
+            if (branchLine) {
+                lines.push('## Git state');
+                lines.push(`- ${branchLine}`);
+                if (statusLines.length > 0) {
+                    lines.push(`- ${statusLines.length} uncommitted change(s):`);
+                    for (const s of statusLines.slice(0, MAX_GIT_STATUS_LINES))
+                        lines.push(`  ${s}`);
+                    if (statusLines.length > MAX_GIT_STATUS_LINES) {
+                        lines.push(`  … ${statusLines.length - MAX_GIT_STATUS_LINES} more`);
+                    }
+                }
+                else {
+                    lines.push('- working tree clean');
+                }
+                if (log.length > 0) {
+                    lines.push('- recent commits:');
+                    for (const c of log)
+                        lines.push(`  ${c}`);
+                }
+            }
+            // Outside a git repo: no Git state section — fine.
+        }
+        catch {
+            // Git digest is best-effort — omit on failure.
+        }
+        const body = lines.join('\n');
+        if (body.length > MAX_BLOCK_CHARS) {
+            return body.slice(0, MAX_BLOCK_CHARS) + '\n[project context truncated to fit the context budget]';
+        }
+        return body;
+    }
+    catch {
+        return '';
+    }
+}
+//# sourceMappingURL=loop-project-context.js.map

package/dist/tools/loop-project-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop-project-context.js","sourceRoot":"","sources":["../../src/tools/loop-project-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC5D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE/C,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAE7D,kFAAkF;AAClF,MAAM,cAAc,GAAG,EAAE,CAAC;AAC1B,sFAAsF;AACtF,MAAM,cAAc,GAAG,CAAC,CAAC;AACzB,6EAA6E;AAC7E,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAC/B,qEAAqE;AACrE,MAAM,oBAAoB,GAAG,EAAE,CAAC;AAChC,iFAAiF;AACjF,MAAM,eAAe,GAAG,KAAK,CAAC;AAE9B,mFAAmF;AACnF,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC;IAC1B,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU;IACnE,QAAQ,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ;CAC9D,CAAC,CAAC;AAEH,6EAA6E;AAC7E,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,IAAI,CAAC;QACH,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE;YAAE,OAAO,KAAK,CAAC;QACnE,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;QACvC,yEAAyE;QACzE,iEAAiE;QACjE,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC;YACtB,cAAc,EAAE,eAAe,EAAE,gBAAgB,EAAE,UAAU,EAAE,kBAAkB;YACjF,YAAY,EAAE,QAAQ,EAAE,SAAS,EAAE,cAAc,EAAE,SAAS,EAAE,eAAe;YAC7E,MAAM,EAAE,UAAU,EAAE,gBAAgB,EAAE,cAAc,EAAE,SAAS,EAAE,iBAAiB;SACnF,CAAC,CAAC;QACH,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,6EAA6E;AAC7E,SAAS,GAAG,CAAC,GAAW,EAAE,IAAc;IACtC,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;QAClF,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM;YAAE,OAAO,EAAE,CAAC;QAC3C,OAAO,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,aAAa,GAAG,KAAK,CAAC;IAE1B,MAAM,IAAI,GAAG,CAAC,OAAe,EAAE,MAAc,EAAE,KAAa,EAAQ,EAAE;QACpE,IAAI,KAAK,GAAG,cAAc,IAAI,KAAK,CAAC,MAAM,IAAI,cAAc,EAAE,CAAC;YAC7D,IAAI,KAAK,CAAC,MAAM,IAAI,cAAc;gBAAE,aAAa,GAAG,IAAI,CAAC;YACzD,OAAO;QACT,CAAC;QAED,IAAI,OAAoB,CAAC;QACzB,IAAI,CAAC;YACH,OAAO,GAAG,WAAW,CAAC,OAAO,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC;iBACpD,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;iBAClE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;iBACtD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7F,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,CAAC,iCAAiC;QAC3C,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,GAAG,mBAAmB,EAAE,CAAC;YACzC,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,mBAAmB,CAAC,CAAC;YAChD,aAAa,GAAG,IAAI,CAAC;QACvB,CAAC;QACD,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE;YACzB,IAAI,KAAK,CAAC,MAAM,IAAI,cAAc,EAAE,CAAC;gBACnC,aAAa,GAAG,IAAI,CAAC;gBACrB,OAAO;YACT,CAAC;YACD,MAAM,IAAI,GAAG,GAAG,KAAK,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;YACxC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;YACnC,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAC5D,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC;gBACZ,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;YAC5E,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;IAEF,IAAI,CAAC,GAAG,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;IACjB,IAAI,aAAa;QAAE,KAAK,CAAC,IAAI,CAAC,8CAA8C,CAAC,CAAC;IAC9E,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAC,GAAW;IACvD,IAAI,CAAC;QACH,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC;YAAE,OAAO,EAAE,CAAC;QAEtC,MAAM,KAAK,GAAa,EAAE,CAAC;QAE3B,oEAAoE;QACpE,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;YAC7B,MAAM,IAAI,GAAa,EAAE,CAAC;YAC1B,IAAI,CAAC,CAAC,QAAQ;gBAAE,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;YACrD,IAAI,CAAC,CAAC,SAAS;gBAAE,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC;YACxD,IAAI,CAAC,CAAC,cAAc;gBAAE,IAAI,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC;YACxE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC;YACpE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC;YAC1D,IAAI,CAAC,CAAC,QAAQ,EAAE,MAAM;gBAAE,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACrF,KAAK,CAAC,IAAI,CAAC,YAAY,EAAE,WAAW,GAAG,EAAE,EAAE,KAAK,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACrE,CAAC;QAAC,MAAM,CAAC;YACP,KAAK,CAAC,IAAI,CAAC,YAAY,EAAE,WAAW,GAAG,EAAE,CAAC,CAAC;QAC7C,CAAC;QAED,0BAA0B;QAC1B,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;YACvC,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACzB,KAAK,CAAC,IAAI,CAAC,cAAc,EAAE,GAAG,SAAS,CAAC,CAAC;YAC3C,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,8DAA8D;QAChE,CAAC;QAED,yDAAyD;QACzD,IAAI,CAAC;YACH,MAAM,UAAU,GAAG,GAAG,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,aAAa,EAAE,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YAClF,MAAM,WAAW,GAAG,GAAG,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YACpF,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAC7E,IAAI,UAAU,EAAE,CAAC;gBACf,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;gBAC3B,KAAK,CAAC,IAAI,CAAC,KAAK,UAAU,EAAE,CAAC,CAAC;gBAC9B,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBAC3B,KAAK,CAAC,IAAI,CAAC,KAAK,WAAW,CAAC,MAAM,yBAAyB,CAAC,CAAC;oBAC7D,KAAK,MAAM,CAAC,IAAI,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,oBAAoB,CAAC;wBAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;oBACjF,IAAI,WAAW,CAAC,MAAM,GAAG,oBAAoB,EAAE,CAAC;wBAC9C,KAAK,CAAC,IAAI,CAAC,OAAO,WAAW,CAAC,MAAM,GAAG,oBAAoB,OAAO,CAAC,CAAC;oBACtE,CAAC;gBACH,CAAC;qBAAM,CAAC;oBACN,KAAK,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;gBACrC,CAAC;gBACD,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBACnB,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;oBAChC,KAAK,MAAM,CAAC,IAAI,GAAG;wBAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;gBAC5C,CAAC;YACH,CAAC;YACD,mDAAmD;QACrD,CAAC;QAAC,MAAM,CAAC;YACP,+CAA+C;QACjD,CAAC;QAED,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC9B,IAAI,IAAI,CAAC,MAAM,GAAG,eAAe,EAAE,CAAC;YAClC,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,eAAe,CAAC,GAAG,yDAAyD,CAAC;QACpG,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/tools/loop-skill-hint.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Loop skill hint (`src/tools/loop-skill-hint.ts`) — AGENTIC_CAPABILITY_ASSESSMENT
+ * Addendum v4 Phase 3.2: "The loop never hears about the orchestrator's skill
+ * layer: the pipeline consults SkillStore.findMatch + the hub catalog before
+ * planning and injects the matched methodology, but a chat/execute-loop goal
+ * starts with zero knowledge that a first-party playbook exists."
+ *
+ * This module closes that parity gap DETERMINISTICALLY (no LLM call): given
+ * the user's goal, it finds the best available skill the SAME way the
+ * orchestrator does —
+ *
+ *   1. compiled SkillStore.findMatch (the first-party capability batch),
+ *   2. the hub catalog (findHubSkillMatch — installed SKILL.md skills),
+ *
+ * then returns a system-prompt block that hands the model the skill's
+ * methodology with an EXPLICIT escape hatch ("this is a recommendation —
+ * ignore it when it does not fit") and the exact load syntax
+ * (`skill` tool, {"skill":"<name>"}).
+ *
+ * Why an evidence filter on top of findMatch: the compiled store's threshold
+ * is intentionally low (score >= 1, "manual discovery") and its scoring adds
+ * a quality/usage bonus to EVERY skill — so a goal merely containing a generic
+ * pattern word ("goal", "task") can false-positive. The chat loop runs on
+ * EVERY message (not just pipeline goals), so the loop hint requires REAL
+ * goal evidence: a name-word or tag hit, or two pattern-word hits. The
+ * orchestrator does not need this (its planner only sees pipeline goals); the
+ * hub catalog's own scoring is keyword-based and needs no filter.
+ *
+ * Safety rails (mirroring the orchestrator's injection contract):
+ *   - skills.disabled[] gate — a dashboard/CLI-disabled skill is NEVER
+ *     injected (the same "the toggle is never cosmetic" rule the match gates
+ *     enforce elsewhere).
+ *   - Website-deploy activation gate — the orchestrator requires
+ *     hosting-specific intent before injecting website methodology; the loop
+ *     hint applies the identical regex so "deploy the API" does not drag in
+ *     static-site deployment steps.
+ *   - Side-effect-free matching: the match itself marks nothing; usage is
+ *     marked ONCE via markLoopSkillUsed by the caller (skillView()'s internal
+ *     markUsed is deliberately avoided so the hint builder is idempotent).
+ *   - Bounded injection: at most ONE methodology block per prompt, and the
+ *     methodology text itself is capped (compiled: 8 steps; hub: 2000 chars)
+ *     so a crowded catalog cannot balloon the system prompt.
+ *   - Best-effort by construction: any store/catalog failure returns '' /
+ *     null and the turn proceeds exactly as before (a hint must never break
+ *     a turn).
+ *
+ * Consumers: chat's runChatAnswer (system prompt) and the execute loop's
+ * runLoopExecutor — the two runToolLoop callers that had no skill knowledge.
+ */
+import type { ConfigManager } from '../config/manager.js';
+/**
+ * The match the hint was built from (echoed to callers for telemetry/tests).
+ * `null` = no match (no skill scored, or it was gated out).
+ */
+export interface LoopSkillHintMatch {
+    name: string;
+    id: string;
+    source: 'compiled' | 'hub';
+}
+/**
+ * Did the goal show REAL evidence for this skill — a name-word hit, a tag
+ * hit, or two pattern-word hits (meta-words excluded)? Guards the compiled
+ * store's intentionally loose threshold: findMatch adds a quality/usage bonus
+ * to every skill, so a generic word like "goal" alone must never inject
+ * methodology into a chat turn. Deterministic, no LLM.
+ */
+export declare function hasRealGoalEvidence(goal: string, skill: {
+    name: string;
+    tags: string[];
+    goalPattern: string;
+}): boolean;
+/**
+ * Find the best skill for the goal across BOTH sources the orchestrator
+ * consults, honoring the disabled + website-deploy activation gates (+ the
+ * compiled evidence filter). Compiled wins ties (its id is the deterministic
+ * seed id). Returns null when nothing matches (never a forced match).
+ */
+export declare function findLoopSkillMatch(goal: string, cm?: ConfigManager): Promise<LoopSkillHintMatch | null>;
+/**
+ * Build the system-prompt block for a matched skill, or '' when there is no
+ * match. The block follows the orchestrator's injection contract:
+ *
+ *   - the skill is a RECOMMENDATION, the model still owns the plan (the
+ *     orchestrator's "model-selected activation" phrasing),
+ *   - the methodology rides in as Level-2 content (progressive disclosure —
+ *     the model sees the steps without paying a tool call for them),
+ *   - the exact load syntax is included so the model can refresh/parameterize
+ *     via the `skill` tool mid-turn,
+ *   - ONE block max (bounded system-prompt growth).
+ *
+ * Marks nothing: usage tracking belongs to markLoopSkillUsed (the caller
+ * decides when a match actually got USED — i.e. was injected).
+ *
+ * @param goal       the user's goal text (matched against skill triggers)
+ * @param cm         ConfigManager for the disabled-skills gate (optional)
+ * @param injected   out-param: when provided, receives the match that was
+ *                   injected (null when none).
+ */
+export declare function buildLoopSkillHint(goal: string, cm?: ConfigManager, injected?: {
+    value: LoopSkillHintMatch | null;
+}): Promise<string>;
+/**
+ * Mark an injected skill as used (usage tracking parity with the orchestrator
+ * — compiled skills only; hub skills have no compiled usage counter). The
+ * SINGLE usage marker for the loop hint path (the hint builder never marks).
+ * Best-effort, fire-and-forget: never throws, never awaited by callers on the
+ * hot path.
+ */
+export declare function markLoopSkillUsed(match: LoopSkillHintMatch | null): Promise<void>;
+//# sourceMappingURL=loop-skill-hint.d.ts.map

package/dist/tools/loop-skill-hint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop-skill-hint.d.ts","sourceRoot":"","sources":["../../src/tools/loop-skill-hint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAG1D;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,UAAU,GAAG,KAAK,CAAC;CAC5B;AA0CD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC3D,OAAO,CAsBT;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,EAAE,CAAC,EAAE,aAAa,GACjB,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAmCpC;AAmCD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,EAAE,CAAC,EAAE,aAAa,EAClB,QAAQ,CAAC,EAAE;IAAE,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAAA;CAAE,GAC9C,OAAO,CAAC,MAAM,CAAC,CAsCjB;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAQvF"}