clementine-agent 1.18.168 → 1.18.170

package/dist/agent/chat-skill-resolver.d.ts

@@ -0,0 +1,117 @@
+/**
+ * chat-skill-resolver — match a chat message against the skill catalog,
+ * extract the MCP servers / toolkits the matched skills imply, and
+ * produce a system-prompt block listing them as "Relevant Skills."
+ *
+ * Why this exists (1.18.170)
+ * ──────────────────────────
+ * Before this module, the modern chat path (`router.ts → runAgent`) did
+ * three things in order:
+ *   1. Build extra MCP servers from `routeToolSurface(userText)` — a
+ *      regex-bundle matcher over 19 fixed bundles in `tool-router.ts`.
+ *   2. Build vault context (SOUL.md / MEMORY.md / AGENTS.md).
+ *   3. Call runAgent with the assembled pieces.
+ *
+ * Step 1 has a fundamental gap: anything outside the 19 hardcoded
+ * bundles (Salesforce, HubSpot, Asana, ClickUp, Airtable, an installed
+ * CLI like `sf`) silently fails to route. The model gets no Salesforce
+ * tools loaded even when the user just connected the Salesforce MCP.
+ *
+ * Clementine already auto-generates one skill per MCP tool whenever a
+ * server's schema is fetched (`auto-skills.ts` → `~/.clementine/vault/
+ * 00-System/skills/auto/<server>/<tool>.md`). Those auto-skills include
+ * server-aware triggers ("salesforce", "my salesforce", "query records
+ * salesforce", …) and a `mcp__<server>__<tool>` reference in their body.
+ *
+ * The legacy chat path (`assistant.ts:1487-1538`) already searched the
+ * skill catalog and injected a "## Relevant Skill" block — but that
+ * code lives in the deprecated PersonalAssistant.query() path. The
+ * modern runAgent path skipped it entirely.
+ *
+ * This module ports + extends the legacy behavior:
+ *   • Top-3 match aggregation (not just top-1) — handles category queries
+ *     like "salesforce" where many tool-specific auto-skills match
+ *     similarly. The parent sees all 3 bodies and picks the right tool.
+ *   • Extracts `mcp__<server>__<tool>` references from every matched
+ *     skill's body. Used to widen `buildExtraMcpForRunAgent` so the
+ *     right Composio toolkits / claude.ai integrations load even though
+ *     "Salesforce" isn't in the regex-bundle list.
+ *   • Extracts `clementine.tools.allow` from user-authored skills (the
+ *     auto-skills don't set this field but human-authored ones often do).
+ *   • Auto-skills get a small penalty in `searchSkills` already (-0.5)
+ *     so user-authored skills outrank them at parity — preserved here.
+ *
+ * Not a sandbox: we never *restrict* tools based on matched skills (the
+ * SDK still receives the parent's full allowedTools). We only widen the
+ * MCP server selection. Hard tool-scope enforcement happens via the
+ * `runSkill` primitive (`run-skill.ts:300`), not chat.
+ *
+ * Failure mode: this module never throws. A match search that errors
+ * (corrupt skill file, missing dir, etc.) returns empty results and the
+ * caller proceeds with `routeToolSurface` alone — i.e. today's behavior.
+ */
+import { type SkillMatch } from './skill-extractor.js';
+import type { AgentProfile } from '../types.js';
+import type { MemoryStore } from '../memory/store.js';
+export interface ResolveSkillsOptions {
+    /** Active hired-agent profile, when set. Used for agent-scoped skill
+     *  priority (matches the legacy boost). */
+    profile?: AgentProfile | null;
+    /** Optional memory store — used to read the user's suppression list
+     *  ("never auto-match this skill again"). */
+    memoryStore?: MemoryStore | null;
+    /** Override the top-K aggregation cap. Defaults to 3. */
+    limit?: number;
+    /** Override the minimum match score. Defaults to 4. */
+    minScore?: number;
+}
+export interface ResolvedSkillContext {
+    /** Match records from searchSkills, filtered to those above minScore
+     *  and capped at `limit`. Length 0 means no skill matched — the
+     *  caller should fall back to today's behavior (regex bundles only). */
+    matches: SkillMatch[];
+    /** MCP server slugs referenced by any matched skill's body. Caller
+     *  unions this with `route.externalMcpServers` and `route.composioToolkits`. */
+    hintedMcpServers: string[];
+    /** Tools declared under `clementine.tools.allow` on matched skills.
+     *  Caller can use these to widen the SDK's `allowedTools` if the
+     *  matched skill expects access beyond the chat default. */
+    hintedTools: string[];
+    /** Pre-rendered "## Relevant Skills" markdown block, ready to append
+     *  to the system prompt. Empty when `matches.length === 0`. */
+    promptBlock: string;
+    /** Diagnostics for log/telemetry. */
+    diagnostics: {
+        queryChars: number;
+        candidatesConsidered: number;
+        matchesAboveThreshold: number;
+        topScore: number;
+        mcpRefsExtracted: number;
+    };
+}
+/** Extract the `mcp__<server>__<tool>` server-name component from a
+ *  match's body content + frontmatter. Returns the set of server slugs. */
+declare function extractMcpServersFromMatch(match: SkillMatch): string[];
+/** Extract `clementine.tools.allow` from a match's frontmatter.
+ *  Returns the list of declared tool names (or [] if none). */
+declare function extractAllowedToolsFromMatch(match: SkillMatch): string[];
+/**
+ * Render the system-prompt block injected for the matched skills.
+ * Single-match keeps the legacy `## Relevant Skill: <title>` shape;
+ * multi-match nests them under `## Relevant Skills` with per-skill
+ * subheadings. Tools-required warnings (legacy `assistant.ts:1504-1513`)
+ * are NOT included here — they belong to the run-time tool policy
+ * check, not the prompt context.
+ */
+declare function renderPromptBlock(matches: SkillMatch[]): string;
+/**
+ * Match a user message against the skill catalog and return the routing
+ * hints + prompt block the chat path should layer on top of the static
+ * `routeToolSurface` decision.
+ *
+ * Never throws — telemetry / matching errors degrade gracefully to
+ * empty hints, and the caller proceeds with today's behavior.
+ */
+export declare function resolveSkillsForChat(userMessage: string, opts?: ResolveSkillsOptions): ResolvedSkillContext;
+export { extractMcpServersFromMatch, extractAllowedToolsFromMatch, renderPromptBlock };
+//# sourceMappingURL=chat-skill-resolver.d.ts.map

