clementine-agent 1.18.161 → 1.18.162

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

@@ -0,0 +1,135 @@
+/**
+ * runSkill — the canonical Skill execution primitive (1.18.162).
+ *
+ * Closes Skills Runtime C-2 from the Skills-First redesign.
+ *
+ * Today (pre-1.18.162) a pinned skill is fed into a cron prompt as a
+ * markdown context block and its `clementine.tools.allow` list is UNIONED
+ * into the cron's allowedTools (1.18.121 widening). That is permissive,
+ * not enforced — a skill that says "I only use Bash + WebFetch" can still
+ * call any tool the surrounding cron allows.
+ *
+ * `runSkill(name, options)` is the alternative path: a sub-call where the
+ * skill's `tools.allow` is a HARD allowlist (only those tools, plus a
+ * minimal core set), `{{var}}` placeholders in the body are substituted
+ * from `options.inputs`, and `clementine.success.schema` is ajv-validated
+ * post-run.
+ *
+ * Why a separate primitive (and not a flag on the existing widening path):
+ * - Caller intent is different. Pinned-skills-as-context is "give the LLM
+ *   reference material"; runSkill is "do this specific procedure now."
+ * - Hard enforcement requires constructing the SDK call ourselves, not
+ *   reusing a cron-job's effective allowlist.
+ * - Inputs/success are skill-call concepts, not cron concepts.
+ *
+ * Surfaced as the MCP tool `run_skill(name, inputs?)` so chat + cron +
+ * sub-agents converge on one primitive.
+ */
+import type { Skill } from '../types.js';
+export interface RunSkillOptions {
+    /** Mustache-style `{{var}}` substitutions for the skill body. */
+    inputs?: Record<string, string | number | boolean>;
+    /** Optional caller context appended after the skill body
+     *  (e.g. the user's request, the cron firing context). */
+    context?: string;
+    /** Stable session key for transcript mirroring. Defaults to a synthesized
+     *  key derived from the skill name + timestamp. */
+    sessionKey?: string;
+    /** Source classification for telemetry. Defaults to 'skill'. */
+    source?: string;
+    /** Optional model override. */
+    model?: string;
+    /** Hard turn cap. Falls back to `clementine.limits.maxTurns` if set. */
+    maxTurns?: number;
+    /** Hard budget cap (USD). Falls back to `clementine.limits.maxBudgetUsd`. */
+    maxBudgetUsd?: number;
+    /** Project work dir for per-project skill precedence (mirrors getSkill's
+     *  `projectWorkDir` parameter — when set, project-scoped skills shadow
+     *  global ones with the same name). */
+    projectWorkDir?: string;
+    /** Skip success.schema validation even if the skill declares one. */
+    skipValidation?: boolean;
+    /** Streaming callback for partial assistant text. */
+    onText?: (chunk: string) => void | Promise<void>;
+    /** Abort signal — cancels the SDK stream when triggered. */
+    abortSignal?: AbortSignal;
+}
+export interface RunSkillResult {
+    ok: boolean;
+    /** Final text response from the SDK. */
+    output: string;
+    /** Cost in USD. */
+    cost?: number;
+    /** Number of agentic turns. */
+    turns?: number;
+    /** SDK session id — capture for resume. */
+    sessionId?: string;
+    /** SDK runId — joins to the Event store. */
+    runId?: string;
+    /** Schema validation result when the skill declared `clementine.success.schema`. */
+    validation?: {
+        /** True when validation actually ran (schema present + JSON extractable). */
+        tried: boolean;
+        /** True when the response validated against the schema. */
+        pass: boolean;
+        /** First few ajv error messages. */
+        errors: string[];
+    };
+    /** The hard allowlist that was passed to the SDK. */
+    effectiveTools?: string[];
+    /** Failure reason when ok=false. */
+    error?: string;
+}
+/**
+ * Substitute `{{var}}` placeholders in `body` from `inputs`. Missing
+ * keys are left as-is (so the LLM still sees the placeholder and can
+ * complain) rather than silently dropped — a missing input is more
+ * recoverable as visible text than as a stripped string.
+ */
+export declare function applyMustache(body: string, inputs: Record<string, string | number | boolean> | undefined): string;
+/**
+ * Compute the HARD allowlist for a skill call.
+ *
+ * Combines, in order:
+ *   1. The skill's `clementine.tools.allow` list (or [] if absent)
+ *   2. Tool names auto-extracted from the skill body matching `mcp__*__*`
+ *   3. SKILL_BASELINE_TOOLS so the SDK can read files / dispatch subagents
+ *
+ * Then subtracts anything in `clementine.tools.deny` (deny wins).
+ *
+ * Returns a deduped array. Empty input = empty output (which the SDK
+ * treats as "deny everything"); callers are expected to set a sensible
+ * `tools.allow` on the skill.
+ */
+export declare function computeSkillAllowlist(skill: Skill): string[];
+/**
+ * Build the prompt the SDK actually executes for a skill call.
+ *
+ * Format:
+ *   <skill body, with mustache substitutions applied>
+ *
+ *   ## Caller context
+ *   <options.context>      ← when provided
+ *
+ * The skill body itself becomes the procedure; the optional context is
+ * the immediate "what triggered this call" frame. Bundled files (other
+ * .md siblings under the skill folder) are NOT inlined — the SDK can
+ * read them via `Read` if listed under tools.allow.
+ */
+export declare function buildSkillPrompt(skill: Skill, inputs: Record<string, string | number | boolean> | undefined, context: string | undefined): string;
+/**
+ * Run a skill as a hard-allowlisted sub-call. Returns a structured result.
+ *
+ * The skill is loaded via `getSkill()` (project-precedence honored when
+ * `projectDir` + `agentSlug` are passed). Its body is mustache-rendered
+ * with `inputs`, then sent to the SDK with an allowlist computed from
+ * `clementine.tools.allow` + auto-extracted MCP refs + a small baseline.
+ * After the SDK returns, `clementine.success.schema` (when set) is
+ * ajv-validated against the response.
+ *
+ * This function never throws — failures (skill not found, SDK error,
+ * timeout) are returned as `{ ok: false, error }`. The caller (chat,
+ * cron, sub-agent, MCP tool) decides how to surface that.
+ */
+export declare function runSkill(name: string, options?: RunSkillOptions): Promise<RunSkillResult>;
+//# sourceMappingURL=run-skill.d.ts.map

