clementine-agent 1.18.124 → 1.18.125

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

@@ -43,6 +43,42 @@ export declare function computeEffectiveAllowedTools(jobAllow: string[] | undefi
  * MCP allowlist set.
  */
 export declare function applyMcpAllowlist<T>(servers: Record<string, T>, jobAllowedMcpServers: string[] | undefined): Record<string, T>;
+/**
+ * Widen the cron's tool allowlist with the union of pinned-skill
+ * `clementine.tools.allow` declarations.
+ *
+ * **Why this exists:** Pinning a skill is a positive user signal — "I want
+ * this skill, with the tools it declares it needs." Before 1.18.125 the
+ * skill's `tools.allow` was rendered into the prompt as text only; the SDK
+ * never saw it, so a skill pinned to a cron with a narrower allowlist would
+ * silently fail with tool-not-found errors.
+ *
+ * **Semantics:**
+ *   - Cron has no allowlist → return undefined (cron is unrestricted; pinned
+ *     skill tools flow through the profile/default fallback in `runAgent`).
+ *     We deliberately don't synthesize an allowlist out of just skill tools
+ *     here, because that would NARROW an unrestricted cron to "only what the
+ *     skills declared."
+ *   - Cron has allowlist + skills declared tools → return the union (skills
+ *     widen, never narrow, an existing constraint).
+ *   - Cron has allowlist + no pinned-skill tools → return the cron's allowlist
+ *     unchanged.
+ */
+export declare function widenAllowlistWithSkillTools(jobAllow: string[] | undefined, pinnedSkillTools: string[] | undefined): string[] | undefined;
+/**
+ * Extract every distinct `mcp__<server>__<tool>` server name referenced
+ * inside the bodies of pinned skills. Empty array when no references found.
+ */
+export declare function extractMcpServersFromSkillBodies(bodies: string[]): string[];
+/**
+ * Widen the cron's MCP-server allowlist with servers referenced inside
+ * pinned-skill bodies (e.g., a skill that calls `mcp__gmail__send_message`
+ * implicitly needs the `gmail` server connected).
+ *
+ * Same semantics as `widenAllowlistWithSkillTools`: only widens an existing
+ * allowlist; doesn't synthesize one when the cron is unrestricted.
+ */
+export declare function widenMcpAllowlistWithSkillRefs(jobMcpAllow: string[] | undefined, skillReferencedServers: string[]): string[] | undefined;
 export interface SkillContextResult {
     /** The rendered "Learned Procedures" block (or empty string when no skills loaded). */
     text: string;
@@ -54,6 +90,16 @@ export interface SkillContextResult {
     }>;
     /** Pinned slugs that didn't resolve (deleted/renamed/suppressed). Logged + surfaced. */
     missing: string[];
+    /** Union of every `clementine.tools.allow` entry from pinned skills. Used by
+     *  `buildCronExecutionPlan` to widen the cron's tool allowlist so a pinned
+     *  skill's declared tools survive into the SDK call. Empty array when no
+     *  pinned skill declared a `tools.allow` list. Auto-matched skills do NOT
+     *  contribute — only explicit pins widen scope. */
+    pinnedToolsRequested: string[];
+    /** Bodies of pinned skills only — used for `mcp__server__tool` reference
+     *  extraction so a skill's MCP usage propagates to `allowedMcpServers`.
+     *  Auto-matched skills excluded for the same reason as above. */
+    pinnedBodies: string[];
 }
 /**
  * Build the matched-skills block (procedures learned from prior successful runs).
@@ -196,6 +242,18 @@ export interface CronExecutionPlan {
      *  being set inside the skill folder. Deduped + filtered to existing
      *  paths. Empty when the trick has no addDirs and no folder-form pins. */
     additionalDirectories: string[];
+    /** Diagnostics: which scopes a pinned skill widened on this run. Empty
+     *  arrays when no widening happened. Surfaced in the Preview UI so users
+     *  see "this skill brought in `Bash` and `gmail` MCP" without reading
+     *  source. */
+    widenedFromSkills: {
+        /** Tool names a pinned skill's `clementine.tools.allow` added on top of
+         *  the cron's own allowlist. Empty when nothing was widened. */
+        tools: string[];
+        /** MCP server names a pinned skill's body referenced (`mcp__server__tool`)
+         *  that the cron's `allowedMcpServers` didn't already include. */
+        mcpServers: string[];
+    };
 }
 /**
  * Plan a cron run — assemble all context, resolve skills, intersect tool/MCP

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

@@ -72,6 +72,70 @@ export function applyMcpAllowlist(servers, jobAllowedMcpServers) {
     const allow = new Set(jobAllowedMcpServers);
     return Object.fromEntries(Object.entries(servers).filter(([name]) => allow.has(name)));
 }
+/**
+ * Widen the cron's tool allowlist with the union of pinned-skill
+ * `clementine.tools.allow` declarations.
+ *
+ * **Why this exists:** Pinning a skill is a positive user signal — "I want
+ * this skill, with the tools it declares it needs." Before 1.18.125 the
+ * skill's `tools.allow` was rendered into the prompt as text only; the SDK
+ * never saw it, so a skill pinned to a cron with a narrower allowlist would
+ * silently fail with tool-not-found errors.
+ *
+ * **Semantics:**
+ *   - Cron has no allowlist → return undefined (cron is unrestricted; pinned
+ *     skill tools flow through the profile/default fallback in `runAgent`).
+ *     We deliberately don't synthesize an allowlist out of just skill tools
+ *     here, because that would NARROW an unrestricted cron to "only what the
+ *     skills declared."
+ *   - Cron has allowlist + skills declared tools → return the union (skills
+ *     widen, never narrow, an existing constraint).
+ *   - Cron has allowlist + no pinned-skill tools → return the cron's allowlist
+ *     unchanged.
+ */
+export function widenAllowlistWithSkillTools(jobAllow, pinnedSkillTools) {
+    if (!jobAllow?.length)
+        return undefined;
+    if (!pinnedSkillTools?.length)
+        return [...jobAllow];
+    return [...new Set([...jobAllow, ...pinnedSkillTools])];
+}
+/** Match `mcp__SERVER__TOOL` references in skill body Markdown.
+ *  Server names can contain single underscores (`Bright_Data`,
+ *  `claude_ai_Microsoft_365`) but never `__` (double-underscore is the
+ *  delimiter). The regex captures the server segment between the leading
+ *  `mcp__` and the next `__`. Anchored on word boundaries so it doesn't
+ *  catch substrings of longer identifiers. */
+const MCP_TOOL_REF = /mcp__([A-Za-z0-9-]+(?:_[A-Za-z0-9-]+)*)__/g;
+/**
+ * Extract every distinct `mcp__<server>__<tool>` server name referenced
+ * inside the bodies of pinned skills. Empty array when no references found.
+ */
+export function extractMcpServersFromSkillBodies(bodies) {
+    const found = new Set();
+    for (const body of bodies) {
+        if (!body)
+            continue;
+        for (const m of body.matchAll(MCP_TOOL_REF))
+            found.add(m[1]);
+    }
+    return [...found];
+}
+/**
+ * Widen the cron's MCP-server allowlist with servers referenced inside
+ * pinned-skill bodies (e.g., a skill that calls `mcp__gmail__send_message`
+ * implicitly needs the `gmail` server connected).
+ *
+ * Same semantics as `widenAllowlistWithSkillTools`: only widens an existing
+ * allowlist; doesn't synthesize one when the cron is unrestricted.
+ */
+export function widenMcpAllowlistWithSkillRefs(jobMcpAllow, skillReferencedServers) {
+    if (!jobMcpAllow?.length)
+        return undefined;
+    if (!skillReferencedServers.length)
+        return [...jobMcpAllow];
+    return [...new Set([...jobMcpAllow, ...skillReferencedServers])];
+}
 function capContextItem(s) {
     if (!s)
         return '';
@@ -235,6 +299,8 @@ function buildCriteriaContext(successCriteria) {
 export async function buildSkillContext(jobName, jobPrompt, agentSlug, pinnedSkills, memoryStore, opts) {
     const applied = [];
     const missing = [];
+    const pinnedToolsRequested = [];
+    const pinnedBodies = [];
     try {
         const { searchSkills, recordSkillUse, loadSkillByName } = await import('./skill-extractor.js');
         const skillQuery = jobName + ' ' + jobPrompt.slice(0, 200);
@@ -305,8 +371,23 @@ export async function buildSkillContext(jobName, jobPrompt, agentSlug, pinnedSki
                 seen.add(m.name);
             }
         }
+        // 1.18.125 — collect pinned-skill tool declarations + bodies so the
+        // cron planner can widen `allowedTools` / `allowedMcpServers` with what
+        // the pinned skills explicitly need. Pins (not auto-matches) widen scope
+        // because pinning is the user's explicit signal of intent.
+        const pinnedSeen = new Set();
+        for (const s of prepared) {
+            if (s.source !== 'pinned')
+                continue;
+            if (pinnedSeen.has(s.name))
+                continue;
+            pinnedSeen.add(s.name);
+            for (const t of s.toolsUsed)
+                pinnedToolsRequested.push(t);
+            pinnedBodies.push(s.content);
+        }
         if (prepared.length === 0)
-            return { text: '', applied, missing };
+            return { text: '', applied, missing, pinnedToolsRequested: [], pinnedBodies: [] };
         // Folder-form bundled-file budget. Anthropic skill spec says the body
         // should be ≤500 lines; bundled files (templates/, reference docs)
         // load on top. We cap aggregate inlined bundle bytes so a skill with a
@@ -398,11 +479,11 @@ export async function buildSkillContext(jobName, jobPrompt, agentSlug, pinnedSki
             return block;
         });
         const text = `## Learned Procedures (from past successful executions)\nFollow these proven approaches when applicable:\n\n${skillLines.join('\n\n')}\n\n`;
-        return { text, applied, missing };
+        return { text, applied, missing, pinnedToolsRequested: [...new Set(pinnedToolsRequested)], pinnedBodies };
     }
     catch (err) {
         logger.debug({ err, jobName }, 'buildSkillContext failed (non-fatal)');
-        return { text: '', applied, missing };
+        return { text: '', applied, missing, pinnedToolsRequested: [], pinnedBodies: [] };
     }
 }
 /**
@@ -463,15 +544,25 @@ export async function buildCronExecutionPlan(opts) {
         ].filter(Boolean).join('\n\n'),
         profile: opts.profile,
     });
+    // 1.18.125 — pinned-skill scope widening (SDK alignment).
+    // A pinned skill that declares `clementine.tools.allow` or references
+    // `mcp__server__tool` in its body needs those tools/servers to actually
+    // be live for the SDK call — not just rendered into the prompt as text.
+    // We widen (never narrow) the cron's allowlists with what the pinned
+    // skills declared. Auto-matched skills don't widen scope (only explicit
+    // pins do — the user's positive signal).
+    const skillReferencedMcpServers = extractMcpServersFromSkillBodies(skillResult.pinnedBodies);
+    const widenedJobAllowedTools = widenAllowlistWithSkillTools(opts.allowedTools, skillResult.pinnedToolsRequested);
+    const widenedJobMcpAllowlist = widenMcpAllowlistWithSkillRefs(opts.allowedMcpServers, skillReferencedMcpServers);
     // Per-trick MCP allowlist: post-filter on the profile-narrowed map.
-    // Effective set = profile ∩ trick.
-    const mcpServerMap = applyMcpAllowlist(mcp.servers, opts.allowedMcpServers);
-    const allowSet = opts.allowedMcpServers?.length ? new Set(opts.allowedMcpServers) : null;
+    // Effective set = profile ∩ trick (widened).
+    const mcpServerMap = applyMcpAllowlist(mcp.servers, widenedJobMcpAllowlist);
+    const allowSet = widenedJobMcpAllowlist?.length ? new Set(widenedJobMcpAllowlist) : null;
     const composioConnected = allowSet ? mcp.composioConnected.filter(n => allowSet.has(n)) : mcp.composioConnected;
     const externalConnected = allowSet ? mcp.externalConnected.filter(n => allowSet.has(n)) : mcp.externalConnected;
     const mcpServersApplied = Object.keys(mcpServerMap);
-    // Per-trick tool allowlist intersection.
-    const effectiveAllowedTools = computeEffectiveAllowedTools(opts.allowedTools, opts.profile?.team?.allowedTools);
+    // Per-trick tool allowlist intersection (widened by pinned-skill needs).
+    const effectiveAllowedTools = computeEffectiveAllowedTools(widenedJobAllowedTools, opts.profile?.team?.allowedTools);
     // Per-tier cap from config (BUDGET.cronT1 / BUDGET.cronT2). 0 = uncapped.
     const configuredCap = tier >= 2 ? BUDGET.cronT2 : BUDGET.cronT1;
     const maxBudget = opts.maxBudgetUsd ?? (configuredCap > 0 ? configuredCap : undefined);
@@ -516,6 +607,12 @@ export async function buildCronExecutionPlan(opts) {
             return false;
         }
     });
+    // Diagnostics: what did the pinned skills add on top of what the cron
+    // already declared? Renders in the Preview UI as "Skill widened scope: …"
+    const baseToolSet = new Set(opts.allowedTools ?? []);
+    const widenedToolsFromSkills = skillResult.pinnedToolsRequested.filter(t => !baseToolSet.has(t));
+    const baseMcpSet = new Set(opts.allowedMcpServers ?? []);
+    const widenedMcpFromSkills = skillReferencedMcpServers.filter(s => !baseMcpSet.has(s));
     return {
         builtPrompt,
         contextBlocks: {
@@ -537,6 +634,13 @@ export async function buildCronExecutionPlan(opts) {
         ownerName,
         predictable,
         additionalDirectories,
+        widenedFromSkills: {
+            // Only surface widening when the cron actually had a base allowlist —
+            // otherwise the cron is unrestricted and "widening" isn't a meaningful
+            // concept (the skills' tools were already implicitly allowed).
+            tools: opts.allowedTools?.length ? widenedToolsFromSkills : [],
+            mcpServers: opts.allowedMcpServers?.length ? widenedMcpFromSkills : [],
+        },
     };
 }
 /**
@@ -565,6 +669,7 @@ export async function runAgentCron(opts) {
         skillsMissing: plan.skillsMissing.length,
         trickAllowedTools: effectiveAllowedTools?.length,
         trickAllowedMcp: opts.allowedMcpServers?.length,
+        widenedFromSkills: plan.widenedFromSkills,
     }, 'runAgentCron: dispatching to runAgent');
     const startedAt = Date.now();
     const result = await runAgent(builtPrompt, {

package/dist/agent/skill-store.d.ts

@@ -110,5 +110,22 @@ export interface WriteSkillResult {
     overwrote: boolean;
 }
 export declare function writeSkill(input: WriteSkillInput): WriteSkillResult;
+export interface SkillBackupSweepResult {
+    /** Files removed this pass. Absolute paths. */
+    removed: string[];
+    /** Files inspected (matched the pattern). Useful for "nothing to do" telemetry. */
+    inspected: number;
+    /** Files that matched the pattern but were younger than the cutoff (kept). */
+    keptFresh: number;
+}
+/**
+ * Sweep `.md.bak` skill backups older than `LEGACY_BAK_AGE_DAYS` from the
+ * global skills directory and from every per-agent skills directory under
+ * `00-System/agents/<slug>/skills/`. Best-effort: per-file errors are
+ * swallowed so a permission glitch on one file doesn't stop the sweep.
+ *
+ * Idempotent — safe to call repeatedly. Returns counts for logging.
+ */
+export declare function cleanupLegacySkillBackups(): SkillBackupSweepResult;
 export {};
 //# sourceMappingURL=skill-store.d.ts.map