package/dist/agent/chat-skill-resolver.js

@@ -0,0 +1,282 @@
+/**
+ * chat-skill-resolver — match a chat message against the skill catalog,
+ * extract the MCP servers / toolkits the matched skills imply, and
+ * produce a system-prompt block listing them as "Relevant Skills."
+ *
+ * Why this exists (1.18.170)
+ * ──────────────────────────
+ * Before this module, the modern chat path (`router.ts → runAgent`) did
+ * three things in order:
+ *   1. Build extra MCP servers from `routeToolSurface(userText)` — a
+ *      regex-bundle matcher over 19 fixed bundles in `tool-router.ts`.
+ *   2. Build vault context (SOUL.md / MEMORY.md / AGENTS.md).
+ *   3. Call runAgent with the assembled pieces.
+ *
+ * Step 1 has a fundamental gap: anything outside the 19 hardcoded
+ * bundles (Salesforce, HubSpot, Asana, ClickUp, Airtable, an installed
+ * CLI like `sf`) silently fails to route. The model gets no Salesforce
+ * tools loaded even when the user just connected the Salesforce MCP.
+ *
+ * Clementine already auto-generates one skill per MCP tool whenever a
+ * server's schema is fetched (`auto-skills.ts` → `~/.clementine/vault/
+ * 00-System/skills/auto/<server>/<tool>.md`). Those auto-skills include
+ * server-aware triggers ("salesforce", "my salesforce", "query records
+ * salesforce", …) and a `mcp__<server>__<tool>` reference in their body.
+ *
+ * The legacy chat path (`assistant.ts:1487-1538`) already searched the
+ * skill catalog and injected a "## Relevant Skill" block — but that
+ * code lives in the deprecated PersonalAssistant.query() path. The
+ * modern runAgent path skipped it entirely.
+ *
+ * This module ports + extends the legacy behavior:
+ *   • Top-3 match aggregation (not just top-1) — handles category queries
+ *     like "salesforce" where many tool-specific auto-skills match
+ *     similarly. The parent sees all 3 bodies and picks the right tool.
+ *   • Extracts `mcp__<server>__<tool>` references from every matched
+ *     skill's body. Used to widen `buildExtraMcpForRunAgent` so the
+ *     right Composio toolkits / claude.ai integrations load even though
+ *     "Salesforce" isn't in the regex-bundle list.
+ *   • Extracts `clementine.tools.allow` from user-authored skills (the
+ *     auto-skills don't set this field but human-authored ones often do).
+ *   • Auto-skills get a small penalty in `searchSkills` already (-0.5)
+ *     so user-authored skills outrank them at parity — preserved here.
+ *
+ * Not a sandbox: we never *restrict* tools based on matched skills (the
+ * SDK still receives the parent's full allowedTools). We only widen the
+ * MCP server selection. Hard tool-scope enforcement happens via the
+ * `runSkill` primitive (`run-skill.ts:300`), not chat.
+ *
+ * Failure mode: this module never throws. A match search that errors
+ * (corrupt skill file, missing dir, etc.) returns empty results and the
+ * caller proceeds with `routeToolSurface` alone — i.e. today's behavior.
+ */
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { existsSync } from 'node:fs';
+import matter from 'gray-matter';
+import pino from 'pino';
+import { searchSkills } from './skill-extractor.js';
+const logger = pino({ name: 'clementine.chat-skill-resolver' });
+// ── Tunables ──────────────────────────────────────────────────────────
+/** Default minimum score to consider a skill match real. Mirrors the
+ *  legacy `assistant.ts:1492` threshold. Skill auto-match is heuristic;
+ *  this filter keeps weak matches from injecting unrelated tooling. */
+const DEFAULT_MIN_SCORE = 4;
+/** Default top-K matches to aggregate. Single-tool requests usually
+ *  return one strong match; category requests ("salesforce") return
+ *  several similarly-scored auto-skills. Top-3 covers both. Raising
+ *  this bloats the system prompt without much routing benefit. */
+const DEFAULT_TOP_K = 3;
+/** Cap per-skill body excerpt in the injected prompt. The full body is
+ *  often a multi-KB args table for an MCP tool — fine if the user
+ *  needs to look at it, wasteful for routing context. Mirrors
+ *  `assistant.ts:1501` which sliced at 800 chars. */
+const PER_SKILL_BODY_CHARS = 1000;
+/** Same MCP_TOOL_REF pattern used in `run-skill.ts:153` / `tool-router.ts:172`.
+ *  Matches `mcp__<server>__<tool>` references inside skill body text. */
+const MCP_TOOL_REF = /mcp__([A-Za-z0-9-]+(?:_[A-Za-z0-9-]+)*)__[A-Za-z0-9_-]+/g;
+// ── Skill discovery support ──────────────────────────────────────────
+/**
+ * Find a matched skill's frontmatter on disk. `SkillMatch` carries
+ * `name` + `skillDir` but not the full frontmatter — and we need
+ * `clementine.tools.allow` + the explicit `tool:` field from auto-skills.
+ *
+ * Walks `<skillDir>` looking for any file whose basename or folder
+ * matches `name`. Returns null on any failure; the caller already has
+ * the matched body content from searchSkills and that's enough for
+ * MCP-ref extraction. The frontmatter read here is opportunistic.
+ */
+function readMatchFrontmatter(match) {
+    // The match's `skillDir` is the SEARCH root. Auto-skills live nested
+    // under `<skillDir>/auto/<server>/<tool>.md`; user skills can be flat
+    // (`<skillDir>/<slug>.md`) or folder-form (`<skillDir>/<slug>/SKILL.md`).
+    const slug = match.name;
+    const candidates = [
+        join(match.skillDir, `${slug}.md`),
+        join(match.skillDir, slug, 'SKILL.md'),
+    ];
+    // For auto-skill slugs like `auto-dataforseo-…`, also try the nested
+    // path that the slug encodes. This is a best-effort lookup; on miss
+    // we just skip frontmatter and use the body alone.
+    if (slug.startsWith('auto-')) {
+        const parts = slug.slice(5).split('-');
+        if (parts.length >= 2) {
+            const server = parts[0];
+            const rest = parts.slice(1).join('-');
+            candidates.push(join(match.skillDir, 'auto', server, `${rest}.md`));
+        }
+    }
+    for (const p of candidates) {
+        try {
+            if (!existsSync(p))
+                continue;
+            const raw = readFileSync(p, 'utf-8');
+            const parsed = matter(raw);
+            return parsed.data;
+        }
+        catch {
+            // try next candidate
+        }
+    }
+    return null;
+}
+/** Extract the `mcp__<server>__<tool>` server-name component from a
+ *  match's body content + frontmatter. Returns the set of server slugs. */
+function extractMcpServersFromMatch(match) {
+    const servers = new Set();
+    // From body text — works for auto-skills (which list the tool name
+    // in their "## Tool call" section) and user skills that paste tool
+    // refs into their instructions.
+    MCP_TOOL_REF.lastIndex = 0;
+    let m;
+    while ((m = MCP_TOOL_REF.exec(match.content)) !== null) {
+        servers.add(m[1]);
+    }
+    // From frontmatter — auto-skills have `tool: mcp__<server>__<name>` AND
+    // `server: <name>` set explicitly. Either is authoritative.
+    const fm = readMatchFrontmatter(match);
+    if (fm) {
+        if (typeof fm.server === 'string' && fm.server.trim()) {
+            servers.add(fm.server.trim());
+        }
+        if (typeof fm.tool === 'string') {
+            const mm = MCP_TOOL_REF.exec(fm.tool);
+            if (mm)
+                servers.add(mm[1]);
+            MCP_TOOL_REF.lastIndex = 0;
+        }
+    }
+    return [...servers];
+}
+/** Extract `clementine.tools.allow` from a match's frontmatter.
+ *  Returns the list of declared tool names (or [] if none). */
+function extractAllowedToolsFromMatch(match) {
+    const fm = readMatchFrontmatter(match);
+    if (!fm)
+        return [];
+    const clementine = fm.clementine;
+    const allow = clementine?.tools?.allow;
+    if (!Array.isArray(allow))
+        return [];
+    return allow.filter((t) => typeof t === 'string' && t.length > 0);
+}
+// ── Prompt rendering ──────────────────────────────────────────────────
+/**
+ * Render the system-prompt block injected for the matched skills.
+ * Single-match keeps the legacy `## Relevant Skill: <title>` shape;
+ * multi-match nests them under `## Relevant Skills` with per-skill
+ * subheadings. Tools-required warnings (legacy `assistant.ts:1504-1513`)
+ * are NOT included here — they belong to the run-time tool policy
+ * check, not the prompt context.
+ */
+function renderPromptBlock(matches) {
+    if (matches.length === 0)
+        return '';
+    if (matches.length === 1) {
+        const s = matches[0];
+        return `## Relevant Skill: ${s.title}\n\n${s.content.slice(0, PER_SKILL_BODY_CHARS)}`;
+    }
+    const parts = ['## Relevant Skills', ''];
+    parts.push(`Top ${matches.length} skill matches for this request, ordered by relevance. ` +
+        `Use these as a guide for which tools to call. If multiple skills suggest the same MCP server, ` +
+        `prefer the highest-scored one's procedure.\n`);
+    for (let i = 0; i < matches.length; i++) {
+        const s = matches[i];
+        parts.push(`### ${i + 1}. ${s.title}`, '');
+        parts.push(s.content.slice(0, PER_SKILL_BODY_CHARS));
+        parts.push('');
+    }
+    return parts.join('\n');
+}
+// ── Public entry point ────────────────────────────────────────────────
+/**
+ * Match a user message against the skill catalog and return the routing
+ * hints + prompt block the chat path should layer on top of the static
+ * `routeToolSurface` decision.
+ *
+ * Never throws — telemetry / matching errors degrade gracefully to
+ * empty hints, and the caller proceeds with today's behavior.
+ */
+export function resolveSkillsForChat(userMessage, opts = {}) {
+    const queryChars = userMessage.length;
+    const empty = {
+        matches: [],
+        hintedMcpServers: [],
+        hintedTools: [],
+        promptBlock: '',
+        diagnostics: {
+            queryChars,
+            candidatesConsidered: 0,
+            matchesAboveThreshold: 0,
+            topScore: 0,
+            mcpRefsExtracted: 0,
+        },
+    };
+    if (!userMessage || !userMessage.trim())
+        return empty;
+    const limit = Math.max(1, opts.limit ?? DEFAULT_TOP_K);
+    const minScore = opts.minScore ?? DEFAULT_MIN_SCORE;
+    const suppressedNames = opts.memoryStore?.getSkillsToSuppress?.(opts.profile?.slug);
+    let candidates = [];
+    try {
+        candidates = searchSkills(userMessage, 
+        // Ask for a bit more than `limit` so we can filter by minScore and
+        // still hit the cap when the distribution has a tail of weak hits.
+        Math.max(limit + 2, 5), opts.profile?.slug, { ...(suppressedNames ? { suppressedNames } : {}) });
+    }
+    catch (err) {
+        logger.debug({ err }, 'chat-skill-resolver: searchSkills failed (non-fatal)');
+        return empty;
+    }
+    const matches = candidates
+        .filter((m) => m.score >= minScore)
+        .slice(0, limit);
+    if (matches.length === 0) {
+        return {
+            ...empty,
+            diagnostics: {
+                queryChars,
+                candidatesConsidered: candidates.length,
+                matchesAboveThreshold: 0,
+                topScore: candidates[0]?.score ?? 0,
+                mcpRefsExtracted: 0,
+            },
+        };
+    }
+    const mcpServerSet = new Set();
+    const toolSet = new Set();
+    for (const m of matches) {
+        for (const s of extractMcpServersFromMatch(m))
+            mcpServerSet.add(s);
+        for (const t of extractAllowedToolsFromMatch(m))
+            toolSet.add(t);
+    }
+    const result = {
+        matches,
+        hintedMcpServers: [...mcpServerSet],
+        hintedTools: [...toolSet],
+        promptBlock: renderPromptBlock(matches),
+        diagnostics: {
+            queryChars,
+            candidatesConsidered: candidates.length,
+            matchesAboveThreshold: matches.length,
+            topScore: matches[0].score,
+            mcpRefsExtracted: mcpServerSet.size,
+        },
+    };
+    logger.info({
+        matches: matches.map(m => ({ name: m.name, score: Number(m.score.toFixed(2)) })),
+        hintedMcpServers: result.hintedMcpServers,
+        hintedToolCount: result.hintedTools.length,
+        queryChars,
+    }, 'chat-skill-resolver: skills matched');
+    return result;
+}
+// Re-export the helpers so tests can target them directly.
+export { extractMcpServersFromMatch, extractAllowedToolsFromMatch, renderPromptBlock };
+// Silence lint for the dirname import — kept for future use when the
+// matcher needs the parent folder of a matched skill (e.g. to surface
+// bundled attachments in the prompt). Removing the import would be a
+// pre-emptive cleanup but the file is already tagged for follow-up work.
+void dirname;
+//# sourceMappingURL=chat-skill-resolver.js.map