package/dist/agent/run-skill.js

@@ -0,0 +1,267 @@
+/**
+ * runSkill — the canonical Skill execution primitive (1.18.162).
+ *
+ * Closes Skills Runtime C-2 from the Skills-First redesign.
+ *
+ * Today (pre-1.18.162) a pinned skill is fed into a cron prompt as a
+ * markdown context block and its `clementine.tools.allow` list is UNIONED
+ * into the cron's allowedTools (1.18.121 widening). That is permissive,
+ * not enforced — a skill that says "I only use Bash + WebFetch" can still
+ * call any tool the surrounding cron allows.
+ *
+ * `runSkill(name, options)` is the alternative path: a sub-call where the
+ * skill's `tools.allow` is a HARD allowlist (only those tools, plus a
+ * minimal core set), `{{var}}` placeholders in the body are substituted
+ * from `options.inputs`, and `clementine.success.schema` is ajv-validated
+ * post-run.
+ *
+ * Why a separate primitive (and not a flag on the existing widening path):
+ * - Caller intent is different. Pinned-skills-as-context is "give the LLM
+ *   reference material"; runSkill is "do this specific procedure now."
+ * - Hard enforcement requires constructing the SDK call ourselves, not
+ *   reusing a cron-job's effective allowlist.
+ * - Inputs/success are skill-call concepts, not cron concepts.
+ *
+ * Surfaced as the MCP tool `run_skill(name, inputs?)` so chat + cron +
+ * sub-agents converge on one primitive.
+ */
+import path from 'node:path';
+import pino from 'pino';
+import { getSkill } from './skill-store.js';
+import { runAgent } from './run-agent.js';
+const logger = pino({ name: 'clementine.run-skill' });
+// ── Mustache substitution ─────────────────────────────────────────────
+/** Matches `{{var_name}}` with optional whitespace. var_name is
+ *  `[a-zA-Z_][a-zA-Z0-9_-]*` — the same identifier shape used in YAML
+ *  frontmatter `inputs:` keys. */
+const MUSTACHE = /\{\{\s*([a-zA-Z_][a-zA-Z0-9_-]*)\s*\}\}/g;
+/**
+ * Substitute `{{var}}` placeholders in `body` from `inputs`. Missing
+ * keys are left as-is (so the LLM still sees the placeholder and can
+ * complain) rather than silently dropped — a missing input is more
+ * recoverable as visible text than as a stripped string.
+ */
+export function applyMustache(body, inputs) {
+    if (!inputs || Object.keys(inputs).length === 0)
+        return body;
+    return body.replace(MUSTACHE, (match, key) => {
+        if (Object.prototype.hasOwnProperty.call(inputs, key)) {
+            return String(inputs[key]);
+        }
+        return match;
+    });
+}
+// ── Allowlist computation ─────────────────────────────────────────────
+/** Tools every skill needs as a baseline regardless of its `tools.allow`.
+ *  Without these the SDK can't navigate the project at all. Read/Glob/Grep
+ *  are non-mutating; Agent is required so the SDK can dispatch its own
+ *  internal subagents. */
+const SKILL_BASELINE_TOOLS = ['Agent', 'Read', 'Glob', 'Grep'];
+/** Matches `mcp__<server>__<tool>` references in skill bodies. Used to
+ *  auto-include MCP tool names the skill *clearly* intends to call but
+ *  which the author forgot to list under `tools.allow`. Same pattern as
+ *  run-agent-cron.ts:150. */
+const MCP_TOOL_REF = /mcp__([A-Za-z0-9-]+(?:_[A-Za-z0-9-]+)*)__[A-Za-z0-9_-]+/g;
+/**
+ * Compute the HARD allowlist for a skill call.
+ *
+ * Combines, in order:
+ *   1. The skill's `clementine.tools.allow` list (or [] if absent)
+ *   2. Tool names auto-extracted from the skill body matching `mcp__*__*`
+ *   3. SKILL_BASELINE_TOOLS so the SDK can read files / dispatch subagents
+ *
+ * Then subtracts anything in `clementine.tools.deny` (deny wins).
+ *
+ * Returns a deduped array. Empty input = empty output (which the SDK
+ * treats as "deny everything"); callers are expected to set a sensible
+ * `tools.allow` on the skill.
+ */
+export function computeSkillAllowlist(skill) {
+    const tools = skill.frontmatter?.clementine?.tools;
+    const declared = Array.isArray(tools?.allow) ? tools.allow : [];
+    const denied = new Set(Array.isArray(tools?.deny) ? tools.deny : []);
+    const fromBody = new Set();
+    let m;
+    // exec() with /g shares state per-regex; reset before each pass.
+    MCP_TOOL_REF.lastIndex = 0;
+    while ((m = MCP_TOOL_REF.exec(skill.body)) !== null) {
+        // m[0] is the full mcp__<server>__<tool> match
+        fromBody.add(m[0]);
+    }
+    const merged = new Set([
+        ...declared,
+        ...fromBody,
+        ...SKILL_BASELINE_TOOLS,
+    ]);
+    for (const d of denied)
+        merged.delete(d);
+    return [...merged];
+}
+// ── Prompt builder ────────────────────────────────────────────────────
+/**
+ * Build the prompt the SDK actually executes for a skill call.
+ *
+ * Format:
+ *   <skill body, with mustache substitutions applied>
+ *
+ *   ## Caller context
+ *   <options.context>      ← when provided
+ *
+ * The skill body itself becomes the procedure; the optional context is
+ * the immediate "what triggered this call" frame. Bundled files (other
+ * .md siblings under the skill folder) are NOT inlined — the SDK can
+ * read them via `Read` if listed under tools.allow.
+ */
+export function buildSkillPrompt(skill, inputs, context) {
+    const substitutedBody = applyMustache(skill.body, inputs);
+    if (!context || !context.trim())
+        return substitutedBody;
+    return `${substitutedBody}\n\n## Caller context\n\n${context.trim()}\n`;
+}
+// ── Schema validation ─────────────────────────────────────────────────
+/** Best-effort JSON extraction: try whole text, then fenced ```json
+ *  block, then the largest {…} substring. Mirrors goal-evaluator.ts so
+ *  skill authors get the same forgiving behavior as goalCheck. */
+function extractJson(text) {
+    if (!text)
+        return null;
+    const trimmed = text.trim();
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch { /* fall through */ }
+    const fenced = /```json\s*([\s\S]*?)```/i.exec(text);
+    if (fenced?.[1]) {
+        try {
+            return JSON.parse(fenced[1]);
+        }
+        catch { /* fall through */ }
+    }
+    const start = text.indexOf('{');
+    const end = text.lastIndexOf('}');
+    if (start !== -1 && end > start) {
+        try {
+            return JSON.parse(text.slice(start, end + 1));
+        }
+        catch { /* fall through */ }
+    }
+    return null;
+}
+async function validateSkillOutput(output, schema) {
+    const json = extractJson(output);
+    if (json === null)
+        return { tried: false, pass: false, errors: [] };
+    try {
+        // Lazy import: ajv pulls in ~150KB and most callers won't have a schema.
+        // Default-export interop matches goal-evaluator.ts:75 — ajv@8 is CJS
+        // and the ESM bridge sometimes lands the constructor on .default.
+        const ajvMod = await import('ajv');
+        const AjvCtor = ajvMod.default ?? ajvMod;
+        const ajv = new AjvCtor({ allErrors: true, strict: false });
+        const validate = ajv.compile(schema);
+        const valid = validate(json);
+        const rawErrors = validate.errors ?? ajv.errors ?? [];
+        return {
+            tried: true,
+            pass: !!valid,
+            errors: rawErrors.slice(0, 5).map(e => {
+                const p = e.instancePath || '';
+                const m = e.message || 'invalid';
+                return p ? `${p} ${m}` : m;
+            }),
+        };
+    }
+    catch (err) {
+        return { tried: true, pass: false, errors: [`schema compile error: ${err}`] };
+    }
+}
+// ── The primitive ─────────────────────────────────────────────────────
+/**
+ * Run a skill as a hard-allowlisted sub-call. Returns a structured result.
+ *
+ * The skill is loaded via `getSkill()` (project-precedence honored when
+ * `projectDir` + `agentSlug` are passed). Its body is mustache-rendered
+ * with `inputs`, then sent to the SDK with an allowlist computed from
+ * `clementine.tools.allow` + auto-extracted MCP refs + a small baseline.
+ * After the SDK returns, `clementine.success.schema` (when set) is
+ * ajv-validated against the response.
+ *
+ * This function never throws — failures (skill not found, SDK error,
+ * timeout) are returned as `{ ok: false, error }`. The caller (chat,
+ * cron, sub-agent, MCP tool) decides how to surface that.
+ */
+export async function runSkill(name, options = {}) {
+    const skill = getSkill(name, {
+        ...(options.projectWorkDir ? { projectWorkDir: options.projectWorkDir } : {}),
+    });
+    if (!skill) {
+        return {
+            ok: false,
+            output: '',
+            error: `Skill not found: ${name}`,
+        };
+    }
+    const effectiveTools = computeSkillAllowlist(skill);
+    const prompt = buildSkillPrompt(skill, options.inputs, options.context);
+    const limits = skill.frontmatter?.clementine?.limits;
+    const maxTurns = options.maxTurns ?? limits?.maxTurns;
+    const maxBudgetUsd = options.maxBudgetUsd ?? limits?.maxBudgetUsd;
+    const sessionKey = options.sessionKey
+        ?? `skill:${name}:${Date.now().toString(36)}`;
+    // Surface the skill folder to the SDK via additionalDirectories so
+    // bundled scripts (skill/scripts/*.py) are reachable for `Bash` calls.
+    // Folder-form skills only — flat skills have no siblings worth surfacing.
+    const additionalDirectories = skill.layout === 'folder' ? [path.dirname(skill.filePath)] : undefined;
+    logger.info({
+        skill: name,
+        tools: effectiveTools,
+        maxTurns,
+        maxBudgetUsd,
+        inputKeys: Object.keys(options.inputs ?? {}),
+        hasContext: !!options.context,
+    }, 'runSkill: invoking');
+    let runResult;
+    try {
+        const sdkOpts = {
+            sessionKey,
+            source: options.source ?? 'skill',
+            allowedTools: effectiveTools,
+            ...(options.model ? { model: options.model } : {}),
+            ...(typeof maxTurns === 'number' ? { maxTurns } : {}),
+            ...(typeof maxBudgetUsd === 'number' ? { maxBudgetUsd } : {}),
+            ...(additionalDirectories ? { additionalDirectories } : {}),
+            ...(options.onText ? { onText: options.onText } : {}),
+            ...(options.abortSignal ? { abortSignal: options.abortSignal } : {}),
+        };
+        runResult = await runAgent(prompt, sdkOpts);
+    }
+    catch (err) {
+        logger.error({ err, skill: name }, 'runSkill: SDK call failed');
+        return {
+            ok: false,
+            output: '',
+            effectiveTools,
+            error: `SDK error: ${err}`,
+        };
+    }
+    // Schema validation — only when the skill declared one and the caller
+    // didn't opt out. We do not flip ok=false on schema fail; we surface
+    // the result so the caller can decide. (A cron may want to retry; a
+    // chat user just sees a "schema mismatch" badge.)
+    let validation;
+    const successSchema = skill.frontmatter?.clementine?.success?.schema;
+    if (!options.skipValidation && successSchema) {
+        validation = await validateSkillOutput(runResult.text, successSchema);
+    }
+    return {
+        ok: true,
+        output: runResult.text,
+        cost: runResult.totalCostUsd,
+        turns: runResult.numTurns,
+        sessionId: runResult.sessionId,
+        runId: runResult.runId,
+        effectiveTools,
+        ...(validation ? { validation } : {}),
+    };
+}
+//# sourceMappingURL=run-skill.js.map