package/dist/agent/skill-store.js

@@ -21,7 +21,7 @@
  * runner. Phase C wires runtime invocation. Phase E migrates legacy
  * crons → folder-form skills.
  */
-import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import matter from 'gray-matter';
@@ -713,4 +713,83 @@ export function writeSkill(input) {
     writeFileSync(entryPath, content);
     return { filePath: entryPath, name: input.name, overwrote: existed };
 }
+// ── Legacy backup janitor (1.18.125) ─────────────────────────────────
+//
+// Pre-1.18.124, `saveActiveSkill` wrote a per-overwrite `.md.bak` next to
+// every skill it updated. The new `writeSkill` path doesn't create these,
+// but the old ones rot in the vault forever unless something sweeps them.
+// `cleanupLegacySkillBackups` finds `.md.bak` files older than the cutoff
+// and removes them. Runs from the periodic memory-maintenance cycle so
+// users don't need to know it exists.
+//
+// Conservative: 30-day age floor + only the slug-named `.md.bak` pattern.
+// Anything mtime-recent stays put in case a user is mid-rollback.
+const LEGACY_BAK_AGE_DAYS = 30;
+const LEGACY_BAK_AGE_MS = LEGACY_BAK_AGE_DAYS * 24 * 60 * 60 * 1000;
+/**
+ * Sweep `.md.bak` skill backups older than `LEGACY_BAK_AGE_DAYS` from the
+ * global skills directory and from every per-agent skills directory under
+ * `00-System/agents/<slug>/skills/`. Best-effort: per-file errors are
+ * swallowed so a permission glitch on one file doesn't stop the sweep.
+ *
+ * Idempotent — safe to call repeatedly. Returns counts for logging.
+ */
+export function cleanupLegacySkillBackups() {
+    const result = { removed: [], inspected: 0, keptFresh: 0 };
+    const cutoff = Date.now() - LEGACY_BAK_AGE_MS;
+    const sweepRoots = [globalSkillsDir()];
+    // Per-agent skill dirs — discover via the agents/ folder.
+    try {
+        const base = process.env.CLEMENTINE_HOME || path.join(os.homedir(), '.clementine');
+        const agentsDir = path.join(base, 'vault', '00-System', 'agents');
+        if (existsSync(agentsDir)) {
+            for (const entry of readdirSync(agentsDir)) {
+                if (entry.startsWith('.'))
+                    continue;
+                const agentSkillsDir = path.join(agentsDir, entry, 'skills');
+                if (existsSync(agentSkillsDir))
+                    sweepRoots.push(agentSkillsDir);
+            }
+        }
+    }
+    catch { /* non-fatal — global sweep still runs */ }
+    for (const root of sweepRoots) {
+        let entries;
+        try {
+            entries = readdirSync(root);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            // Match exactly the legacy pattern. Don't touch anything else — we
+            // never want to nuke `templates/old-draft.md.bak` inside a folder skill,
+            // for instance. The legacy writer only ever produced flat
+            // `<slug>.md.bak` siblings, so that's all we sweep.
+            if (!entry.endsWith('.md.bak'))
+                continue;
+            const full = path.join(root, entry);
+            let st;
+            try {
+                st = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (!st.isFile())
+                continue;
+            result.inspected++;
+            if (st.mtimeMs > cutoff) {
+                result.keptFresh++;
+                continue;
+            }
+            try {
+                unlinkSync(full);
+                result.removed.push(full);
+            }
+            catch { /* skip — permission or race; next sweep retries */ }
+        }
+    }
+    return result;
+}
 //# sourceMappingURL=skill-store.js.map

package/dist/memory/maintenance.js

@@ -146,6 +146,19 @@ export async function runStartupMaintenance(store) {
     catch (err) {
         logger.warn({ err }, 'Startup janitor failed');
     }
+    // Vault janitor (1.18.125) — sweep legacy `.md.bak` skill backups so the
+    // first daemon boot after upgrade clears the existing leak instead of
+    // waiting 6h for the periodic cycle.
+    try {
+        const { cleanupLegacySkillBackups } = await import('../agent/skill-store.js');
+        const sweep = cleanupLegacySkillBackups();
+        if (sweep.removed.length > 0) {
+            logger.info({ removed: sweep.removed.length, inspected: sweep.inspected, keptFresh: sweep.keptFresh }, 'Startup .md.bak sweep');
+        }
+    }
+    catch (err) {
+        logger.warn({ err }, 'Startup .md.bak sweep failed');
+    }
     // Embedding warm-up — pre-embed the most-cited chunks in the background so
     // the first retrievals after startup don't pay cold-start latency. Fire
     // and forget; never blocks startup.
@@ -247,6 +260,20 @@ export async function runPeriodicCycle(store, llmCall) {
     catch (err) {
         logger.warn({ err }, 'Periodic janitor failed');
     }
+    // 6a. Vault janitor — sweep legacy `.md.bak` skill backups (1.18.125).
+    // Pre-1.18.124 saveActiveSkill wrote per-overwrite backups; the new
+    // writeSkill path doesn't, so the old ones rot in the vault. Cap age
+    // at 30 days to give rollback room. No-op when nothing to sweep.
+    try {
+        const { cleanupLegacySkillBackups } = await import('../agent/skill-store.js');
+        const sweep = cleanupLegacySkillBackups();
+        if (sweep.removed.length > 0) {
+            logger.info({ removed: sweep.removed.length, inspected: sweep.inspected, keptFresh: sweep.keptFresh }, 'Legacy skill .md.bak sweep');
+        }
+    }
+    catch (err) {
+        logger.warn({ err }, 'Legacy skill .md.bak sweep failed');
+    }
     // 6b. Integrity probes — FTS health, orphan derived_from, embedding gaps.
     try {
         const report = runIntegrityProbes(store);

package/package.json

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