package/dist/agent/run-agent-mcp.d.ts

@@ -24,6 +24,19 @@ export interface BuildExtraMcpOptions {
     /** When true, build the FULL surface (no bundle filtering, no dedup).
      *  Used by admin/debug callers; not the cron-path default. */
     fullSurface?: boolean;
+    /**
+     * Additional MCP server slugs that should be considered "in scope" beyond
+     * what `routeToolSurface(scopeText)` produced. The chat path (1.18.170)
+     * derives these from `mcp__<server>__<tool>` references on auto-matched
+     * skills — see `chat-skill-resolver.ts`. The same slug is tried as both a
+     * Composio toolkit and an external MCP server name, mirroring the
+     * `explicit_mcp` handling in `tool-router.ts:223-234` so whichever source
+     * is actually connected mounts and the other no-ops.
+     *
+     * Profile-level allowlists still WIN over these hints — a hint cannot
+     * loosen a profile-restricted agent's tool surface.
+     */
+    skillHintedMcpServers?: string[];
 }
 export interface BuildExtraMcpResult {
     /** Map of additional MCP servers to merge into runAgent's mcpServers. */

package/dist/agent/run-agent-mcp.js

@@ -44,6 +44,36 @@ export async function buildExtraMcpForRunAgent(opts = {}) {
             reason: 'full_surface',
         }
         : routeToolSurface(opts.scopeText ?? '');
+    // 1b. Widen with skill-hinted MCP servers (1.18.170). Each hint slug is
+    //     tried as both an external MCP server name and a Composio toolkit;
+    //     unmatched/disconnected ones no-op below at server-construction time.
+    //     We don't touch `route` when `fullSurface` is set — nothing to widen.
+    if (!opts.fullSurface && opts.skillHintedMcpServers && opts.skillHintedMcpServers.length > 0) {
+        const ext = new Set(Array.isArray(route.externalMcpServers) ? route.externalMcpServers : []);
+        const com = new Set(Array.isArray(route.composioToolkits) ? route.composioToolkits : []);
+        for (const slug of opts.skillHintedMcpServers) {
+            const trimmed = slug.trim();
+            if (!trimmed)
+                continue;
+            if (trimmed.startsWith('claude_ai_')) {
+                ext.add(trimmed.slice('claude_ai_'.length));
+            }
+            else {
+                ext.add(trimmed);
+                com.add(trimmed);
+            }
+        }
+        // Keep the existing reason union ('empty' | 'matched' | 'full_surface').
+        // The widening just lifts an 'empty' route into 'matched' once we've
+        // added any skill-derived server. Diagnostics about skill_hint
+        // contribution flow via the caller's log line.
+        route = {
+            ...route,
+            externalMcpServers: [...ext],
+            composioToolkits: [...com],
+            reason: ext.size > 0 || com.size > 0 ? 'matched' : route.reason,
+        };
+    }
     // 2. Build Composio MCP servers, honoring profile allowlist when set.
     let composioMcpServers = {};
     try {

package/dist/agent/run-agent.d.ts

@@ -111,7 +111,7 @@ export interface RunAgentOptions {
      *  team-task) keep the prompt small. When unset, falls back to
      *  profile.systemPromptBody (legacy single-source behavior). */
     systemPromptAppend?: string;
-    /** Per-run override for the tool-output-guard config (1.18.168).
+    /** Per-run override for the tool-output-guard config (1.18.169).
      *  Defaults come from src/config.ts TOOL_OUTPUT_GUARD (env +
      *  clementine.json). Pass null to disable the guard for this run
      *  (rarely needed — almost always a sign that perTool overrides

package/dist/agent/run-agent.js

@@ -279,7 +279,7 @@ export async function runAgent(prompt, opts) {
         }
     }
     // PRD §6 / 1.18.85: stable run id created before sdkOptions so the
-    // tool-output guard (1.18.168) can namespace its on-disk archive by
+    // tool-output guard (1.18.169) can namespace its on-disk archive by
     // runId. EventLog writers below also reference this id.
     const runId = randomUUID();
     const eventLog = new EventLog();
@@ -294,7 +294,7 @@ export async function runAgent(prompt, opts) {
         }
         catch { /* never block */ }
     };
