@sweny-ai/core 0.1.0

package/dist/executor.js

@@ -0,0 +1,173 @@
+/**
+ * DAG Workflow Executor
+ *
+ * Walks a workflow graph node-by-node. At each node, Claude gets
+ * the node's instruction + available skill tools + context from
+ * prior nodes. Claude does the work, then the executor resolves
+ * which edge to follow next.
+ *
+ * This replaces ~8k lines of engine + recipe step code.
+ */
+import { consoleLogger } from "./types.js";
+/**
+ * Execute a workflow from entry to completion.
+ *
+ * Returns a map of node ID → result for every node that ran.
+ */
+export async function execute(workflow, input, options) {
+    const { skills, claude, observer } = options;
+    const config = resolveConfig(skills, options.config);
+    const logger = options.logger ?? consoleLogger;
+    const results = new Map();
+    validate(workflow, skills);
+    safeObserve(observer, { type: "workflow:start", workflow: workflow.id }, logger);
+    let currentId = workflow.entry;
+    while (currentId) {
+        const node = workflow.nodes[currentId];
+        if (!node)
+            throw new Error(`Unknown node: "${currentId}"`);
+        safeObserve(observer, { type: "node:enter", node: currentId, instruction: node.instruction }, logger);
+        logger.info(`→ ${node.name}`, { node: currentId });
+        // Gather tools from the node's skills
+        const tools = resolveTools(node.skills, skills);
+        // Build context: input + all prior node results
+        const context = {
+            input,
+            ...Object.fromEntries([...results.entries()].map(([k, v]) => [k, v.data])),
+        };
+        // Wrap tool handlers to emit events + inject context
+        const trackedTools = tools.map((t) => ({
+            ...t,
+            handler: async (toolInput) => {
+                safeObserve(observer, { type: "tool:call", node: currentId, tool: t.name, input: toolInput }, logger);
+                const toolCtx = { config, logger };
+                const output = await t.handler(toolInput, toolCtx);
+                safeObserve(observer, { type: "tool:result", node: currentId, tool: t.name, output }, logger);
+                return output;
+            },
+        }));
+        // Run Claude on this node
+        const result = await claude.run({
+            instruction: node.instruction,
+            context,
+            tools: trackedTools,
+            outputSchema: node.output,
+        });
+        results.set(currentId, result);
+        safeObserve(observer, { type: "node:exit", node: currentId, result }, logger);
+        logger.info(`  ✓ ${result.status}`, { node: currentId, toolCalls: result.toolCalls.length });
+        // Resolve next node via edge conditions
+        currentId = await resolveNext(workflow, currentId, results, claude, observer);
+    }
+    safeObserve(observer, {
+        type: "workflow:end",
+        results: Object.fromEntries(results),
+    }, logger);
+    return results;
+}
+// ─── Internals ───────────────────────────────────────────────────
+/** Call observer without letting exceptions crash the workflow */
+function safeObserve(observer, event, logger) {
+    if (!observer)
+        return;
+    try {
+        observer(event);
+    }
+    catch (err) {
+        (logger ?? consoleLogger).warn(`Observer error (non-fatal): ${err.message}`);
+    }
+}
+function resolveTools(skillIds, skills) {
+    return skillIds
+        .map((id) => skills.get(id))
+        .filter((s) => s != null)
+        .flatMap((s) => s.tools);
+}
+/**
+ * Resolve config values: check explicit overrides first, then env vars.
+ * Throws if a required field is missing.
+ */
+function resolveConfig(skills, overrides) {
+    const config = {};
+    const missing = [];
+    for (const skill of skills.values()) {
+        for (const [key, field] of Object.entries(skill.config)) {
+            const value = overrides?.[key] ?? (field.env ? process.env[field.env] : undefined);
+            if (value) {
+                config[key] = value;
+            }
+            else if (field.required) {
+                missing.push(`${skill.id}.${key} (env: ${field.env ?? "none"})`);
+            }
+        }
+    }
+    if (missing.length > 0) {
+        throw new Error(`Missing required config:\n  ${missing.join("\n  ")}`);
+    }
+    return config;
+}
+/**
+ * Resolve which edge to follow from the current node.
+ *
+ * - 0 out-edges → terminal (return null)
+ * - 1 unconditional edge → follow it
+ * - Multiple or conditional → Claude evaluates
+ */
+async function resolveNext(workflow, current, results, claude, observer) {
+    const outEdges = workflow.edges.filter((e) => e.from === current);
+    if (outEdges.length === 0)
+        return null;
+    // Single unconditional edge — just follow it
+    if (outEdges.length === 1 && !outEdges[0].when) {
+        safeObserve(observer, { type: "route", from: current, to: outEdges[0].to, reason: "only path" });
+        return outEdges[0].to;
+    }
+    // Check for a default (unconditional) edge among conditionals
+    const defaultEdge = outEdges.find((e) => !e.when);
+    const conditionalEdges = outEdges.filter((e) => e.when);
+    // Claude evaluates which condition matches
+    const context = Object.fromEntries([...results.entries()].map(([k, v]) => [k, v.data]));
+    const choices = conditionalEdges.map((e) => ({
+        id: e.to,
+        description: e.when,
+    }));
+    if (defaultEdge) {
+        choices.push({ id: defaultEdge.to, description: "None of the above / default path" });
+    }
+    const chosen = await claude.evaluate({
+        question: "Based on the results so far, which condition is true?",
+        context,
+        choices,
+    });
+    // Validate that Claude returned a valid target
+    const validTargets = new Set(outEdges.map((e) => e.to));
+    const resolved = validTargets.has(chosen) ? chosen : (defaultEdge?.to ?? outEdges[0].to); // fall back to default or first edge
+    safeObserve(observer, {
+        type: "route",
+        from: current,
+        to: resolved,
+        reason: choices.find((c) => c.id === resolved)?.description ?? "default",
+    });
+    return resolved;
+}
+/**
+ * Validate a workflow definition before execution.
+ */
+function validate(workflow, skills) {
+    if (!workflow.nodes[workflow.entry]) {
+        throw new Error(`Entry node "${workflow.entry}" not found`);
+    }
+    for (const edge of workflow.edges) {
+        if (!workflow.nodes[edge.from])
+            throw new Error(`Edge references unknown node: "${edge.from}"`);
+        if (!workflow.nodes[edge.to])
+            throw new Error(`Edge references unknown node: "${edge.to}"`);
+    }
+    // Warn about missing skills (non-fatal — skills might be registered later)
+    const allSkillIds = new Set(Object.values(workflow.nodes).flatMap((n) => n.skills));
+    for (const id of allSkillIds) {
+        if (!skills.has(id)) {
+            consoleLogger.warn(`Workflow references unregistered skill: "${id}"`);
+        }
+    }
+}

