clementine-agent 1.18.128 → 1.18.130

package/dist/agent/schedule-registry.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Schedule registry — 1.18.129.
+ *
+ * The Anthropic-pure architectural shift: skills stay vanilla SKILL.md
+ * folders, scheduling lives in a separate tiny registry. Today's "fat
+ * cron" model in CRON.md duplicated ~70% of the skill schema (prompt,
+ * tools, MCP allowlists, work_dir, success criteria); this registry
+ * replaces all that with a thin {skillName → schedule} map.
+ *
+ * Storage: a single JSON file at `~/.clementine/schedules.json` with
+ * the shape:
+ *
+ *   {
+ *     "morning-briefing": {
+ *       "schedule": "0 7 * * 1-5",
+ *       "enabled": true,
+ *       "agentSlug": null,
+ *       "addedAt": "2026-05-08T...",
+ *       "lastModifiedAt": "2026-05-08T..."
+ *     }
+ *   }
+ *
+ * The cron scheduler reads this alongside CRON.md and emits one
+ * CronJobDefinition per scheduled skill. The runtime path is unchanged
+ * — the skill body becomes the prompt via the existing buildSkillContext
+ * pipeline, no special case.
+ *
+ * Coexists with CRON.md indefinitely. Both formats run today; new work
+ * goes through this registry. Phase 3 ships the migrator that converts
+ * legacy crons to scheduled skills.
+ */
+export interface ScheduleEntry {
+    /** Skill slug — must match a skill in the catalog. The runtime auto-pins
+     *  this skill, so its body becomes the prompt at fire-time. */
+    skillName: string;
+    /** Cron expression. Empty / falsy = no auto-fire (still appears on
+     *  Tasks page so the user can edit it). */
+    schedule: string;
+    /** When false the scheduler skips it. Lets users pause without losing
+     *  the schedule definition. */
+    enabled: boolean;
+    /** When set, the skill runs as the named hired agent (Sasha, Ross,
+     *  Nora, etc.). null/undefined = Clementine. Per-agent skills load
+     *  from `agents/<slug>/skills/` first; the runtime resolves precedence. */
+    agentSlug?: string | null;
+    /** ISO timestamp of when the schedule was first created. */
+    addedAt?: string;
+    /** ISO timestamp of the last edit. */
+    lastModifiedAt?: string;
+}
+/** On-disk shape — keyed by skill name for O(1) lookup + simple merge. */
+export type ScheduleFile = Record<string, Omit<ScheduleEntry, 'skillName'>>;
+/**
+ * Read every schedule entry as a flat array. Each entry includes its
+ * skill name so callers don't have to reconstruct it.
+ */
+export declare function listSchedules(): ScheduleEntry[];
+/** Read one entry by skill name. Returns null when not scheduled. */
+export declare function getSchedule(skillName: string): ScheduleEntry | null;
+export interface SetScheduleInput {
+    schedule: string;
+    enabled?: boolean;
+    agentSlug?: string | null;
+}
+/**
+ * Upsert a schedule for a skill. New entries get `addedAt`; existing
+ * entries get `lastModifiedAt` updated. Returns the resulting entry so
+ * the dashboard can re-render without a re-fetch.
+ */
+export declare function setSchedule(skillName: string, input: SetScheduleInput): ScheduleEntry;
+/** Drop the entry for a skill. No-op when nothing is scheduled. */
+export declare function removeSchedule(skillName: string): void;
+/** Toggle the enabled flag. Skill stays in the registry; just won't
+ *  fire while disabled. Caller-side convenience to avoid re-passing
+ *  schedule + agentSlug just to flip the boolean. */
+export declare function enableSchedule(skillName: string, enabled: boolean): ScheduleEntry | null;
+//# sourceMappingURL=schedule-registry.d.ts.map

package/dist/agent/schedule-registry.js

