clementine-agent 1.2.3 → 1.3.0

package/dist/dashboard/builder/snapshots.js

@@ -0,0 +1,138 @@
+/**
+ * Builder snapshot history — file-based undo for workflow saves.
+ *
+ * Every successful save writes a copy of the source file to:
+ *   ~/.clementine/snapshots/builder/<origin>/<key>/<timestamp>.md
+ *
+ * Bounded: keep at most MAX_PER_WORKFLOW snapshots per workflow id.
+ * Older snapshots are pruned on each save.
+ *
+ * No git dependency, no user-facing CLI — agent invokes via MCP tools
+ * (workflow_history / workflow_restore).
+ */
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { parseBuilderId } from './serializer.js';
+function snapRoot() {
+    return path.join(process.env.CLEMENTINE_HOME || path.join(os.homedir(), '.clementine'), 'snapshots', 'builder');
+}
+const MAX_PER_WORKFLOW = 20;
+let _snapshotCounter = 0;
+function nextSnapshotFilename() {
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    const seq = (++_snapshotCounter).toString(36).padStart(3, '0');
+    return `${ts}-${seq}.md`;
+}
+function snapshotDirFor(id) {
+    const parsed = parseBuilderId(id);
+    if (!parsed)
+        return null;
+    return path.join(snapRoot(), parsed.origin, sanitizeKey(parsed.key));
+}
+function sanitizeKey(key) {
+    return key.replace(/[^a-z0-9._-]/gi, '_').slice(0, 120);
+}
+/**
+ * Write a snapshot of the current state of a workflow's source file.
+ * Best-effort — failures are logged but never block the underlying save.
+ */
+export function snapshotWorkflow(id, sourceFile) {
+    if (!sourceFile || !existsSync(sourceFile))
+        return null;
+    const dir = snapshotDirFor(id);
+    if (!dir)
+        return null;
+    try {
+        mkdirSync(dir, { recursive: true });
+        const filename = nextSnapshotFilename();
+        const dst = path.join(dir, filename);
+        copyFileSync(sourceFile, dst);
+        pruneOldSnapshots(dir);
+        return entryFromFile(id, dir, filename);
+    }
+    catch {
+        return null;
+    }
+}
+/** List snapshots for a builder id, newest first. */
+export function listSnapshots(id) {
+    const dir = snapshotDirFor(id);
+    if (!dir || !existsSync(dir))
+        return [];
+    try {
+        const files = readdirSync(dir).filter(f => f.endsWith('.md'));
+        return files
+            .map(f => entryFromFile(id, dir, f))
+            .filter((e) => e != null)
+            .sort((a, b) => b.ts.localeCompare(a.ts));
+    }
+    catch {
+        return [];
+    }
+}
+/** Restore a snapshot by filename. Writes the snapshot's contents back into sourceFile. */
+export function restoreSnapshot(id, snapshotFilename, sourceFile) {
+    const dir = snapshotDirFor(id);
+    if (!dir)
+        return { ok: false, error: 'unknown id' };
+    const safe = path.basename(snapshotFilename);
+    const src = path.join(dir, safe);
+    if (!existsSync(src))
+        return { ok: false, error: 'snapshot not found' };
+    if (!sourceFile)
+        return { ok: false, error: 'missing sourceFile' };
+    try {
+        // Snapshot the *current* contents first so the restore itself is reversible.
+        snapshotWorkflow(id, sourceFile);
+        const content = readFileSync(src, 'utf-8');
+        writeFileSync(sourceFile, content, 'utf-8');
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, error: err.message };
+    }
+}
+function pruneOldSnapshots(dir) {
+    let files;
+    try {
+        files = readdirSync(dir).filter(f => f.endsWith('.md'));
+    }
+    catch {
+        return;
+    }
+    if (files.length <= MAX_PER_WORKFLOW)
+        return;
+    const sorted = files.sort(); // ISO timestamps sort naturally
+    const overflow = sorted.length - MAX_PER_WORKFLOW;
+    for (let i = 0; i < overflow; i++) {
+        try {
+            unlinkSync(path.join(dir, sorted[i]));
+        }
+        catch { /* */ }
+    }
+}
+function entryFromFile(id, dir, filename) {
+    try {
+        const full = path.join(dir, filename);
+        const stat = statSync(full);
+        const ts = filename.replace(/\.md$/, '').replace(/-/g, ':').replace(/^(\d{4}):(\d{2}):(\d{2})T/, '$1-$2-$3T').replace(/T(\d{2}):(\d{2}):(\d{2}):(\d{3})Z?$/, 'T$1:$2:$3.$4Z');
+        let preview = '';
+        try {
+            const head = readFileSync(full, 'utf-8').slice(0, 240);
+            preview = head.replace(/\n/g, ' ').slice(0, 120);
+        }
+        catch { /* */ }
+        return {
+            id,
+            filename,
+            ts,
+            size: stat.size,
+            preview,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=snapshots.js.map

package/dist/dashboard/builder/validation.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Builder workflow validation.
+ *
+ * Static, side-effect-free checks. Used both by `workflow_validate` (agent
+ * runs it explicitly) and by save handlers (refuse to persist invalid
+ * graphs). Errors block save; warnings are surfaced for the agent and UI
+ * but don't prevent persistence (e.g., disabled cron with no schedule —
+ * legal but probably wrong).
+ */
+import type { WorkflowDefinition } from '../../types.js';
+export type ValidationSeverity = 'error' | 'warning';
+export interface ValidationIssue {
+    severity: ValidationSeverity;
+    code: string;
+    stepId?: string;
+    field?: string;
+    message: string;
+}
+export interface ValidationResult {
+    ok: boolean;
+    issues: ValidationIssue[];
+}
+export declare function validateWorkflow(wf: WorkflowDefinition): ValidationResult;
+/** Lightweight cron expression validation. Accepts standard 5-field cron and common ranges/lists/steps. */
+export declare function isCronExpression(expr: string): boolean;
+//# sourceMappingURL=validation.d.ts.map

package/dist/dashboard/builder/validation.js

@@ -0,0 +1,183 @@
+/**
+ * Builder workflow validation.
+ *
+ * Static, side-effect-free checks. Used both by `workflow_validate` (agent
+ * runs it explicitly) and by save handlers (refuse to persist invalid
+ * graphs). Errors block save; warnings are surfaced for the agent and UI
+ * but don't prevent persistence (e.g., disabled cron with no schedule —
+ * legal but probably wrong).
+ */
+export function validateWorkflow(wf) {
+    const issues = [];
+    // ── Workflow-level ──
+    if (!wf.name || !wf.name.trim()) {
+        issues.push({ severity: 'error', code: 'name-empty', message: 'Workflow has no name' });
+    }
+    if (wf.steps.length === 0) {
+        issues.push({ severity: 'error', code: 'no-steps', message: 'Workflow has no steps' });
+    }
+    if (wf.trigger.schedule && !isCronExpression(wf.trigger.schedule)) {
+        issues.push({
+            severity: 'error', code: 'bad-schedule',
+            field: 'trigger.schedule',
+            message: `Invalid cron expression: "${wf.trigger.schedule}"`,
+        });
+    }
+    if (wf.enabled && !wf.trigger.schedule && !wf.trigger.manual) {
+        issues.push({
+            severity: 'warning', code: 'enabled-no-trigger',
+            message: 'Workflow is enabled but has neither a cron schedule nor a manual trigger',
+        });
+    }
+    // ── Step-level ──
+    const seenIds = new Set();
+    for (const step of wf.steps) {
+        if (seenIds.has(step.id)) {
+            issues.push({
+                severity: 'error', code: 'duplicate-step-id',
+                stepId: step.id,
+                message: `Duplicate step id: "${step.id}"`,
+            });
+        }
+        seenIds.add(step.id);
+        issues.push(...validateStepConfig(step));
+        for (const dep of step.dependsOn) {
+            if (dep === step.id) {
+                issues.push({
+                    severity: 'error', code: 'self-dep',
+                    stepId: step.id,
+                    message: `Step "${step.id}" depends on itself`,
+                });
+            }
+        }
+    }
+    // Missing dep references
+    for (const step of wf.steps) {
+        for (const dep of step.dependsOn) {
+            if (dep !== step.id && !seenIds.has(dep)) {
+                issues.push({
+                    severity: 'error', code: 'missing-dep',
+                    stepId: step.id,
+                    message: `Step "${step.id}" depends on unknown step "${dep}"`,
+                });
+            }
+        }
+    }
+    // Cycle detection (only worthwhile if there are no missing-dep errors)
+    if (!issues.some(i => i.code === 'missing-dep' || i.code === 'self-dep')) {
+        const cycle = findCycle(wf.steps);
+        if (cycle) {
+            issues.push({
+                severity: 'error', code: 'cycle',
+                message: `Cycle detected through steps: ${cycle.join(' → ')}`,
+            });
+        }
+    }
+    return { ok: !issues.some(i => i.severity === 'error'), issues };
+}
+function validateStepConfig(step) {
+    const issues = [];
+    const kind = step.kind ?? 'prompt';
+    switch (kind) {
+        case 'prompt':
+            if (!step.prompt || !step.prompt.trim()) {
+                issues.push({ severity: 'error', code: 'prompt-empty', stepId: step.id, message: `Prompt step "${step.id}" has empty prompt` });
+            }
+            break;
+        case 'mcp':
+            if (!step.mcp) {
+                issues.push({ severity: 'error', code: 'mcp-missing', stepId: step.id, message: `MCP step "${step.id}" has no config` });
+            }
+            else {
+                if (!step.mcp.server)
+                    issues.push({ severity: 'error', code: 'mcp-no-server', stepId: step.id, message: `MCP step "${step.id}" missing server` });
+                if (!step.mcp.tool)
+                    issues.push({ severity: 'error', code: 'mcp-no-tool', stepId: step.id, message: `MCP step "${step.id}" missing tool` });
+            }
+            break;
+        case 'channel':
+            if (!step.channel) {
+                issues.push({ severity: 'error', code: 'channel-missing', stepId: step.id, message: `Channel step "${step.id}" has no config` });
+            }
+            else {
+                if (!step.channel.channel)
+                    issues.push({ severity: 'error', code: 'channel-no-channel', stepId: step.id, message: `Channel step "${step.id}" missing channel` });
+                if (!step.channel.target)
+                    issues.push({ severity: 'error', code: 'channel-no-target', stepId: step.id, message: `Channel step "${step.id}" missing target` });
+                if (!step.channel.content)
+                    issues.push({ severity: 'warning', code: 'channel-no-content', stepId: step.id, message: `Channel step "${step.id}" has empty content` });
+            }
+            break;
+        case 'transform':
+            if (!step.transform || !step.transform.expression) {
+                issues.push({ severity: 'error', code: 'transform-no-expr', stepId: step.id, message: `Transform step "${step.id}" missing expression` });
+            }
+            break;
+        case 'conditional':
+            if (!step.conditional || !step.conditional.condition) {
+                issues.push({ severity: 'error', code: 'conditional-no-cond', stepId: step.id, message: `Conditional step "${step.id}" missing condition` });
+            }
+            break;
+        case 'loop':
+            if (!step.loop || !step.loop.items) {
+                issues.push({ severity: 'error', code: 'loop-no-items', stepId: step.id, message: `Loop step "${step.id}" missing items expression` });
+            }
+            break;
+    }
+    if (typeof step.tier !== 'number' || step.tier < 1 || step.tier > 5) {
+        issues.push({ severity: 'warning', code: 'tier-range', stepId: step.id, field: 'tier', message: `Step "${step.id}" tier out of usual range (1-5): ${step.tier}` });
+    }
+    if (typeof step.maxTurns !== 'number' || step.maxTurns < 1) {
+        issues.push({ severity: 'warning', code: 'max-turns-range', stepId: step.id, field: 'maxTurns', message: `Step "${step.id}" maxTurns invalid: ${step.maxTurns}` });
+    }
+    return issues;
+}
+/** Return the cycle as a list of step ids (first→last→first), or null if acyclic. */
+function findCycle(steps) {
+    const adj = new Map();
+    for (const s of steps)
+        adj.set(s.id, s.dependsOn.slice());
+    const WHITE = 0, GRAY = 1, BLACK = 2;
+    const color = new Map();
+    for (const id of adj.keys())
+        color.set(id, WHITE);
+    const stack = [];
+    function dfs(node) {
+        color.set(node, GRAY);
+        stack.push(node);
+        for (const dep of adj.get(node) ?? []) {
+            const c = color.get(dep);
+            if (c === GRAY) {
+                const cycleStart = stack.indexOf(dep);
+                return [...stack.slice(cycleStart), dep];
+            }
+            if (c === WHITE) {
+                const found = dfs(dep);
+                if (found)
+                    return found;
+            }
+        }
+        stack.pop();
+        color.set(node, BLACK);
+        return null;
+    }
+    for (const id of adj.keys()) {
+        if (color.get(id) === WHITE) {
+            const found = dfs(id);
+            if (found)
+                return found;
+        }
+    }
+    return null;
+}
+const CRON_FIELD = /^(\*|(\d+|\*\/\d+)([,-/](\d+))*)$/;
+/** Lightweight cron expression validation. Accepts standard 5-field cron and common ranges/lists/steps. */
+export function isCronExpression(expr) {
+    if (!expr || typeof expr !== 'string')
+        return false;
+    const fields = expr.trim().split(/\s+/);
+    if (fields.length !== 5)
+        return false;
+    return fields.every(f => CRON_FIELD.test(f) || /^[A-Z*]+$/i.test(f));
+}
+//# sourceMappingURL=validation.js.map

package/dist/gateway/router.js

@@ -1445,9 +1445,38 @@ export class Gateway {
         try {
             logger.info({ workflow: workflow.name, inputs }, 'Running workflow');
             try {
-                const { WorkflowRunner } = await import('../agent/workflow-runner.js');
+                const [{ WorkflowRunner }, { emitBuilderEvent }, { workflowId }] = await Promise.all([
+                    import('../agent/workflow-runner.js'),
+                    import('../dashboard/builder/events.js'),
+                    import('../dashboard/builder/serializer.js'),
+                ]);
                 const runner = new WorkflowRunner(this.assistant);
-                const result = await runner.run(workflow, inputs);
+                // Derive builder id so the dashboard canvas can light up live if it's open.
+                const baseName = workflow.sourceFile
+                    ? workflow.sourceFile.split('/').pop()?.replace(/\.md$/, '') ?? workflow.name
+                    : workflow.name;
+                const builderId = workflowId(baseName);
+                const runId = `sched-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+                emitBuilderEvent({ type: 'run:started', workflowId: builderId, runId, payload: { mode: 'real', stepCount: workflow.steps.length } });
+                const result = await runner.run(workflow, inputs, (updates) => {
+                    for (const u of updates) {
+                        if (u.status === 'waiting')
+                            continue;
+                        const status = u.status === 'done' ? 'done' : u.status === 'failed' ? 'failed' : u.status === 'skipped' ? 'skipped' : 'running';
+                        emitBuilderEvent({
+                            type: 'run:step-status',
+                            workflowId: builderId,
+                            runId,
+                            payload: { stepId: u.stepId, status, durationMs: u.durationMs, mocked: false },
+                        });
+                    }
+                });
+                emitBuilderEvent({
+                    type: 'run:completed',
+                    workflowId: builderId,
+                    runId,
+                    payload: { status: result.status === 'ok' ? 'ok' : 'error', durationMs: result.entry.durationMs },
+                });
                 // Re-baseline integrity checksums after workflow (may write to vault)
                 scanner.refreshIntegrity();
                 return result.output || '*(workflow completed — no output)*';

package/dist/index.js

@@ -694,6 +694,16 @@ async function asyncMain() {
     const heartbeat = new HeartbeatScheduler(gateway, dispatcher);
     const cronScheduler = new CronScheduler(gateway, dispatcher);
     heartbeat.setCronScheduler(cronScheduler);
+    // Builder runner — wire MCP invoke handler so canvas test runs can hit
+    // real read-only MCP tools (gmail.list_unread, github.list_prs, etc.).
+    // Stdio clients are pooled per server with idle teardown.
+    try {
+        const { installBuilderMcpHandler } = await import('./dashboard/builder/mcp-invoke.js');
+        installBuilderMcpHandler();
+    }
+    catch (err) {
+        logger.warn({ err }, 'Builder MCP invoke handler install failed (non-fatal)');
+    }
     // Per-agent heartbeats — one cheap-path observer per registered specialist.
     // LLM tick fires on signal change with the agent's profile and routes
     // output to their Discord channel.
@@ -1019,6 +1029,14 @@ async function asyncMain() {
     catch (err) {
         logger.warn({ err }, 'Memory write queue drain failed');
     }
+    // Tear down builder MCP client pool (best-effort).
+    try {
+        const { shutdownBuilderMcpHandler } = await import('./dashboard/builder/mcp-invoke.js');
+        await shutdownBuilderMcpHandler();
+    }
+    catch (err) {
+        logger.warn({ err }, 'Builder MCP handler shutdown failed (non-fatal)');
+    }
     // Now safe to tear down remaining infrastructure
     heartbeat.stop();
     cronScheduler.stop();

package/dist/tools/builder-tools.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Clementine — Builder MCP tools.
+ *
+ * Agent-facing surface for managing workflows + crons on the visual
+ * canvas. Read, edit, validate, and dry-run. Actual execution lives
+ * separately in the runner (Phase 2+).
+ *
+ * Outputs are terse plain text by default for prompt efficiency; pass
+ * `verbose: true` to get the underlying JSON for debugging.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerBuilderTools(server: McpServer): void;
+//# sourceMappingURL=builder-tools.d.ts.map