package/dist/executor.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/executor.test.js

@@ -0,0 +1,314 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { mkdirSync, writeFileSync, readFileSync, existsSync } from "node:fs";
+import { rmSync } from "node:fs";
+import * as path from "node:path";
+import { tmpdir } from "node:os";
+import { execute } from "./executor.js";
+import { MockClaude, createFileSkill } from "./testing.js";
+import { createSkillMap } from "./skills/index.js";
+import { validateWorkflow, parseWorkflow } from "./schema.js";
+import { triageWorkflow } from "./workflows/triage.js";
+import { implementWorkflow } from "./workflows/implement.js";
+// ─── Test fixtures ───────────────────────────────────────────────
+const tmpBase = path.join(tmpdir(), "sweny-core-test");
+function freshDir(name) {
+    const dir = path.join(tmpBase, `${name}-${Date.now()}`);
+    rmSync(dir, { recursive: true, force: true });
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+// Minimal 3-node DAG for unit testing
+const simpleWorkflow = {
+    id: "test-simple",
+    name: "Simple Test",
+    description: "A→B→C linear workflow",
+    entry: "step-a",
+    nodes: {
+        "step-a": {
+            name: "Step A",
+            instruction: "Read the input and produce context",
+            skills: ["filesystem"],
+        },
+        "step-b": {
+            name: "Step B",
+            instruction: "Process the context from step A",
+            skills: ["filesystem"],
+        },
+        "step-c": {
+            name: "Step C",
+            instruction: "Write the final result",
+            skills: ["filesystem"],
+        },
+    },
+    edges: [
+        { from: "step-a", to: "step-b" },
+        { from: "step-b", to: "step-c" },
+    ],
+};
+// Branching DAG for conditional routing
+const branchingWorkflow = {
+    id: "test-branching",
+    name: "Branching Test",
+    description: "A → B or C depending on condition",
+    entry: "check",
+    nodes: {
+        check: {
+            name: "Check Input",
+            instruction: "Examine the input and determine severity",
+            skills: ["filesystem"],
+        },
+        handle_high: {
+            name: "Handle High Severity",
+            instruction: "Handle a high-severity alert",
+            skills: ["filesystem"],
+        },
+        handle_low: {
+            name: "Handle Low Severity",
+            instruction: "Handle a low-severity alert",
+            skills: [],
+        },
+    },
+    edges: [
+        { from: "check", to: "handle_high", when: "severity is high or critical" },
+        { from: "check", to: "handle_low", when: "severity is low or medium" },
+    ],
+};
+// ─── Schema validation tests ─────────────────────────────────────
+describe("schema validation", () => {
+    it("validates a correct workflow", () => {
+        const errors = validateWorkflow(simpleWorkflow);
+        expect(errors).toEqual([]);
+    });
+    it("detects missing entry node", () => {
+        const bad = { ...simpleWorkflow, entry: "nonexistent" };
+        const errors = validateWorkflow(bad);
+        expect(errors).toContainEqual(expect.objectContaining({ code: "MISSING_ENTRY" }));
+    });
+    it("detects unknown edge targets", () => {
+        const bad = {
+            ...simpleWorkflow,
+            edges: [{ from: "step-a", to: "nonexistent" }],
+        };
+        const errors = validateWorkflow(bad);
+        expect(errors).toContainEqual(expect.objectContaining({ code: "UNKNOWN_EDGE_TARGET" }));
+    });
+    it("detects unreachable nodes", () => {
+        const disconnected = {
+            ...simpleWorkflow,
+            edges: [{ from: "step-a", to: "step-b" }],
+            // step-c has no incoming edge
+        };
+        const errors = validateWorkflow(disconnected);
+        expect(errors).toContainEqual(expect.objectContaining({ code: "UNREACHABLE_NODE", nodeId: "step-c" }));
+    });
+    it("detects self-loops", () => {
+        const loopy = {
+            ...simpleWorkflow,
+            edges: [
+                { from: "step-a", to: "step-a" },
+                { from: "step-a", to: "step-b" },
+                { from: "step-b", to: "step-c" },
+            ],
+        };
+        const errors = validateWorkflow(loopy);
+        expect(errors).toContainEqual(expect.objectContaining({ code: "SELF_LOOP", nodeId: "step-a" }));
+    });
+    it("detects unknown skill references", () => {
+        const errors = validateWorkflow(simpleWorkflow, new Set(["github"]));
+        expect(errors).toContainEqual(expect.objectContaining({ code: "UNKNOWN_SKILL", nodeId: "step-a" }));
+    });
+    it("validates the triage workflow", () => {
+        const errors = validateWorkflow(triageWorkflow);
+        expect(errors).toEqual([]);
+    });
+    it("validates the implement workflow", () => {
+        const errors = validateWorkflow(implementWorkflow);
+        expect(errors).toEqual([]);
+    });
+    it("parses a raw JSON workflow via Zod", () => {
+        const raw = JSON.parse(JSON.stringify(simpleWorkflow));
+        const parsed = parseWorkflow(raw);
+        expect(parsed.id).toBe("test-simple");
+        expect(parsed.nodes["step-a"].instruction).toBe("Read the input and produce context");
+    });
+    it("rejects invalid workflow JSON", () => {
+        expect(() => parseWorkflow({ id: "" })).toThrow();
+        expect(() => parseWorkflow({ id: "x", name: "x", nodes: {}, edges: [] })).toThrow(); // missing entry
+    });
+});
+// ─── Executor tests ──────────────────────────────────────────────
+describe("executor", () => {
+    let outputDir;
+    beforeEach(() => {
+        outputDir = freshDir("executor");
+    });
+    it("executes a linear workflow end-to-end", async () => {
+        const fileSkill = createFileSkill(outputDir);
+        const skills = createSkillMap([fileSkill]);
+        // Write a fixture input file
+        writeFileSync(path.join(outputDir, "input.json"), JSON.stringify({ alert: "test" }));
+        const claude = new MockClaude({
+            responses: {
+                "step-a": {
+                    toolCalls: [{ tool: "fs_read_json", input: { path: "input.json" } }],
+                    data: { context: "loaded from file" },
+                },
+                "step-b": {
+                    data: { analysis: "processed" },
+                },
+                "step-c": {
+                    toolCalls: [
+                        {
+                            tool: "fs_write_json",
+                            input: { path: "result.json", data: { status: "done" } },
+                        },
+                    ],
+                    data: { result: "written" },
+                },
+            },
+        });
+        const events = [];
+        const results = await execute(simpleWorkflow, { alert: "test" }, {
+            skills,
+            claude,
+            observer: (e) => events.push(e),
+            config: {},
+        });
+        // All 3 nodes executed
+        expect(results.size).toBe(3);
+        expect(results.get("step-a")?.status).toBe("success");
+        expect(results.get("step-b")?.status).toBe("success");
+        expect(results.get("step-c")?.status).toBe("success");
+        // Node A read the input file
+        expect(results.get("step-a")?.data.context).toBe("loaded from file");
+        // Node C wrote the result file
+        expect(existsSync(path.join(outputDir, "result.json"))).toBe(true);
+        const written = JSON.parse(readFileSync(path.join(outputDir, "result.json"), "utf-8"));
+        expect(written.status).toBe("done");
+        // Events were emitted correctly
+        expect(events[0]).toEqual({ type: "workflow:start", workflow: "test-simple" });
+        const nodeEnters = events.filter((e) => e.type === "node:enter");
+        expect(nodeEnters).toHaveLength(3);
+        expect(events[events.length - 1].type).toBe("workflow:end");
+    });
+    it("executes conditional branches", async () => {
+        const fileSkill = createFileSkill(outputDir);
+        const skills = createSkillMap([fileSkill]);
+        const claude = new MockClaude({
+            responses: {
+                check: { data: { severity: "high" } },
+                handle_high: { data: { handled: true } },
+            },
+            routes: {
+                check: "handle_high", // Route to high severity handler
+            },
+        });
+        const results = await execute(branchingWorkflow, { alert: "cpu spike" }, {
+            skills,
+            claude,
+            config: {},
+        });
+        expect(results.size).toBe(2);
+        expect(results.has("check")).toBe(true);
+        expect(results.has("handle_high")).toBe(true);
+        expect(results.has("handle_low")).toBe(false);
+    });
+    it("routes to alternative branch", async () => {
+        const fileSkill = createFileSkill(outputDir);
+        const skills = createSkillMap([fileSkill]);
+        const claude = new MockClaude({
+            responses: {
+                check: { data: { severity: "low" } },
+                handle_low: { data: { skipped: true } },
+            },
+            routes: {
+                check: "handle_low",
+            },
+        });
+        const results = await execute(branchingWorkflow, { alert: "minor" }, {
+            skills,
+            claude,
+            config: {},
+        });
+        expect(results.size).toBe(2);
+        expect(results.has("handle_low")).toBe(true);
+        expect(results.has("handle_high")).toBe(false);
+    });
+    it("emits tool:call and tool:result events", async () => {
+        const fileSkill = createFileSkill(outputDir);
+        writeFileSync(path.join(outputDir, "data.json"), '{"key": "value"}');
+        const claude = new MockClaude({
+            responses: {
+                "step-a": {
+                    toolCalls: [{ tool: "fs_read_json", input: { path: "data.json" } }],
+                    data: { read: true },
+                },
+                "step-b": { data: {} },
+                "step-c": { data: {} },
+            },
+        });
+        const events = [];
+        await execute(simpleWorkflow, {}, {
+            skills: createSkillMap([fileSkill]),
+            claude,
+            observer: (e) => events.push(e),
+            config: {},
+        });
+        const toolCalls = events.filter((e) => e.type === "tool:call");
+        const toolResults = events.filter((e) => e.type === "tool:result");
+        expect(toolCalls).toHaveLength(1);
+        expect(toolResults).toHaveLength(1);
+        expect(toolCalls[0]).toMatchObject({
+            type: "tool:call",
+            node: "step-a",
+            tool: "fs_read_json",
+        });
+    });
+    it("throws on missing entry node", async () => {
+        const bad = { ...simpleWorkflow, entry: "nonexistent" };
+        const claude = new MockClaude({ responses: {} });
+        await expect(execute(bad, {}, { skills: createSkillMap([]), claude, config: {} })).rejects.toThrow("Entry node");
+    });
+    it("throws on invalid edge reference", async () => {
+        const bad = {
+            ...simpleWorkflow,
+            edges: [
+                { from: "step-a", to: "nonexistent" },
+                { from: "step-a", to: "step-b" },
+            ],
+        };
+        const claude = new MockClaude({ responses: {} });
+        await expect(execute(bad, {}, { skills: createSkillMap([]), claude, config: {} })).rejects.toThrow("unknown node");
+    });
+});
+// ─── File skill tests ────────────────────────────────────────────
+describe("file skill", () => {
+    let outputDir;
+    beforeEach(() => {
+        outputDir = freshDir("fileskill");
+    });
+    it("reads and writes JSON", async () => {
+        const skill = createFileSkill(outputDir);
+        const write = skill.tools.find((t) => t.name === "fs_write_json");
+        const read = skill.tools.find((t) => t.name === "fs_read_json");
+        const ctx = { config: {}, logger: console };
+        await write.handler({ path: "test.json", data: { hello: "world" } }, ctx);
+        const result = await read.handler({ path: "test.json" }, ctx);
+        expect(result).toEqual({ hello: "world" });
+    });
+    it("writes markdown", async () => {
+        const skill = createFileSkill(outputDir);
+        const write = skill.tools.find((t) => t.name === "fs_write_markdown");
+        const ctx = { config: {}, logger: console };
+        await write.handler({ path: "issues/ISSUE-1.md", content: "# Bug\n\nSomething broke" }, ctx);
+        const content = readFileSync(path.join(outputDir, "issues/ISSUE-1.md"), "utf-8");
+        expect(content).toContain("# Bug");
+    });
+    it("creates nested directories", async () => {
+        const skill = createFileSkill(outputDir);
+        const write = skill.tools.find((t) => t.name === "fs_write_json");
+        const ctx = { config: {}, logger: console };
+        await write.handler({ path: "deep/nested/file.json", data: { ok: true } }, ctx);
+        expect(existsSync(path.join(outputDir, "deep/nested/file.json"))).toBe(true);
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @sweny-ai/core — Skill library + DAG workflow orchestration
+ *
+ * Three concepts:
+ *   Skill  — a group of tools Claude can call (replaces "providers")
+ *   Workflow — a DAG of nodes connected by edges (replaces "engine + recipes")
+ *   execute() — walk the DAG, run Claude at each node
+ *
+ * @example
+ * ```ts
+ * import { execute, ClaudeClient, createSkillMap, github, sentry, slack } from '@sweny-ai/core'
+ * import { triageWorkflow } from '@sweny-ai/core/workflows'
+ *
+ * const skills = createSkillMap([github, sentry, slack])
+ * const claude = new ClaudeClient()
+ *
+ * const results = await execute(triageWorkflow, alertPayload, {
+ *   skills,
+ *   claude,
+ *   observer: (event) => console.log(event),
+ * })
+ * ```
+ */
+export type { Skill, SkillCategory, Tool, ToolContext, ConfigField, JSONSchema, Workflow, Node, Edge, NodeResult, ToolCall, ExecutionEvent, Observer, Claude, Logger, } from "./types.js";
+export { consoleLogger } from "./types.js";
+export { execute } from "./executor.js";
+export type { ExecuteOptions } from "./executor.js";
+export { ClaudeClient } from "./claude.js";
+export type { ClaudeClientOptions } from "./claude.js";
+export { github, linear, slack, sentry, datadog, betterstack, notification, builtinSkills, createSkillMap, allSkills, isSkillConfigured, configuredSkills, validateWorkflowSkills, } from "./skills/index.js";
+export type { SkillValidationResult } from "./skills/index.js";
+export { workflowZ, nodeZ, edgeZ, skillZ, parseWorkflow, validateWorkflow, workflowJsonSchema } from "./schema.js";
+export type { WorkflowError } from "./schema.js";
+export { buildAutoMcpServers } from "./mcp.js";
+export type { McpServerConfig, McpAutoConfig } from "./types.js";
+export { buildWorkflow, refineWorkflow } from "./workflow-builder.js";
+export type { BuildWorkflowOptions } from "./workflow-builder.js";

package/dist/index.js

@@ -0,0 +1,36 @@
+/**
+ * @sweny-ai/core — Skill library + DAG workflow orchestration
+ *
+ * Three concepts:
+ *   Skill  — a group of tools Claude can call (replaces "providers")
+ *   Workflow — a DAG of nodes connected by edges (replaces "engine + recipes")
+ *   execute() — walk the DAG, run Claude at each node
+ *
+ * @example
+ * ```ts
+ * import { execute, ClaudeClient, createSkillMap, github, sentry, slack } from '@sweny-ai/core'
+ * import { triageWorkflow } from '@sweny-ai/core/workflows'
+ *
+ * const skills = createSkillMap([github, sentry, slack])
+ * const claude = new ClaudeClient()
+ *
+ * const results = await execute(triageWorkflow, alertPayload, {
+ *   skills,
+ *   claude,
+ *   observer: (event) => console.log(event),
+ * })
+ * ```
+ */
+export { consoleLogger } from "./types.js";
+// Executor
+export { execute } from "./executor.js";
+// Claude client
+export { ClaudeClient } from "./claude.js";
+// Skills
+export { github, linear, slack, sentry, datadog, betterstack, notification, builtinSkills, createSkillMap, allSkills, isSkillConfigured, configuredSkills, validateWorkflowSkills, } from "./skills/index.js";
+// Schema & validation
+export { workflowZ, nodeZ, edgeZ, skillZ, parseWorkflow, validateWorkflow, workflowJsonSchema } from "./schema.js";
+// MCP auto-injection
+export { buildAutoMcpServers } from "./mcp.js";
+// Workflow builder
+export { buildWorkflow, refineWorkflow } from "./workflow-builder.js";

package/dist/mcp.d.ts

@@ -0,0 +1,11 @@
+import type { McpAutoConfig, McpServerConfig } from "./types.js";
+/**
+ * Auto-configure well-known MCP servers based on which providers
+ * and workspace tools the user has enabled.
+ *
+ * Category A: triggered by sourceControlProvider / issueTrackerProvider / observabilityProvider
+ * Category B: workspace tools — explicit opt-in via workspaceTools array
+ *
+ * User-supplied servers (userMcpServers) always win on key conflicts.
+ */
+export declare function buildAutoMcpServers(config: McpAutoConfig): Record<string, McpServerConfig>;