@@ -0,0 +1,147 @@
+/**
+ * Schedule registry — 1.18.129.
+ *
+ * The Anthropic-pure architectural shift: skills stay vanilla SKILL.md
+ * folders, scheduling lives in a separate tiny registry. Today's "fat
+ * cron" model in CRON.md duplicated ~70% of the skill schema (prompt,
+ * tools, MCP allowlists, work_dir, success criteria); this registry
+ * replaces all that with a thin {skillName → schedule} map.
+ *
+ * Storage: a single JSON file at `~/.clementine/schedules.json` with
+ * the shape:
+ *
+ *   {
+ *     "morning-briefing": {
+ *       "schedule": "0 7 * * 1-5",
+ *       "enabled": true,
+ *       "agentSlug": null,
+ *       "addedAt": "2026-05-08T...",
+ *       "lastModifiedAt": "2026-05-08T..."
+ *     }
+ *   }
+ *
+ * The cron scheduler reads this alongside CRON.md and emits one
+ * CronJobDefinition per scheduled skill. The runtime path is unchanged
+ * — the skill body becomes the prompt via the existing buildSkillContext
+ * pipeline, no special case.
+ *
+ * Coexists with CRON.md indefinitely. Both formats run today; new work
+ * goes through this registry. Phase 3 ships the migrator that converts
+ * legacy crons to scheduled skills.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+// Resolve lazily on each call so test environments (which override
+// CLEMENTINE_HOME inside beforeEach) see the fresh value rather than the
+// value snapshot at module-load time. Mirrors skill-suppressions.ts.
+function baseDir() {
+    return process.env.CLEMENTINE_HOME || path.join(os.homedir(), '.clementine');
+}
+function schedulesPath() {
+    return path.join(baseDir(), 'schedules.json');
+}
+function readFile() {
+    const filePath = schedulesPath();
+    if (!existsSync(filePath))
+        return {};
+    try {
+        const raw = JSON.parse(readFileSync(filePath, 'utf-8'));
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            return {};
+        const out = {};
+        for (const [name, entry] of Object.entries(raw)) {
+            if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+                continue;
+            const e = entry;
+            // Tolerate partially-populated entries (a hand-edited file might
+            // have only `schedule` set). Default everything else.
+            out[name] = {
+                schedule: typeof e.schedule === 'string' ? e.schedule : '',
+                enabled: e.enabled !== false, // default true
+                agentSlug: typeof e.agentSlug === 'string' ? e.agentSlug : null,
+                addedAt: typeof e.addedAt === 'string' ? e.addedAt : undefined,
+                lastModifiedAt: typeof e.lastModifiedAt === 'string' ? e.lastModifiedAt : undefined,
+            };
+        }
+        return out;
+    }
+    catch {
+        // Malformed JSON — never throw out of the registry. Worst case the
+        // user re-creates entries via the UI; their CRON.md jobs keep firing.
+        return {};
+    }
+}
+function writeFile(data) {
+    const dir = baseDir();
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    // Sorted keys → deterministic on disk → friendly to git users who
+    // version-control their ~/.clementine/.
+    const sorted = {};
+    for (const k of Object.keys(data).sort())
+        sorted[k] = data[k];
+    writeFileSync(schedulesPath(), JSON.stringify(sorted, null, 2));
+}
+/**
+ * Read every schedule entry as a flat array. Each entry includes its
+ * skill name so callers don't have to reconstruct it.
+ */
+export function listSchedules() {
+    const file = readFile();
+    return Object.entries(file).map(([skillName, entry]) => ({ skillName, ...entry }));
+}
+/** Read one entry by skill name. Returns null when not scheduled. */
+export function getSchedule(skillName) {
+    const file = readFile();
+    const entry = file[skillName];
+    if (!entry)
+        return null;
+    return { skillName, ...entry };
+}
+/**
+ * Upsert a schedule for a skill. New entries get `addedAt`; existing
+ * entries get `lastModifiedAt` updated. Returns the resulting entry so
+ * the dashboard can re-render without a re-fetch.
+ */
+export function setSchedule(skillName, input) {
+    if (!skillName || typeof skillName !== 'string') {
+        throw new Error('setSchedule: skillName required');
+    }
+    const file = readFile();
+    const existing = file[skillName];
+    const now = new Date().toISOString();
+    const entry = {
+        schedule: input.schedule ?? '',
+        enabled: input.enabled !== false,
+        agentSlug: input.agentSlug ?? null,
+        addedAt: existing?.addedAt ?? now,
+        lastModifiedAt: now,
+    };
+    file[skillName] = entry;
+    writeFile(file);
+    return { skillName, ...entry };
+}
+/** Drop the entry for a skill. No-op when nothing is scheduled. */
+export function removeSchedule(skillName) {
+    const file = readFile();
+    if (!(skillName in file))
+        return;
+    delete file[skillName];
+    writeFile(file);
+}
+/** Toggle the enabled flag. Skill stays in the registry; just won't
+ *  fire while disabled. Caller-side convenience to avoid re-passing
+ *  schedule + agentSlug just to flip the boolean. */
+export function enableSchedule(skillName, enabled) {
+    const file = readFile();
+    const entry = file[skillName];
+    if (!entry)
+        return null;
+    entry.enabled = enabled;
+    entry.lastModifiedAt = new Date().toISOString();
+    file[skillName] = entry;
+    writeFile(file);
+    return { skillName, ...entry };
+}
+//# sourceMappingURL=schedule-registry.js.map

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

