@agentic-surfaces/core 0.1.8 → 0.1.10

package/dist/agents.d.ts

@@ -0,0 +1,26 @@
+export interface AgentCommand {
+    name: string;
+    description?: string;
+}
+export interface AgentDefinition {
+    name: string;
+    model?: string;
+    effort?: "low" | "medium" | "high" | "xhigh" | "max";
+    commands?: AgentCommand[];
+    fallback?: string;
+    mcpServers?: Array<{
+        name: string;
+        url?: string;
+        command?: string;
+        args?: string[];
+    }>;
+    instructions: string;
+}
+/**
+ * Parse one agent `.md` file into an AgentDefinition.
+ *
+ * @param content      Raw file contents (optional YAML frontmatter + markdown body).
+ * @param defaultName  Used as `name` when the frontmatter omits it (e.g. the filename).
+ * @throws if the frontmatter is present but invalid YAML or fails validation.
+ */
+export declare function parseAgentFile(content: string, defaultName: string): AgentDefinition;

package/dist/agents.js

@@ -0,0 +1,73 @@
+import { z } from "zod";
+import { parse as parseYaml } from "yaml";
+// A reusable agent definition loaded from agents/<name>.md — YAML frontmatter
+// (config) + a markdown body (instructions). Decision agents declare a `commands`
+// allowlist (+ fallback); worker agents omit it and just do a task on their model.
+const McpServerRefSchema = z.union([
+    z.object({ name: z.string(), url: z.string() }),
+    z.object({ name: z.string(), command: z.string(), args: z.array(z.string()).optional() }),
+]);
+const AgentCommandSchema = z.object({
+    name: z.string().min(1),
+    description: z.string().optional(),
+});
+const AgentFrontmatterSchema = z
+    .object({
+    name: z.string().min(1).optional(),
+    model: z.string().optional(),
+    effort: z.enum(["low", "medium", "high", "xhigh", "max"]).optional(),
+    commands: z.array(AgentCommandSchema).min(1).optional(),
+    fallback: z.string().optional(),
+    mcpServers: z.array(McpServerRefSchema).optional(),
+})
+    .superRefine((v, ctx) => {
+    if (v.commands) {
+        const names = v.commands.map((c) => c.name);
+        if (new Set(names).size !== names.length) {
+            ctx.addIssue({ code: "custom", message: "command names must be unique", path: ["commands"] });
+        }
+        if (v.fallback && !names.includes(v.fallback)) {
+            ctx.addIssue({ code: "custom", message: `fallback "${v.fallback}" is not one of the commands`, path: ["fallback"] });
+        }
+    }
+    else if (v.fallback) {
+        ctx.addIssue({ code: "custom", message: "fallback requires a commands list", path: ["fallback"] });
+    }
+});
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---\s*\r?\n?([\s\S]*)$/;
+/**
+ * Parse one agent `.md` file into an AgentDefinition.
+ *
+ * @param content      Raw file contents (optional YAML frontmatter + markdown body).
+ * @param defaultName  Used as `name` when the frontmatter omits it (e.g. the filename).
+ * @throws if the frontmatter is present but invalid YAML or fails validation.
+ */
+export function parseAgentFile(content, defaultName) {
+    let rawFm = {};
+    let body = content;
+    const m = content.match(FRONTMATTER);
+    if (m) {
+        try {
+            rawFm = parseYaml(m[1]) ?? {};
+        }
+        catch (err) {
+            throw new Error(`agent "${defaultName}": invalid frontmatter YAML: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        body = m[2] ?? "";
+    }
+    const result = AgentFrontmatterSchema.safeParse(rawFm);
+    if (!result.success) {
+        const issues = result.error.issues.map((i) => `  ${i.path.join(".")}: ${i.message}`).join("\n");
+        throw new Error(`agent "${defaultName}": invalid definition:\n${issues}`);
+    }
+    const fm = result.data;
+    return {
+        name: fm.name ?? defaultName,
+        model: fm.model,
+        effort: fm.effort,
+        commands: fm.commands,
+        fallback: fm.fallback,
+        mcpServers: fm.mcpServers,
+        instructions: body.trim(),
+    };
+}

package/dist/handlers/agent.js

@@ -2,20 +2,64 @@ export const agentHandler = {
     type: "agent.run",
     async execute(node, ctx) {
         const cfg = node.config;
+        // Resolve a named agent file, if referenced.
+        let instructions = cfg.prompt ?? "";
+        let model = cfg.model;
+        let effort = cfg.effort;
+        let mcpServers = cfg.mcpServers;
+        let decisionSchema = cfg.decision;
+        let commands;
+        let fallback;
+        if (cfg.agent) {
+            const def = ctx.services.agents?.get(cfg.agent);
+            if (!def)
+                throw new Error(`unknown agent: ${cfg.agent}`);
+            // Agent file body is the prompt; a node-level prompt is appended as extra guidance.
+            instructions = cfg.prompt ? `${def.instructions}\n\n${cfg.prompt}` : def.instructions;
+            model = cfg.model ?? def.model;
+            effort = cfg.effort ?? def.effort;
+            mcpServers = cfg.mcpServers ?? def.mcpServers;
+            commands = def.commands;
+            fallback = def.fallback;
+            // A decision agent's commands generate the decision schema (the allowlist).
+            if (commands?.length) {
+                decisionSchema = {
+                    type: "object",
+                    properties: { command: { enum: commands.map((c) => c.name) } },
+                    required: ["command"],
+                };
+            }
+        }
+        if (!cfg.agent && !cfg.prompt) {
+            throw new Error("agent.run requires either `agent` or `prompt`");
+        }
         const defaults = ctx.services.agentDefaults ?? {};
-        const model = cfg.model ?? defaults.model;
-        const effort = cfg.effort ?? defaults.effort; // per-node wins, else project default
-        const mcpServers = cfg.mcpServers ?? defaults.mcpServers;
+        model = model ?? defaults.model;
+        effort = effort ?? defaults.effort;
+        mcpServers = mcpServers ?? defaults.mcpServers;
         const result = await ctx.services.agent.run({
-            prompt: cfg.prompt,
+            prompt: instructions,
             model,
             effort,
             mcpServers,
             context: Object.fromEntries(ctx.outputs),
-            decisionSchema: cfg.decision,
+            decisionSchema,
         });
-        // With a decision schema, surface the decision's fields at the top level so
-        // jsonata (e.g. task.branch `interpret.action`) can route on them; keep .text.
+        // Decision agent: guarantee the chosen command is on the allowlist (else use
+        // the fallback), and surface it at the top level so task.branch can route.
+        if (commands?.length) {
+            const names = new Set(commands.map((c) => c.name));
+            const raw = result.data?.command;
+            let command = typeof raw === "string" ? raw : "";
+            if (!names.has(command)) {
+                if (fallback)
+                    command = fallback;
+                else
+                    throw new Error(`agent ${cfg.agent} returned an off-allowlist command: ${String(raw)}`);
+            }
+            return { output: { command, text: result.text } };
+        }
+        // Inline decision schema: surface its fields at the top level (0.1.7 behaviour).
         if (cfg.decision && result.data && typeof result.data === "object" && !Array.isArray(result.data)) {
             return { output: { ...result.data, text: result.text } };
         }

package/dist/index.d.ts

@@ -7,5 +7,6 @@ export * from "./cache.js";
 export * from "./observer.js";
 export * from "./secrets.js";
 export * from "./project-config.js";
+export * from "./agents.js";
 export * from "./handlers/foreach.js";
 export * from "./handlers/run-workflow.js";

package/dist/index.js

@@ -7,5 +7,6 @@ export * from "./cache.js";
 export * from "./observer.js";
 export * from "./secrets.js";
 export * from "./project-config.js";
+export * from "./agents.js";
 export * from "./handlers/foreach.js";
 export * from "./handlers/run-workflow.js";

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import type { AgentRunner, McpServerRef } from "@agentic-surfaces/agent";
+import type { AgentDefinition } from "./agents.js";
 export type { AgentRunner, McpServerRef };
 export type NodeType = "trigger.cron" | "trigger.webhook" | "trigger.command" | "task.http" | "task.transform" | "task.branch" | "task.run-workflow" | "task.foreach" | "agent.run";
 export interface RetryPolicy {
@@ -46,6 +47,7 @@ export interface Services {
         mcpServers?: McpServerRef[];
     };
     runWorkflow?: (name: string, payload: unknown) => Promise<Map<string, unknown>>;
+    agents?: Map<string, AgentDefinition>;
 }
 export interface RunContext {
     workflow: Workflow;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentic-surfaces/core",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "type": "module",
   "license": "MIT",
   "publishConfig": {
@@ -23,7 +23,7 @@
     "jsonata": "^2.2.1",
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
-    "@agentic-surfaces/agent": "0.1.8"
+    "@agentic-surfaces/agent": "0.1.10"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",