clementine-agent 1.2.2 → 1.3.0

package/dist/dashboard/builder/serializer.js

@@ -0,0 +1,547 @@
+/**
+ * Builder serializer.
+ *
+ * Two responsibilities:
+ *
+ * 1. Unified read/write of crons + workflows as WorkflowDefinition objects
+ *    so the visual canvas can edit both with one shape. CRON.md entries
+ *    round-trip as virtual single-step workflows; multi-step workflow
+ *    files round-trip via the existing workflow-runner format.
+ *
+ * 2. Convert WorkflowDefinition ⇄ Drawflow's canvas data shape so the
+ *    frontend can drop the JSON straight into drawflow.import().
+ *
+ * Backwards-compatible: existing CRON.md and workflow files are unchanged
+ * unless edited through this module, and edits preserve unrelated fields.
+ */
+import { existsSync, readFileSync, readdirSync, writeFileSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+import matter from 'gray-matter';
+import yaml from 'js-yaml';
+import { CRON_FILE, WORKFLOWS_DIR } from '../../config.js';
+import { snapshotWorkflow } from './snapshots.js';
+// ── ID scheme ───────────────────────────────────────────────────────
+const CRON_ID_PREFIX = 'cron:';
+const WORKFLOW_ID_PREFIX = 'workflow:';
+export function cronId(name) {
+    return CRON_ID_PREFIX + name;
+}
+export function workflowId(filename) {
+    const base = filename.endsWith('.md') ? filename.slice(0, -3) : filename;
+    return WORKFLOW_ID_PREFIX + base;
+}
+export function parseBuilderId(id) {
+    if (id.startsWith(CRON_ID_PREFIX))
+        return { origin: 'cron', key: id.slice(CRON_ID_PREFIX.length) };
+    if (id.startsWith(WORKFLOW_ID_PREFIX))
+        return { origin: 'workflow', key: id.slice(WORKFLOW_ID_PREFIX.length) };
+    return null;
+}
+// ── List ────────────────────────────────────────────────────────────
+export function listAllForBuilder() {
+    const out = [];
+    // Crons from CRON.md
+    for (const job of readCronJobs()) {
+        out.push({
+            id: cronId(job.name),
+            origin: 'cron',
+            name: job.name,
+            description: '',
+            enabled: job.enabled,
+            schedule: job.schedule,
+            stepCount: 1,
+            sourceFile: CRON_FILE,
+            agentSlug: job.agentSlug,
+        });
+    }
+    // Workflows from workflows dir
+    if (existsSync(WORKFLOWS_DIR)) {
+        for (const file of readdirSync(WORKFLOWS_DIR).filter(f => f.endsWith('.md'))) {
+            try {
+                const wf = parseWorkflowFile(path.join(WORKFLOWS_DIR, file));
+                out.push({
+                    id: workflowId(file),
+                    origin: 'workflow',
+                    name: wf.name,
+                    description: wf.description,
+                    enabled: wf.enabled,
+                    schedule: wf.trigger.schedule,
+                    stepCount: wf.steps.length,
+                    sourceFile: wf.sourceFile,
+                    agentSlug: wf.agentSlug,
+                });
+            }
+            catch {
+                // Skip unparseable workflow files
+            }
+        }
+    }
+    return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+// ── Read ────────────────────────────────────────────────────────────
+export function readWorkflow(id) {
+    const parsed = parseBuilderId(id);
+    if (!parsed)
+        return null;
+    if (parsed.origin === 'cron') {
+        const job = readCronJobs().find(j => j.name === parsed.key);
+        if (!job)
+            return null;
+        return cronJobToWorkflow(job);
+    }
+    const file = path.join(WORKFLOWS_DIR, parsed.key + '.md');
+    if (!existsSync(file))
+        return null;
+    try {
+        return parseWorkflowFile(file);
+    }
+    catch {
+        return null;
+    }
+}
+function readCronJobs() {
+    if (!existsSync(CRON_FILE))
+        return [];
+    const raw = readFileSync(CRON_FILE, 'utf-8');
+    let parsed;
+    try {
+        parsed = matter(raw);
+    }
+    catch {
+        return [];
+    }
+    const jobDefs = (parsed.data.jobs ?? []);
+    const jobs = [];
+    for (const job of jobDefs) {
+        const name = String(job.name ?? '');
+        const schedule = String(job.schedule ?? '');
+        const prompt = String(job.prompt ?? '');
+        if (!name || !schedule || !prompt)
+            continue;
+        jobs.push({
+            name,
+            schedule,
+            prompt,
+            enabled: job.enabled !== false,
+            tier: Number(job.tier ?? 1),
+            maxTurns: job.max_turns != null ? Number(job.max_turns) : undefined,
+            model: job.model != null ? String(job.model) : undefined,
+            workDir: job.work_dir != null ? String(job.work_dir) : undefined,
+            mode: job.mode === 'unleashed' ? 'unleashed' : 'standard',
+            maxHours: job.max_hours != null ? Number(job.max_hours) : undefined,
+            maxRetries: job.max_retries != null ? Number(job.max_retries) : undefined,
+            after: job.after != null ? String(job.after) : undefined,
+            successCriteria: Array.isArray(job.success_criteria)
+                ? job.success_criteria.map(c => String(c))
+                : undefined,
+            alwaysDeliver: job.always_deliver === true ? true : undefined,
+            context: job.context != null ? String(job.context) : undefined,
+            preCheck: job.pre_check != null ? String(job.pre_check) : undefined,
+            agentSlug: typeof job.agentSlug === 'string'
+                ? job.agentSlug
+                : typeof job.agent_slug === 'string'
+                    ? job.agent_slug
+                    : undefined,
+        });
+    }
+    return jobs;
+}
+function parseWorkflowFile(filePath) {
+    const raw = readFileSync(filePath, 'utf-8');
+    const parsed = matter(raw);
+    const data = parsed.data;
+    if (data.type !== 'workflow') {
+        throw new Error(`Not a workflow file (type=${String(data.type)}): ${filePath}`);
+    }
+    const name = String(data.name ?? path.basename(filePath, '.md'));
+    const description = String(data.description ?? '');
+    const enabled = data.enabled !== false;
+    const triggerRaw = (data.trigger ?? {});
+    const trigger = {
+        schedule: triggerRaw.schedule ? String(triggerRaw.schedule) : undefined,
+        manual: triggerRaw.manual !== false,
+    };
+    const inputs = {};
+    if (data.inputs && typeof data.inputs === 'object') {
+        for (const [key, val] of Object.entries(data.inputs)) {
+            const v = val;
+            inputs[key] = {
+                type: (v.type === 'number' ? 'number' : 'string'),
+                default: v.default != null ? String(v.default) : undefined,
+                description: v.description ? String(v.description) : undefined,
+            };
+        }
+    }
+    const stepsRaw = (data.steps ?? []);
+    const steps = stepsRaw.map((s, i) => {
+        const step = {
+            id: String(s.id ?? `step-${i + 1}`),
+            prompt: String(s.prompt ?? ''),
+            dependsOn: Array.isArray(s.dependsOn) ? s.dependsOn.map(String) : [],
+            tier: Number(s.tier ?? 1),
+            maxTurns: Number(s.maxTurns ?? 15),
+            model: s.model != null ? String(s.model) : undefined,
+            workDir: s.workDir != null ? String(s.workDir) : undefined,
+        };
+        const kind = s.kind;
+        if (kind && kind !== 'prompt')
+            step.kind = kind;
+        if (s.mcp && typeof s.mcp === 'object')
+            step.mcp = s.mcp;
+        if (s.channel && typeof s.channel === 'object')
+            step.channel = s.channel;
+        if (s.transform && typeof s.transform === 'object')
+            step.transform = s.transform;
+        if (s.conditional && typeof s.conditional === 'object')
+            step.conditional = s.conditional;
+        if (s.loop && typeof s.loop === 'object')
+            step.loop = s.loop;
+        if (s.canvas && typeof s.canvas === 'object') {
+            const c = s.canvas;
+            if (typeof c.x === 'number' && typeof c.y === 'number')
+                step.canvas = { x: c.x, y: c.y };
+        }
+        return step;
+    });
+    const synthesis = data.synthesis?.prompt
+        ? { prompt: String(data.synthesis.prompt) }
+        : undefined;
+    return {
+        name,
+        description,
+        enabled,
+        trigger,
+        inputs,
+        steps,
+        synthesis,
+        sourceFile: filePath,
+        agentSlug: typeof data.agentSlug === 'string' ? data.agentSlug : undefined,
+    };
+}
+// ── Cron ⇄ Workflow ─────────────────────────────────────────────────
+export function cronJobToWorkflow(job) {
+    const step = {
+        id: 'main',
+        prompt: job.prompt,
+        dependsOn: [],
+        tier: job.tier,
+        maxTurns: job.maxTurns ?? 15,
+        model: job.model,
+        workDir: job.workDir,
+        kind: 'prompt',
+    };
+    return {
+        name: job.name,
+        description: '',
+        enabled: job.enabled,
+        trigger: { schedule: job.schedule, manual: false },
+        inputs: {},
+        steps: [step],
+        sourceFile: CRON_FILE,
+        agentSlug: job.agentSlug,
+    };
+}
+/** True if a workflow is shaped like a CRON.md entry (single prompt step + cron schedule). */
+export function isCronShape(wf) {
+    return (wf.steps.length === 1 &&
+        (wf.steps[0].kind ?? 'prompt') === 'prompt' &&
+        !!wf.trigger.schedule);
+}
+// ── Save ────────────────────────────────────────────────────────────
+export function saveWorkflow(id, wf) {
+    const parsed = parseBuilderId(id);
+    if (!parsed)
+        return { ok: false, error: 'Unknown builder id: ' + id };
+    // Snapshot the current state of the source file before overwriting.
+    // Best-effort — failures here never block the save.
+    const sourceBefore = sourceFileForId(id, parsed);
+    if (sourceBefore) {
+        try {
+            snapshotWorkflow(id, sourceBefore);
+        }
+        catch { /* */ }
+    }
+    if (parsed.origin === 'cron') {
+        if (!isCronShape(wf)) {
+            return { ok: false, error: 'Cron entry must remain a single prompt step with a cron schedule' };
+        }
+        return saveCronEntry(parsed.key, wf);
+    }
+    return saveWorkflowFile(parsed.key, wf);
+}
+/** Resolve the on-disk file path for a builder id (cron entries all share CRON_FILE). */
+export function sourceFileForId(id, parsedHint) {
+    const parsed = parsedHint ?? parseBuilderId(id);
+    if (!parsed)
+        return null;
+    if (parsed.origin === 'cron')
+        return CRON_FILE;
+    return path.join(WORKFLOWS_DIR, parsed.key + '.md');
+}
+function saveCronEntry(originalName, wf) {
+    if (!existsSync(CRON_FILE))
+        return { ok: false, error: 'CRON.md does not exist' };
+    const raw = readFileSync(CRON_FILE, 'utf-8');
+    let parsed;
+    try {
+        parsed = matter(raw);
+    }
+    catch (err) {
+        return { ok: false, error: 'CRON.md YAML parse error: ' + err.message };
+    }
+    const jobs = Array.isArray(parsed.data.jobs) ? [...parsed.data.jobs] : [];
+    const idx = jobs.findIndex(j => String(j.name ?? '') === originalName);
+    if (idx === -1)
+        return { ok: false, error: 'Cron entry not found: ' + originalName };
+    const step = wf.steps[0];
+    const prev = jobs[idx];
+    const updated = {
+        ...prev,
+        name: wf.name,
+        schedule: wf.trigger.schedule,
+        prompt: step.prompt,
+        enabled: wf.enabled,
+        tier: step.tier,
+    };
+    if (step.maxTurns != null)
+        updated.max_turns = step.maxTurns;
+    if (step.model != null)
+        updated.model = step.model;
+    if (step.workDir != null)
+        updated.work_dir = step.workDir;
+    if (wf.agentSlug)
+        updated.agentSlug = wf.agentSlug;
+    jobs[idx] = updated;
+    parsed.data.jobs = jobs;
+    const out = matter.stringify(parsed.content ?? '', parsed.data);
+    writeFileSync(CRON_FILE, out, 'utf-8');
+    return { ok: true };
+}
+function saveWorkflowFile(key, wf) {
+    if (!existsSync(WORKFLOWS_DIR))
+        mkdirSync(WORKFLOWS_DIR, { recursive: true });
+    const file = path.join(WORKFLOWS_DIR, key + '.md');
+    // Preserve body content if the file exists; otherwise empty body.
+    let body = '';
+    if (existsSync(file)) {
+        try {
+            const existing = matter(readFileSync(file, 'utf-8'));
+            body = existing.content ?? '';
+        }
+        catch {
+            body = '';
+        }
+    }
+    const data = {
+        type: 'workflow',
+        name: wf.name,
+        description: wf.description,
+        enabled: wf.enabled,
+        trigger: wf.trigger,
+    };
+    if (wf.agentSlug)
+        data.agentSlug = wf.agentSlug;
+    if (Object.keys(wf.inputs).length > 0)
+        data.inputs = wf.inputs;
+    data.steps = wf.steps.map(serializeStep);
+    if (wf.synthesis)
+        data.synthesis = wf.synthesis;
+    const out = matter.stringify(body, data);
+    writeFileSync(file, out, 'utf-8');
+    return { ok: true };
+}
+function serializeStep(step) {
+    const out = {
+        id: step.id,
+        prompt: step.prompt,
+        dependsOn: step.dependsOn,
+        tier: step.tier,
+        maxTurns: step.maxTurns,
+    };
+    if (step.model)
+        out.model = step.model;
+    if (step.workDir)
+        out.workDir = step.workDir;
+    const kind = step.kind ?? 'prompt';
+    if (kind !== 'prompt')
+        out.kind = kind;
+    if (step.mcp)
+        out.mcp = step.mcp;
+    if (step.channel)
+        out.channel = step.channel;
+    if (step.transform)
+        out.transform = step.transform;
+    if (step.conditional)
+        out.conditional = step.conditional;
+    if (step.loop)
+        out.loop = step.loop;
+    if (step.canvas)
+        out.canvas = step.canvas;
+    return out;
+}
+const COL_WIDTH = 260;
+const ROW_HEIGHT = 140;
+export function workflowToDrawflow(wf) {
+    // Wave-based default layout: x = wave * COL_WIDTH, y = position-in-wave * ROW_HEIGHT.
+    const waveOf = computeWaves(wf.steps);
+    const perWave = {};
+    const stepIdToNumeric = {};
+    wf.steps.forEach((s, i) => { stepIdToNumeric[s.id] = i + 1; });
+    const data = {};
+    for (let i = 0; i < wf.steps.length; i++) {
+        const step = wf.steps[i];
+        const numericId = i + 1;
+        const wave = waveOf[step.id] ?? 0;
+        const idxInWave = perWave[wave] ?? 0;
+        perWave[wave] = idxInWave + 1;
+        const x = step.canvas?.x ?? wave * COL_WIDTH + 50;
+        const y = step.canvas?.y ?? idxInWave * ROW_HEIGHT + 50;
+        const inputConnections = step.dependsOn.map(depId => ({
+            node: String(stepIdToNumeric[depId] ?? ''),
+            input: 'output_1',
+        })).filter(c => c.node);
+        data[String(numericId)] = {
+            id: numericId,
+            name: nodeNameForKind(step.kind ?? 'prompt'),
+            data: stepToNodeData(step),
+            class: 'cl-node cl-node-' + (step.kind ?? 'prompt'),
+            html: '',
+            typenode: false,
+            inputs: { input_1: { connections: inputConnections } },
+            outputs: { output_1: { connections: [] } },
+            pos_x: x,
+            pos_y: y,
+        };
+    }
+    // Fill in output connections from input connections (Drawflow needs both directions).
+    for (const [nodeIdStr, node] of Object.entries(data)) {
+        for (const conn of node.inputs.input_1.connections) {
+            const src = data[conn.node];
+            if (src) {
+                src.outputs.output_1.connections.push({ node: nodeIdStr, output: 'input_1' });
+            }
+        }
+    }
+    return { drawflow: { Home: { data } } };
+}
+export function drawflowToWorkflow(exportData, base) {
+    const nodes = exportData?.drawflow?.Home?.data ?? {};
+    const numericToStepId = {};
+    const orderedNumericIds = Object.keys(nodes).sort((a, b) => Number(a) - Number(b));
+    // Read step ids back out of node.data; fall back to step-N if missing.
+    for (const nid of orderedNumericIds) {
+        const stepData = (nodes[nid].data ?? {});
+        numericToStepId[nid] = stepData.stepId || `step-${nid}`;
+    }
+    const baseById = new Map(base.steps.map(s => [s.id, s]));
+    const steps = orderedNumericIds.map(nid => {
+        const node = nodes[nid];
+        const data = node.data;
+        const stepId = numericToStepId[nid];
+        const baseStep = baseById.get(stepId);
+        const dependsOn = node.inputs.input_1.connections
+            .map(c => numericToStepId[c.node])
+            .filter((s) => !!s);
+        const next = {
+            id: stepId,
+            prompt: typeof data.prompt === 'string' ? data.prompt : (baseStep?.prompt ?? ''),
+            dependsOn,
+            tier: typeof data.tier === 'number' ? data.tier : (baseStep?.tier ?? 1),
+            maxTurns: typeof data.maxTurns === 'number' ? data.maxTurns : (baseStep?.maxTurns ?? 15),
+            model: typeof data.model === 'string' ? data.model : baseStep?.model,
+            workDir: typeof data.workDir === 'string' ? data.workDir : baseStep?.workDir,
+            kind: data.kind ?? baseStep?.kind,
+            mcp: data.mcp ?? baseStep?.mcp,
+            channel: data.channel ?? baseStep?.channel,
+            transform: data.transform ?? baseStep?.transform,
+            conditional: data.conditional ?? baseStep?.conditional,
+            loop: data.loop ?? baseStep?.loop,
+            canvas: { x: node.pos_x, y: node.pos_y },
+        };
+        return next;
+    });
+    return { ...base, steps };
+}
+function nodeNameForKind(kind) {
+    switch (kind) {
+        case 'mcp': return 'MCP Tool';
+        case 'channel': return 'Channel';
+        case 'transform': return 'Transform';
+        case 'conditional': return 'Conditional';
+        case 'loop': return 'Loop';
+        default: return 'Prompt';
+    }
+}
+function stepToNodeData(step) {
+    const data = {
+        stepId: step.id,
+        prompt: step.prompt,
+        tier: step.tier,
+        maxTurns: step.maxTurns,
+        kind: step.kind ?? 'prompt',
+    };
+    if (step.model)
+        data.model = step.model;
+    if (step.workDir)
+        data.workDir = step.workDir;
+    if (step.mcp)
+        data.mcp = step.mcp;
+    if (step.channel)
+        data.channel = step.channel;
+    if (step.transform)
+        data.transform = step.transform;
+    if (step.conditional)
+        data.conditional = step.conditional;
+    if (step.loop)
+        data.loop = step.loop;
+    return data;
+}
+/** Topological wave numbers (0 = no deps, 1 = depends only on wave 0, ...). */
+function computeWaves(steps) {
+    const wave = {};
+    const ids = new Set(steps.map(s => s.id));
+    const remaining = new Set(steps.map(s => s.id));
+    let current = 0;
+    // Cap iterations to avoid infinite loops on cyclic/malformed graphs.
+    const maxIter = steps.length + 1;
+    for (let iter = 0; iter < maxIter && remaining.size > 0; iter++) {
+        const ready = [];
+        for (const s of steps) {
+            if (!remaining.has(s.id))
+                continue;
+            const depsResolved = s.dependsOn.every(d => !ids.has(d) || (wave[d] != null && wave[d] < current + 1));
+            if (depsResolved)
+                ready.push(s.id);
+        }
+        if (ready.length === 0) {
+            // Break cycles: assign remaining to current wave.
+            for (const id of remaining)
+                wave[id] = current;
+            break;
+        }
+        for (const id of ready) {
+            wave[id] = current;
+            remaining.delete(id);
+        }
+        current++;
+    }
+    return wave;
+}
+// ── YAML helper for tests / debug ───────────────────────────────────
+/** Stringify a workflow's frontmatter for visual inspection. */
+export function workflowFrontmatterString(wf) {
+    const data = {
+        type: 'workflow',
+        name: wf.name,
+        description: wf.description,
+        enabled: wf.enabled,
+        trigger: wf.trigger,
+        steps: wf.steps.map(serializeStep),
+    };
+    if (wf.synthesis)
+        data.synthesis = wf.synthesis;
+    if (wf.agentSlug)
+        data.agentSlug = wf.agentSlug;
+    return yaml.dump(data);
+}
+//# sourceMappingURL=serializer.js.map

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

@@ -0,0 +1,32 @@
+/**
+ * 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).
+ */
+export interface SnapshotEntry {
+    id: string;
+    filename: string;
+    ts: string;
+    size: number;
+    preview: string;
+}
+/**
+ * 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 declare function snapshotWorkflow(id: string, sourceFile: string): SnapshotEntry | null;
+/** List snapshots for a builder id, newest first. */
+export declare function listSnapshots(id: string): SnapshotEntry[];
+/** Restore a snapshot by filename. Writes the snapshot's contents back into sourceFile. */
+export declare function restoreSnapshot(id: string, snapshotFilename: string, sourceFile: string): {
+    ok: boolean;
+    error?: string;
+};
+//# sourceMappingURL=snapshots.d.ts.map