-    // ── Tool-output guard hooks (1.18.168) ─────────────────────────────
+    // ── Tool-output guard hooks (1.18.169) ─────────────────────────────
     // Bounds the per-tool-call output that reaches the model so SDK
     // auto-compaction never thrashes on a runaway MCP result. The hook
     // ALSO mirrors compression events into the run's EventLog so the Run
@@ -380,7 +380,7 @@ export async function runAgent(prompt, opts) {
         ...(opts.additionalDirectories && opts.additionalDirectories.length > 0
             ? { additionalDirectories: opts.additionalDirectories }
             : {}),
-        // 1.18.168 — install the tool-output guard hooks. SDK types accept
+        // 1.18.169 — install the tool-output guard hooks. SDK types accept
         // `hooks` keyed by HookEvent; the empty object is a no-op when the
         // guard is disabled.
         ...(Object.keys(guard.hooks).length > 0 ? { hooks: guard.hooks } : {}),
@@ -443,7 +443,7 @@ export async function runAgent(prompt, opts) {
             }
             if (message.type === 'assistant') {
                 const am = message;
-                // 1.18.168 — capture this turn's usage so the tool-output guard can
+                // 1.18.169 — capture this turn's usage so the tool-output guard can
                 // adaptively tighten its cap as cumulative context climbs. We sum
                 // input + cache_read + cache_creation because all three count
                 // against the model's window for the NEXT turn. Output_tokens isn't
@@ -631,7 +631,7 @@ export async function runAgent(prompt, opts) {
         totalCostUsd: Number(totalCostUsd.toFixed(4)),
         durationMs: Date.now() - startedAt,
         finalTextChars: finalText.length,
-        // 1.18.168 — tool-output guard summary, surfaced for observability.
+        // 1.18.169 — tool-output guard summary, surfaced for observability.
         // Non-zero `compressed` means the guard kept the SDK from thrashing.
         guard: guard.stats.inspected > 0 ? {
             inspected: guard.stats.inspected,

package/dist/agent/tool-output-guard.d.ts

@@ -141,6 +141,8 @@ export interface GuardHookOptions {
      *  guard calls this once per tool result to adapt the cap. When
      *  absent, ratio is assumed 0 (full soft cap is always used). */
     usageRatio?: () => number;
+    /** Optional archive root override for tests. Defaults to Clementine home. */
+    archiveBaseDir?: string;
 }
 export interface GuardHookHandles {
     /** Hook map suitable for SDK `query({ options: { hooks } })`. */

package/dist/agent/tool-output-guard.js

@@ -184,9 +184,9 @@ function formatBytes(n) {
 /** Persist the full payload so the agent can `Read` it later if needed.
  *  Returns the absolute path, or null on any failure (archive is opt-in
  *  convenience — never blocks compression). */
-function archivePayload(runId, toolUseId, toolName, payload) {
+function archivePayload(baseDir, runId, toolUseId, toolName, payload) {
     try {
-        const dir = join(BASE_DIR, 'tool-archive', runId);
+        const dir = join(baseDir, 'tool-archive', runId);
         mkdirSync(dir, { recursive: true });
         const safeName = toolName.replace(/[^a-zA-Z0-9_-]+/g, '_').slice(0, 80);
         const file = join(dir, `${safeName}__${toolUseId}.json`);
@@ -304,7 +304,7 @@ export function buildGuardHooks(opts) {
         // a real file. We don't fail compression if archive fails — the
         // payload just becomes irretrievable; the model still gets a
         // truncation marker and can re-call the tool.
-        const archivePath = archivePayload(opts.runId, toolUseId, toolName, rawOutput);
+        const archivePath = archivePayload(opts.archiveBaseDir ?? BASE_DIR, opts.runId, toolUseId, toolName, rawOutput);
         const outcome = compressToolOutput(toolName, rawOutput, {
             toolName,
             toolUseId,

package/dist/config/clementine-json.js

@@ -68,7 +68,7 @@ export const clementineJsonSchema = z.object({
         chat: z.number().nonnegative().optional(),
     }).optional(),
     /**
-     * Tool-output context-protection caps (1.18.168).
+     * Tool-output context-protection caps (1.18.169).
      *
      * Every SDK `tool_result` larger than the limit gets compressed in a
      * PostToolUse hook before the model sees it. The full result is archived

package/dist/config.js

@@ -428,7 +428,7 @@ export const TASK_BUDGET_TOKENS = {
     // Interactive chat: off by default — let the user and maxTurns drive it.
     chat: optionalTokenEnv('TASK_BUDGET_CHAT', undefined),
 };
-// ── Tool-output context guard (1.18.168) ─────────────────────────────
+// ── Tool-output context guard (1.18.169) ─────────────────────────────
 // Caps the per-tool-call size that reaches the model's context window.
 // Implements Anthropic's recommended PostToolUse hook pattern to prevent
 // runaway MCP-tool outputs (Outlook inbox dumps, iMessage history,

package/dist/gateway/router.js

@@ -1796,6 +1796,7 @@ export class Gateway {
                     const { runAgent } = await import('../agent/run-agent.js');
                     const { buildExtraMcpForRunAgent } = await import('../agent/run-agent-mcp.js');
                     const { buildChatSystemAppend } = await import('../agent/run-agent-context.js');
+                    const { resolveSkillsForChat } = await import('../agent/chat-skill-resolver.js');
                     // Builder sessions (dashboard trick/skill/cron/agent builder)
                     // are conversational JSON-drafting flows, not real chat. They
                     // don't need vault context, MCP tools, recall, or auto-memory
@@ -1804,6 +1805,23 @@ export class Gateway {
                     // expensive; keep just SDK session resume so multi-turn
                     // artifact iteration sees its own prior turns.
                     const isBuilderSession = sessionKey.startsWith('dashboard:builder:');
+                    // ── Skill auto-match (1.18.170) ─────────────────────────────
+                    // Match the user's message against the skill catalog (auto-
+                    // skills + user-authored). Top-3 matches above score ≥ 4 inform:
+                    //   (a) MCP routing — every matched skill's `mcp__<server>__<tool>`
+                    //       references widen `buildExtraMcpForRunAgent`'s server set
+                    //       beyond the 19 regex bundles. Closes the "Salesforce
+                    //       connected but no bundle exists" gap end-to-end.
+                    //   (b) System prompt — matched skill bodies are appended as a
+                    //       "## Relevant Skills" block so the model knows the canonical
+                    //       procedure + arg names.
+                    // Builder sessions skip this — they don't call tools.
+                    const resolvedSkills = isBuilderSession
+                        ? null
+                        : resolveSkillsForChat(originalText, {
+                            profile: resolvedProfile,
+                            memoryStore: this.assistant.getMemoryStore?.() ?? null,
+                        });
                     // Wire Composio + external MCP only for real chat. Builder
                     // skips entirely — builder turns never call tools.
                     const chatMcp = isBuilderSession
@@ -1811,16 +1829,26 @@ export class Gateway {
                         : await buildExtraMcpForRunAgent({
                             scopeText: originalText,
                             profile: resolvedProfile,
+                            ...(resolvedSkills && resolvedSkills.hintedMcpServers.length > 0
+                                ? { skillHintedMcpServers: resolvedSkills.hintedMcpServers }
+                                : {}),
                         });
                     // Vault context (SOUL.md / MEMORY.md / AGENTS.md + optional
                     // profile body) — real chat only. Builder gets just its own
                     // prefix as the system prompt.
-                    const chatSystemAppend = isBuilderSession
+                    const baseSystemAppend = isBuilderSession
                         ? ''
                         : buildChatSystemAppend({
                             profile: resolvedProfile,
                             profileAppend: resolvedProfile?.systemPromptBody,
                         });
+                    // Append the matched-skill block AFTER the vault context so the
+                    // skill instructions are the last (most recent) frame the model
+                    // sees in the system prompt — a small recency boost without
+                    // disturbing personality / memory ordering.
+                    const chatSystemAppend = resolvedSkills && resolvedSkills.promptBlock
+                        ? (baseSystemAppend ? `${baseSystemAppend}\n\n${resolvedSkills.promptBlock}` : resolvedSkills.promptBlock)
+                        : baseSystemAppend;
                     // Per-turn context (recall + persistent learnings + silent
                     // blocks + security/toolset directives) — real chat only.
                     // Builder doesn't need recall of unrelated transcripts.
@@ -1854,6 +1882,11 @@ export class Gateway {
                         turnContextChars: turnContextPrefix.length,
                         resumingSdkSessionId: priorSdkSessionId || null,
                         isBuilderSession,
+                        // 1.18.170 — surface skill matches so the dashboard's Run
+                        // detail page can render which skills informed routing.
+                        skillMatches: resolvedSkills?.matches.length ?? 0,
+                        skillMatchNames: resolvedSkills?.matches.map(m => m.name) ?? [],
+                        skillHintedMcpServers: resolvedSkills?.hintedMcpServers ?? [],
                     }, 'Routing chat through runAgent');
                     const runAgentResult = await runAgent(finalPrompt, {
                         sessionKey: effectiveSessionKey,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clementine-agent",
-  "version": "1.18.168",
+  "version": "1.18.170",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",