@sweny-ai/core 0.1.0

package/dist/schema.d.ts

@@ -0,0 +1,318 @@
+/**
+ * Workflow Schema & Validation
+ *
+ * Zod schemas that define the canonical Workflow spec.
+ * Use `validateWorkflow()` for structural validation (cycles,
+ * reachability, missing nodes). Use the Zod schemas for
+ * parsing untrusted input (JSON/YAML import, Studio editor).
+ */
+import { z } from "zod";
+export declare const jsonSchemaZ: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const configFieldZ: z.ZodObject<{
+    description: z.ZodString;
+    required: z.ZodOptional<z.ZodBoolean>;
+    env: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    description: string;
+    required?: boolean | undefined;
+    env?: string | undefined;
+}, {
+    description: string;
+    required?: boolean | undefined;
+    env?: string | undefined;
+}>;
+/**
+ * Zod schema for tool metadata (name, description, input_schema).
+ * Note: `handler` is intentionally omitted — Zod schemas validate
+ * serializable data (JSON import/export), not runtime function refs.
+ */
+export declare const toolZ: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    input_schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+}, {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+}>;
+export declare const skillCategoryZ: z.ZodEnum<["git", "observability", "tasks", "notification", "general"]>;
+export declare const skillZ: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodString;
+    category: z.ZodEnum<["git", "observability", "tasks", "notification", "general"]>;
+    config: z.ZodRecord<z.ZodString, z.ZodObject<{
+        description: z.ZodString;
+        required: z.ZodOptional<z.ZodBoolean>;
+        env: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        description: string;
+        required?: boolean | undefined;
+        env?: string | undefined;
+    }, {
+        description: string;
+        required?: boolean | undefined;
+        env?: string | undefined;
+    }>>;
+    tools: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        input_schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        description: string;
+        input_schema: Record<string, unknown>;
+    }, {
+        name: string;
+        description: string;
+        input_schema: Record<string, unknown>;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    name: string;
+    description: string;
+    category: "git" | "observability" | "tasks" | "notification" | "general";
+    config: Record<string, {
+        description: string;
+        required?: boolean | undefined;
+        env?: string | undefined;
+    }>;
+    tools: {
+        name: string;
+        description: string;
+        input_schema: Record<string, unknown>;
+    }[];
+}, {
+    id: string;
+    name: string;
+    description: string;
+    category: "git" | "observability" | "tasks" | "notification" | "general";
+    config: Record<string, {
+        description: string;
+        required?: boolean | undefined;
+        env?: string | undefined;
+    }>;
+    tools: {
+        name: string;
+        description: string;
+        input_schema: Record<string, unknown>;
+    }[];
+}>;
+export declare const nodeZ: z.ZodObject<{
+    name: z.ZodString;
+    instruction: z.ZodString;
+    skills: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    output: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    skills: string[];
+    name: string;
+    instruction: string;
+    output?: Record<string, unknown> | undefined;
+}, {
+    name: string;
+    instruction: string;
+    skills?: string[] | undefined;
+    output?: Record<string, unknown> | undefined;
+}>;
+export declare const edgeZ: z.ZodObject<{
+    from: z.ZodString;
+    to: z.ZodString;
+    when: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    from: string;
+    to: string;
+    when?: string | undefined;
+}, {
+    from: string;
+    to: string;
+    when?: string | undefined;
+}>;
+export declare const workflowZ: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodDefault<z.ZodString>;
+    nodes: z.ZodRecord<z.ZodString, z.ZodObject<{
+        name: z.ZodString;
+        instruction: z.ZodString;
+        skills: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        output: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        skills: string[];
+        name: string;
+        instruction: string;
+        output?: Record<string, unknown> | undefined;
+    }, {
+        name: string;
+        instruction: string;
+        skills?: string[] | undefined;
+        output?: Record<string, unknown> | undefined;
+    }>>;
+    edges: z.ZodArray<z.ZodObject<{
+        from: z.ZodString;
+        to: z.ZodString;
+        when: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        from: string;
+        to: string;
+        when?: string | undefined;
+    }, {
+        from: string;
+        to: string;
+        when?: string | undefined;
+    }>, "many">;
+    entry: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    name: string;
+    description: string;
+    nodes: Record<string, {
+        skills: string[];
+        name: string;
+        instruction: string;
+        output?: Record<string, unknown> | undefined;
+    }>;
+    edges: {
+        from: string;
+        to: string;
+        when?: string | undefined;
+    }[];
+    entry: string;
+}, {
+    id: string;
+    name: string;
+    nodes: Record<string, {
+        name: string;
+        instruction: string;
+        skills?: string[] | undefined;
+        output?: Record<string, unknown> | undefined;
+    }>;
+    edges: {
+        from: string;
+        to: string;
+        when?: string | undefined;
+    }[];
+    entry: string;
+    description?: string | undefined;
+}>;
+/** Parse + validate a raw object as a Workflow. Throws on invalid input. */
+export declare function parseWorkflow(raw: unknown): {
+    id: string;
+    name: string;
+    description: string;
+    nodes: Record<string, {
+        skills: string[];
+        name: string;
+        instruction: string;
+        output?: Record<string, unknown> | undefined;
+    }>;
+    edges: {
+        from: string;
+        to: string;
+        when?: string | undefined;
+    }[];
+    entry: string;
+};
+export interface WorkflowError {
+    code: "MISSING_ENTRY" | "UNKNOWN_EDGE_SOURCE" | "UNKNOWN_EDGE_TARGET" | "UNREACHABLE_NODE" | "UNKNOWN_SKILL" | "SELF_LOOP" | "NO_OUTGOING_EDGE";
+    message: string;
+    nodeId?: string;
+}
+/**
+ * Validate a workflow's graph structure.
+ *
+ * Checks:
+ * - Entry node exists
+ * - All edge sources and targets reference existing nodes
+ * - No self-loops
+ * - All nodes are reachable from entry
+ * - All non-terminal nodes have at least one outgoing edge
+ * - (optional) All referenced skills exist in the provided skill set
+ */
+export declare function validateWorkflow(workflow: z.infer<typeof workflowZ>, knownSkills?: Set<string>): WorkflowError[];
+/**
+ * Static JSON Schema for the Workflow type.
+ * Use this for external validation (YAML files, Studio import, CI checks).
+ */
+export declare const workflowJsonSchema: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $id: "https://sweny.ai/schemas/workflow.json";
+    readonly title: "SWEny Workflow";
+    readonly description: "A DAG workflow definition for skill-based orchestration";
+    readonly type: "object";
+    readonly required: readonly ["id", "name", "nodes", "edges", "entry"];
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly id: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly name: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly description: {
+            readonly type: "string";
+        };
+        readonly entry: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly description: "ID of the entry node";
+        };
+        readonly nodes: {
+            readonly type: "object";
+            readonly additionalProperties: {
+                readonly type: "object";
+                readonly required: readonly ["name", "instruction"];
+                readonly additionalProperties: false;
+                readonly properties: {
+                    readonly name: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly instruction: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly description: "What Claude should do at this node";
+                    };
+                    readonly skills: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                        readonly description: "Skill IDs available at this node";
+                    };
+                    readonly output: {
+                        readonly type: "object";
+                        readonly description: "Optional JSON Schema for structured output";
+                    };
+                };
+            };
+        };
+        readonly edges: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly required: readonly ["from", "to"];
+                readonly additionalProperties: false;
+                readonly properties: {
+                    readonly from: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly to: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly when: {
+                        readonly type: "string";
+                        readonly description: "Natural language condition — Claude evaluates at runtime";
+                    };
+                };
+            };
+        };
+    };
+};