@@ -0,0 +1,55 @@
+/**
+ * Skill templates — 1.18.130 (Phase 2 / Skill Builder).
+ *
+ * Each template scaffolds a SKILL.md frontmatter + body skeleton plus
+ * (optionally) starter bundled files. Templates encode the five common
+ * skill archetypes the user pulled out of the Anthropic skills video:
+ *
+ *   - **Orchestrator** — the meta-skill that routes work to other skills
+ *   - **Scraper / Poller** — read external data, surface what's new
+ *   - **Transformer** — mutate input → produce output (no side effects)
+ *   - **Notifier** — send a message to Discord/Slack/email when X happens
+ *   - **Conversational** — interactive multi-turn agent for one workflow
+ *
+ * The Builder asks the user to pick one when creating a new skill;
+ * the chosen template defines the starting body + suggested tools.allow.
+ * Authors edit from there. Templates aren't a runtime concept — they're
+ * just initial content the writeSkill() helper persists like any other
+ * skill.
+ */
+export interface SkillTemplate {
+    /** Stable id used by the picker. */
+    id: string;
+    /** Display name shown in the picker. */
+    label: string;
+    /** One-line "use when" hint for the picker subtitle. */
+    hint: string;
+    /** Emoji shown next to the label — gives the picker visual texture. */
+    emoji: string;
+    /** Initial frontmatter description filled into the create modal.
+     *  User can override before save; serves as a writing prompt. */
+    defaultDescription: string;
+    /** Initial Markdown body. Should follow the Anthropic procedure
+     *  shape (numbered steps, clear inputs/outputs section) so authors
+     *  start from a good pattern instead of a blank page. */
+    body: string;
+    /** Suggested clementine.tools.allow allowlist. The Builder pre-fills
+     *  the tools chip list so authors see "this archetype usually needs
+     *  Read + Bash + memory_write" right away. */
+    suggestedTools: string[];
+    /** Optional bundled files to drop alongside SKILL.md. Each entry is
+     *  written via the same writeSkill folder as the entry-point file.
+     *  Example: an Orchestrator template ships a templates/output.md
+     *  scaffold; a Scraper ships a scripts/fetch.py stub. */
+    bundledFiles?: Array<{
+        relPath: string;
+        content: string;
+    }>;
+}
+export declare const SKILL_TEMPLATES: SkillTemplate[];
+/** Lookup by id. */
+export declare function getSkillTemplate(id: string): SkillTemplate | null;
+/** Apply a template to a skill name — substitutes \`{{TITLE}}\` placeholders
+ *  in the body with the user's display title. */
+export declare function renderTemplateBody(template: SkillTemplate, displayTitle: string): string;
+//# sourceMappingURL=skill-templates.d.ts.map

package/dist/agent/skill-templates.js