package/dist/tools/skill-tools.js

@@ -214,5 +214,43 @@ export function registerSkillTools(server) {
             return textResult(`❌ Failed to list skills: ${err instanceof Error ? err.message : String(err)}`);
         }
     });
+    // ── run_skill (1.18.162) ────────────────────────────────────────────
+    // Invoke a skill as a hard-allowlisted sub-call. Mustache substitutes
+    // `{{var}}` placeholders in the skill body from `inputs`, runs through
+    // the SDK with ONLY the skill's clementine.tools.allow + a baseline
+    // (Agent/Read/Glob/Grep) + auto-extracted mcp__*__* refs from the body,
+    // and validates against clementine.success.schema if declared.
+    //
+    // Use this when a chat or another skill needs to *execute* a procedure
+    // (not just reference it). Pinned-skills-as-context (the existing 1.18.121
+    // widening path) is for the cron prompt; this is for callable execution.
+    server.tool('run_skill', 'Execute a named skill as a sub-call with a HARD tool allowlist. The skill body is rendered with optional {{var}} substitutions from `inputs`, then run with only the tools the skill declared under clementine.tools.allow (plus a small baseline). Returns the skill output + cost + schema validation result when applicable. Use when chat says "run my morning-briefing skill" or when one skill needs to invoke another.', {
+        name: z.string().regex(NAME_PATTERN).describe('Skill slug (e.g. "morning-briefing"). Must match an existing skill in the vault.'),
+        inputs: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional()
+            .describe('Optional key→value map substituted into {{var}} placeholders in the skill body. Missing placeholders are left as-is so the LLM can complain.'),
+        context: z.string().optional()
+            .describe('Optional caller context appended after the skill body (e.g. "user said: do X right now"). Surfaced under a "## Caller context" heading.'),
+    }, async ({ name, inputs, context }) => {
+        try {
+            // Lazy import — runSkill pulls in run-agent + the SDK; only load on
+            // demand so `list_skills` etc stay fast and the MCP server boots
+            // without warming the whole agent path.
+            const { runSkill } = await import('../agent/run-skill.js');
+            const result = await runSkill(name, { inputs, context, source: 'mcp:run_skill' });
+            if (!result.ok) {
+                return textResult(`❌ run_skill(${name}) failed: ${result.error ?? 'unknown error'}`);
+            }
+            const validationLine = result.validation
+                ? `\n\n**Schema:** ${result.validation.tried ? (result.validation.pass ? '✅ pass' : `❌ fail — ${result.validation.errors.slice(0, 2).join('; ')}`) : '(skipped — no JSON in output)'}`
+                : '';
+            const meta = `\n\n_${result.turns ?? 0} turns · $${(result.cost ?? 0).toFixed(4)} · ${result.effectiveTools?.length ?? 0} tools allowed_${validationLine}`;
+            return textResult(`${result.output}${meta}`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            logger.error({ err, skill: name }, 'run_skill failed');
+            return textResult(`❌ run_skill(${name}) failed: ${msg}`);
+        }
+    });
 }
 //# sourceMappingURL=skill-tools.js.map

package/package.json

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