package/dist/schema.js

@@ -0,0 +1,207 @@
+/**
+ * Workflow Schema & Validation
+ *
+ * Zod schemas that define the canonical Workflow spec.
+ * Use `validateWorkflow()` for structural validation (cycles,
+ * reachability, missing nodes). Use the Zod schemas for
+ * parsing untrusted input (JSON/YAML import, Studio editor).
+ */
+import { z } from "zod";
+// ─── Zod Schemas ─────────────────────────────────────────────────
+export const jsonSchemaZ = z.record(z.unknown());
+export const configFieldZ = z.object({
+    description: z.string(),
+    required: z.boolean().optional(),
+    env: z.string().optional(),
+});
+/**
+ * Zod schema for tool metadata (name, description, input_schema).
+ * Note: `handler` is intentionally omitted — Zod schemas validate
+ * serializable data (JSON import/export), not runtime function refs.
+ */
+export const toolZ = z.object({
+    name: z.string().min(1),
+    description: z.string(),
+    input_schema: jsonSchemaZ,
+});
+export const skillCategoryZ = z.enum(["git", "observability", "tasks", "notification", "general"]);
+export const skillZ = z.object({
+    id: z.string().min(1),
+    name: z.string(),
+    description: z.string(),
+    category: skillCategoryZ,
+    config: z.record(configFieldZ),
+    tools: z.array(toolZ),
+});
+export const nodeZ = z.object({
+    name: z.string().min(1),
+    instruction: z.string().min(1),
+    skills: z.array(z.string()).default([]),
+    output: jsonSchemaZ.optional(),
+});
+export const edgeZ = z.object({
+    from: z.string().min(1),
+    to: z.string().min(1),
+    when: z.string().optional(),
+});
+export const workflowZ = z.object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    description: z.string().default(""),
+    nodes: z.record(nodeZ),
+    edges: z.array(edgeZ),
+    entry: z.string().min(1),
+});
+/** Parse + validate a raw object as a Workflow. Throws on invalid input. */
+export function parseWorkflow(raw) {
+    return workflowZ.parse(raw);
+}
+/**
+ * Validate a workflow's graph structure.
+ *
+ * Checks:
+ * - Entry node exists
+ * - All edge sources and targets reference existing nodes
+ * - No self-loops
+ * - All nodes are reachable from entry
+ * - All non-terminal nodes have at least one outgoing edge
+ * - (optional) All referenced skills exist in the provided skill set
+ */
+export function validateWorkflow(workflow, knownSkills) {
+    const errors = [];
+    const nodeIds = new Set(Object.keys(workflow.nodes));
+    // Entry must exist
+    if (!nodeIds.has(workflow.entry)) {
+        errors.push({
+            code: "MISSING_ENTRY",
+            message: `Entry node "${workflow.entry}" does not exist`,
+        });
+    }
+    // Edge targets must exist
+    for (const edge of workflow.edges) {
+        if (!nodeIds.has(edge.from)) {
+            errors.push({
+                code: "UNKNOWN_EDGE_SOURCE",
+                message: `Edge source "${edge.from}" does not exist`,
+                nodeId: edge.from,
+            });
+        }
+        if (!nodeIds.has(edge.to)) {
+            errors.push({
+                code: "UNKNOWN_EDGE_TARGET",
+                message: `Edge target "${edge.to}" does not exist`,
+                nodeId: edge.to,
+            });
+        }
+        if (edge.from === edge.to) {
+            errors.push({
+                code: "SELF_LOOP",
+                message: `Edge from "${edge.from}" to itself`,
+                nodeId: edge.from,
+            });
+        }
+    }
+    // Don't check reachability if there are structural errors
+    if (errors.length > 0)
+        return errors;
+    // Reachability: BFS from entry
+    const visited = new Set();
+    const queue = [workflow.entry];
+    while (queue.length > 0) {
+        const id = queue.shift();
+        if (visited.has(id))
+            continue;
+        visited.add(id);
+        for (const edge of workflow.edges) {
+            if (edge.from === id && !visited.has(edge.to)) {
+                queue.push(edge.to);
+            }
+        }
+    }
+    for (const nodeId of nodeIds) {
+        if (!visited.has(nodeId)) {
+            errors.push({
+                code: "UNREACHABLE_NODE",
+                message: `Node "${nodeId}" is unreachable from entry "${workflow.entry}"`,
+                nodeId,
+            });
+        }
+    }
+    // Non-terminal nodes must have outgoing edges
+    for (const nodeId of nodeIds) {
+        const hasOutgoing = workflow.edges.some((e) => e.from === nodeId);
+        if (!hasOutgoing && visited.has(nodeId)) {
+            // Terminal node — fine, no error. This is intentional.
+            // But if it has outgoing in the graph, it's fine too.
+        }
+    }
+    // Skill references
+    if (knownSkills) {
+        for (const [nodeId, node] of Object.entries(workflow.nodes)) {
+            for (const skillId of node.skills) {
+                if (!knownSkills.has(skillId)) {
+                    errors.push({
+                        code: "UNKNOWN_SKILL",
+                        message: `Node "${nodeId}" references unknown skill "${skillId}"`,
+                        nodeId,
+                    });
+                }
+            }
+        }
+    }
+    return errors;
+}
+// ─── JSON Schema Export ──────────────────────────────────────────
+/**
+ * Static JSON Schema for the Workflow type.
+ * Use this for external validation (YAML files, Studio import, CI checks).
+ */
+export const workflowJsonSchema = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: "https://sweny.ai/schemas/workflow.json",
+    title: "SWEny Workflow",
+    description: "A DAG workflow definition for skill-based orchestration",
+    type: "object",
+    required: ["id", "name", "nodes", "edges", "entry"],
+    additionalProperties: false,
+    properties: {
+        id: { type: "string", minLength: 1 },
+        name: { type: "string", minLength: 1 },
+        description: { type: "string" },
+        entry: { type: "string", minLength: 1, description: "ID of the entry node" },
+        nodes: {
+            type: "object",
+            additionalProperties: {
+                type: "object",
+                required: ["name", "instruction"],
+                additionalProperties: false,
+                properties: {
+                    name: { type: "string", minLength: 1 },
+                    instruction: { type: "string", minLength: 1, description: "What Claude should do at this node" },
+                    skills: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Skill IDs available at this node",
+                    },
+                    output: {
+                        type: "object",
+                        description: "Optional JSON Schema for structured output",
+                    },
+                },
+            },
+        },
+        edges: {
+            type: "array",
+            items: {
+                type: "object",
+                required: ["from", "to"],
+                additionalProperties: false,
+                properties: {
+                    from: { type: "string", minLength: 1 },
+                    to: { type: "string", minLength: 1 },
+                    when: { type: "string", description: "Natural language condition — Claude evaluates at runtime" },
+                },
+            },
+        },
+    },
+};