@@ -0,0 +1,220 @@
+/**
+ * Skill templates — 1.18.130 (Phase 2 / Skill Builder).
+ *
+ * Each template scaffolds a SKILL.md frontmatter + body skeleton plus
+ * (optionally) starter bundled files. Templates encode the five common
+ * skill archetypes the user pulled out of the Anthropic skills video:
+ *
+ *   - **Orchestrator** — the meta-skill that routes work to other skills
+ *   - **Scraper / Poller** — read external data, surface what's new
+ *   - **Transformer** — mutate input → produce output (no side effects)
+ *   - **Notifier** — send a message to Discord/Slack/email when X happens
+ *   - **Conversational** — interactive multi-turn agent for one workflow
+ *
+ * The Builder asks the user to pick one when creating a new skill;
+ * the chosen template defines the starting body + suggested tools.allow.
+ * Authors edit from there. Templates aren't a runtime concept — they're
+ * just initial content the writeSkill() helper persists like any other
+ * skill.
+ */
+export const SKILL_TEMPLATES = [
+    {
+        id: 'orchestrator',
+        label: 'Orchestrator',
+        hint: 'Routes work to other skills based on conditions. The "meta-skill" pattern from the Anthropic agent skills video.',
+        emoji: '🎯',
+        defaultDescription: 'Route incoming work through a sequence of decisions. For each item, pick the right downstream skill based on the conditions in the body.',
+        suggestedTools: ['Agent', 'Read'],
+        body: `# {{TITLE}}
+
+This skill is an **orchestrator** — it doesn't do the work itself, it routes work to other skills based on conditions.
+
+## Procedure
+
+1. **Gather inputs.** State what you need to know to make routing decisions (e.g., query a data source, read state, check a flag).
+
+2. **For each item, decide the path:**
+   - If <condition A> → invoke the **<skill-name-a>** skill with \`{key: value}\`
+   - If <condition B> → invoke the **<skill-name-b>** skill with \`{key: value}\`
+   - Otherwise → log to the daily note as "no match"
+
+3. **Summarize.** Send a short Discord summary: how many items, which skills fired, any errors.
+
+## Sub-skills referenced
+
+- \`<skill-name-a>\` — describe what it does
+- \`<skill-name-b>\` — describe what it does
+
+## Tips for writing orchestrators
+
+- Keep the routing logic in this body. Sub-skills should be pure functions that don't know they're being called from here.
+- Pin every sub-skill to the same scheduled task so their bodies are loaded into context together.
+- The Agent tool is what dispatches sub-skills — keep it in your tools.allow.
+`,
+    },
+    {
+        id: 'scraper',
+        label: 'Scraper / Poller',
+        hint: 'Read an external source, surface what is new since the last run.',
+        emoji: '🔍',
+        defaultDescription: 'Poll an external source on a schedule and surface what is new since the last run. Tracks state via the cron progress mechanism so it does not re-process old items.',
+        suggestedTools: ['Read', 'WebFetch', 'cron_progress_read', 'cron_progress_write'],
+        body: `# {{TITLE}}
+
+Read an external data source on a schedule, surface only what's changed since the last run.
+
+## Procedure
+
+1. **Read state.** \`cron_progress_read\` to get \`{processed_ids: [...]}\` (default \`[]\`).
+
+2. **Query the source.** Describe exactly what you fetch (URL, MCP tool call, file path).
+
+3. **Filter to new items.** Compare each item's id against \`processed_ids\`. Skip ones already seen.
+
+4. **For each new item:**
+   - <do the thing>
+
+5. **Persist state.** \`cron_progress_write({processed_ids: [...]})\` with the union of old + new ids.
+
+6. **Output.** If nothing was new, output \`__NOTHING__\`. Otherwise summarize what was processed.
+
+## Inputs
+
+- (declare any \`clementine.inputs\` parameters here so the agent reads them as inputs)
+`,
+        bundledFiles: [
+            {
+                relPath: 'references/state-shape.md',
+                content: `# State shape\\n\\nThis skill reads/writes its state via \`cron_progress_*\`. Document the shape here so future-you remembers what each key means.\\n\\n\\\`\\\`\\\`json\\n{\\n  "processed_ids": ["id1", "id2"],\\n  "last_run_summary": "..."\\n}\\n\\\`\\\`\\\`\\n`,
+            },
+        ],
+    },
+    {
+        id: 'transformer',
+        label: 'Transformer',
+        hint: 'Take input → produce output. Pure function, no side effects.',
+        emoji: '⚙',
+        defaultDescription: 'Pure transformation: receives input, produces output. No external side effects. Useful as a sub-skill called by an orchestrator.',
+        suggestedTools: ['Read', 'Write'],
+        body: `# {{TITLE}}
+
+Transform input into output. No side effects — safe to call from any context.
+
+## Inputs
+
+Declare in \`clementine.inputs\`:
+
+\\\`\\\`\\\`yaml
+clementine:
+  inputs:
+    source_text:
+      type: string
+      description: The raw text to transform
+      required: true
+    style:
+      type: string
+      enum: [casual, formal, urgent]
+      default: casual
+\\\`\\\`\\\`
+
+## Procedure
+
+1. **Read inputs.** All inputs are interpolated as \`{{ input_name }}\`.
+
+2. **Transform.** Describe the transformation step by step.
+
+3. **Output.** Return the transformed text only — no commentary, no narration.
+
+## Output shape
+
+\\\`\\\`\\\`
+<one-line summary>
+
+<transformed body>
+\\\`\\\`\\\`
+`,
+    },
+    {
+        id: 'notifier',
+        label: 'Notifier',
+        hint: 'Send a message somewhere when a condition fires.',
+        emoji: '📣',
+        defaultDescription: 'Send a message to Discord/Slack/email/SMS when a condition is met. Composes well with a Scraper that detects "something changed."',
+        suggestedTools: ['Read', 'discord_channel_send', 'slack_post_message'],
+        body: `# {{TITLE}}
+
+Notify a destination when a condition fires.
+
+## Procedure
+
+1. **Check the condition.** Describe what triggers the notification (e.g., new audit row, daily digest ready, alert threshold crossed).
+
+2. **Build the message.** Keep it short. Include:
+   - What happened
+   - Why it matters (one line)
+   - Action the recipient should take, if any
+
+3. **Send via the right channel:**
+   - Use \`discord_channel_send\` for the team / yourself
+   - Use \`slack_post_message\` if the recipient prefers Slack
+   - Use \`mcp__gmail__send\` for external recipients
+
+4. **Confirm delivery.** Output a one-liner like "Sent to #ops-alerts at 09:14."
+
+## Inputs
+
+\\\`\\\`\\\`yaml
+clementine:
+  inputs:
+    destination:
+      type: string
+      enum: [discord-ops, slack-team, email-owner]
+      default: discord-ops
+    severity:
+      type: string
+      enum: [info, warning, urgent]
+      default: info
+\\\`\\\`\\\`
+`,
+    },
+    {
+        id: 'conversational',
+        label: 'Conversational',
+        hint: 'Multi-turn interactive agent for one specific workflow.',
+        emoji: '💬',
+        defaultDescription: 'Multi-turn conversational agent for a specific workflow (e.g., onboarding a new client, debugging a system). Maintains a focused context across the conversation.',
+        suggestedTools: ['Read', 'memory_read', 'memory_write', 'note_create'],
+        body: `# {{TITLE}}
+
+Run a focused multi-turn conversation. The user comes to you with a specific goal; you guide them step by step until it's done.
+
+## Procedure
+
+1. **Open with intent confirmation.** "Sounds like you want to do X. Is that right?" Don't start tools until they confirm.
+
+2. **Gather what you need.** Ask one question at a time, not a wall.
+
+3. **Use tools sparingly.** Each tool call should be obvious and explainable in the next turn.
+
+4. **Save what you learn.** Use \`memory_write\` for facts that should persist beyond this conversation.
+
+5. **Close cleanly.** When done, summarize what was accomplished + any next steps for the user.
+
+## Conversation principles
+
+- Match the user's tone (casual / formal / urgent — read their first message)
+- Never start a multi-step process without checking in first
+- If the user changes direction mid-conversation, acknowledge + pivot — don't pretend they asked for what you started
+`,
+    },
+];
+/** Lookup by id. */
+export function getSkillTemplate(id) {
+    return SKILL_TEMPLATES.find((t) => t.id === id) ?? null;
+}
+/** Apply a template to a skill name — substitutes \`{{TITLE}}\` placeholders
+ *  in the body with the user's display title. */
+export function renderTemplateBody(template, displayTitle) {
+    return template.body.replace(/\{\{TITLE\}\}/g, displayTitle);
+}
+//# sourceMappingURL=skill-templates.js.map

package/dist/cli/cron.js

@@ -62,6 +62,36 @@ export async function cmdCronRun(jobName) {
     process.env.CLEMENTINE_HOME = BASE_DIR;
     const jobs = parseCronJobs();
     let job = jobs.find((j) => j.name === jobName);
+    // 1.18.129 — Run-now fallback for skills that aren't on a schedule.
+    // The dashboard's "Run now" button on a skill detail pane calls this
+    // endpoint with the skill name. If the skill has no registry entry,
+    // synthesize a transient CronJobDefinition so the runtime can fire
+    // it once. The skill body becomes the prompt via buildSkillContext,
+    // same as scheduled-skill jobs.
+    if (!job) {
+        try {
+            const { getSkill } = await import('../agent/skill-store.js');
+            const skill = getSkill(jobName);
+            if (skill) {
+                const ext = (skill.frontmatter.clementine ?? {});
+                job = {
+                    name: skill.frontmatter.name,
+                    schedule: '0 0 1 1 *', // dummy — never auto-fires; run-now bypasses scheduling
+                    prompt: '', // buildSkillContext injects the skill body
+                    tier: 1,
+                    enabled: true,
+                    skills: [skill.frontmatter.name],
+                    agentSlug: ext.agentSlug ?? undefined,
+                    predictable: true,
+                    source: 'scheduled-skill',
+                };
+                console.log(`(running skill "${jobName}" on demand — not yet scheduled)`);
+            }
+        }
+        catch {
+            // Fall through to error
+        }
+    }
     if (!job) {
         console.error(`Job not found: ${jobName}`);
         console.error(`Available jobs: ${jobs.map((j) => j.name).join(', ') || '(none)'}`);