package/dist/skills/betterstack.d.ts

@@ -0,0 +1,7 @@
+/**
+ * BetterStack Skill
+ *
+ * Uptime monitoring (incidents, monitors) and log search via BetterStack APIs.
+ */
+import type { Skill } from "../types.js";
+export declare const betterstack: Skill;

package/dist/skills/betterstack.js

@@ -0,0 +1,114 @@
+/**
+ * BetterStack Skill
+ *
+ * Uptime monitoring (incidents, monitors) and log search via BetterStack APIs.
+ */
+const UPTIME_BASE = "https://uptime.betterstack.com/api/v2";
+async function uptimeApi(path, ctx, init) {
+    const res = await fetch(`${UPTIME_BASE}${path}`, {
+        ...init,
+        headers: {
+            Authorization: `Bearer ${ctx.config.BETTERSTACK_API_TOKEN}`,
+            "Content-Type": "application/json",
+            ...init?.headers,
+        },
+        signal: AbortSignal.timeout(30_000),
+    });
+    if (!res.ok)
+        throw new Error(`[BetterStack] API request failed (HTTP ${res.status}): ${await res.text()}`);
+    return res.json();
+}
+export const betterstack = {
+    id: "betterstack",
+    name: "BetterStack",
+    description: "Query incidents, monitors, and logs from BetterStack (Better Uptime + Logtail)",
+    category: "observability",
+    config: {
+        BETTERSTACK_API_TOKEN: {
+            description: "BetterStack API token (from Uptime > Settings > API)",
+            required: true,
+            env: "BETTERSTACK_API_TOKEN",
+        },
+    },
+    tools: [
+        {
+            name: "betterstack_list_incidents",
+            description: "List recent incidents from BetterStack Uptime. Returns ongoing and resolved incidents.",
+            input_schema: {
+                type: "object",
+                properties: {
+                    from: { type: "string", description: "ISO 8601 start date (e.g. 2024-01-01T00:00:00Z)" },
+                    to: { type: "string", description: "ISO 8601 end date" },
+                    per_page: { type: "number", description: "Results per page (default 20, max 100)" },
+                },
+            },
+            handler: async (input, ctx) => {
+                const params = new URLSearchParams();
+                if (input.from)
+                    params.set("from", input.from);
+                if (input.to)
+                    params.set("to", input.to);
+                if (input.per_page)
+                    params.set("per_page", String(input.per_page));
+                const qs = params.toString();
+                return uptimeApi(`/incidents${qs ? `?${qs}` : ""}`, ctx);
+            },
+        },
+        {
+            name: "betterstack_get_incident",
+            description: "Get detailed information about a specific incident including timeline.",
+            input_schema: {
+                type: "object",
+                properties: {
+                    incident_id: { type: "string", description: "Incident ID" },
+                },
+                required: ["incident_id"],
+            },
+            handler: async (input, ctx) => {
+                return uptimeApi(`/incidents/${input.incident_id}`, ctx);
+            },
+        },
+        {
+            name: "betterstack_list_monitors",
+            description: "List all monitors (uptime checks) and their current status.",
+            input_schema: {
+                type: "object",
+                properties: {
+                    per_page: { type: "number", description: "Results per page (default 20, max 100)" },
+                },
+            },
+            handler: async (input, ctx) => {
+                const params = new URLSearchParams();
+                if (input.per_page)
+                    params.set("per_page", String(input.per_page));
+                const qs = params.toString();
+                return uptimeApi(`/monitors${qs ? `?${qs}` : ""}`, ctx);
+            },
+        },
+        {
+            name: "betterstack_get_monitor",
+            description: "Get details and recent status of a specific monitor.",
+            input_schema: {
+                type: "object",
+                properties: {
+                    monitor_id: { type: "string", description: "Monitor ID" },
+                },
+                required: ["monitor_id"],
+            },
+            handler: async (input, ctx) => {
+                return uptimeApi(`/monitors/${input.monitor_id}`, ctx);
+            },
+        },
+        {
+            name: "betterstack_list_on_call",
+            description: "List current on-call calendars and who is on-call.",
+            input_schema: {
+                type: "object",
+                properties: {},
+            },
+            handler: async (_input, ctx) => {
+                return uptimeApi("/on-calls", ctx);
+            },
+        },
+    ],
+};

package/dist/skills/datadog.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Datadog Skill
+ *
+ * Replaces: observability/datadog.ts
+ */
+import type { Skill } from "../types.js";
+export declare const datadog: Skill;