agent-worker 0.16.0 → 0.17.0

package/dist/cli/index.mjs

@@ -2,10 +2,10 @@
 import { A as parseModel, I as getDefaultModel, L as isAutoProvider, P as createModelAsync, R as resolveModelFallback, a as createMockBackend, j as FRONTIER_MODELS, k as normalizeBackendType, n as createBackend } from "../backends-D7DT0uox.mjs";
 import { t as createTool } from "../create-tool-gcUuI1FD.mjs";
 import { generateText, stepCountIs, tool } from "ai";
-import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from "node:fs";
-import { dirname, isAbsolute, join, relative } from "node:path";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { appendFile, mkdir, open, readFile, readdir, stat, unlink, writeFile } from "node:fs/promises";
-import { stringify } from "yaml";
+import { parse, stringify } from "yaml";
 import { z } from "zod";
 import { homedir } from "node:os";
 import { execSync, spawn } from "node:child_process";
@@ -21,6 +21,7 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 import { MockLanguageModelV3, mockValues } from "ai/test";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { z as z$1 } from "zod/v4";
 
 //#region rolldown:runtime
 var __defProp = Object.defineProperty;
@@ -1709,76 +1710,106 @@ function formatInbox(inbox) {
 		return `- [${time}] From @${m.entry.from}${priority}${dm}: ${m.entry.content}`;
 	}).join("\n");
 }
+/** Project context (what codebase to work on) */
+const projectSection = (ctx) => `## Project\nWorking on: ${ctx.projectDir}`;
+/** Inbox (unread messages for this agent) */
+const inboxSection = (ctx) => {
+	const count = ctx.inbox.length;
+	return `## Inbox (${count} ${count === 1 ? "message" : "messages"} for you)\n${formatInbox(ctx.inbox)}`;
+};
+/** Recent activity hint (use tool instead of injecting messages) */
+const activitySection = () => "## Recent Activity\nUse channel_read tool to view recent channel messages and conversation context if needed.";
+/** Shared document section */
+const documentSection = (ctx) => ctx.documentContent ? `## Shared Document\n${ctx.documentContent}` : null;
+/** Retry notice */
+const retrySection = (ctx) => ctx.retryAttempt > 1 ? `## Note\nThis is retry attempt ${ctx.retryAttempt}. Previous attempt failed.` : null;
+/** MCP tool instructions */
+const instructionsSection = (ctx) => {
+	const lines = [];
+	lines.push("## Instructions");
+	lines.push("You are an agent in a multi-agent workflow. Communicate ONLY through the MCP tools below.");
+	lines.push("Your text output is NOT seen by other agents — you MUST use channel_send to communicate.");
+	lines.push("");
+	lines.push("### Channel Tools");
+	lines.push("- **channel_send**: Send a message to the shared channel. Use @agentname to mention/notify.");
+	lines.push("  Use the \"to\" parameter for private DMs: channel_send({ message: \"...\", to: \"bob\" })");
+	lines.push("- **channel_read**: Read recent channel messages (DMs and logs are auto-filtered).");
+	lines.push("");
+	lines.push("### Team Tools");
+	lines.push("- **team_members**: List all agents you can @mention. Pass includeStatus=true to see their current state and tasks.");
+	lines.push("- **team_doc_read/write/append/list/create**: Shared team documents.");
+	lines.push("");
+	lines.push("### Personal Tools");
+	lines.push("- **my_inbox**: Check your unread messages.");
+	lines.push("- **my_inbox_ack**: Acknowledge messages after processing (pass the latest message ID).");
+	lines.push("- **my_status_set**: Update your status. Call when starting work (state='running', task='...') or when done (state='idle').");
+	lines.push("");
+	lines.push("### Proposal & Voting Tools");
+	lines.push("- **team_proposal_create**: Create a proposal for team voting (types: election, decision, approval, assignment).");
+	lines.push("- **team_vote**: Cast your vote on an active proposal. You can change your vote by voting again.");
+	lines.push("- **team_proposal_status**: Check status of a proposal, or list all active proposals.");
+	lines.push("- **team_proposal_cancel**: Cancel a proposal you created.");
+	lines.push("");
+	lines.push("### Resource Tools");
+	lines.push("- **resource_create**: Store large content, get a reference (resource:id) for use anywhere.");
+	lines.push("- **resource_read**: Read resource content by ID.");
+	if (ctx.feedback) {
+		lines.push("");
+		lines.push("### Feedback Tool");
+		lines.push("- **feedback_submit**: Report workflow improvement needs — a missing tool, an awkward step, or a capability gap.");
+		lines.push("  Only use when you genuinely hit a pain point during your work.");
+	}
+	return lines.join("\n");
+};
+/** Workflow instructions (read → work → ack → exit) */
+const workflowSection = () => {
+	const lines = [];
+	lines.push("### Workflow");
+	lines.push("1. Read your inbox messages above");
+	lines.push("2. Do your assigned work using channel_send with @mentions");
+	lines.push("3. Acknowledge your inbox with my_inbox_ack");
+	lines.push("4. Exit when your task is complete");
+	return lines.join("\n");
+};
+/** Exit guidance (when to stop) */
+const exitSection = () => {
+	const lines = [];
+	lines.push("### IMPORTANT: When to stop");
+	lines.push("- Once your assigned task is complete, acknowledge your inbox and exit. Do NOT keep chatting.");
+	lines.push("- Do NOT send pleasantries (\"you're welcome\", \"glad to help\", \"thanks again\") — they trigger unnecessary cycles.");
+	lines.push("- Do NOT @mention another agent in your final message unless you need them to do more work.");
+	lines.push("- If you receive a thank-you or acknowledgment, just call my_inbox_ack and exit. Do not reply.");
+	return lines.join("\n");
+};
 /**
-* Build the complete agent prompt from run context
+* Default prompt sections — produces the same output as the original
+* monolithic buildAgentPrompt. New sections (soul, memory, todo) can
+* be inserted at specific positions without touching these.
+*/
+const DEFAULT_SECTIONS = [
+	projectSection,
+	inboxSection,
+	activitySection,
+	documentSection,
+	retrySection,
+	instructionsSection,
+	workflowSection,
+	exitSection
+];
+/**
+* Assemble prompt from sections. Joins non-null sections with blank lines.
+*/
+function assemblePrompt(sections, ctx) {
+	return sections.map((section) => section(ctx)).filter((content) => content !== null).join("\n\n");
+}
+/**
+* Build the complete agent prompt from run context.
+*
+* Uses the default section list. For custom section lists,
+* use assemblePrompt() directly.
 */
 function buildAgentPrompt(ctx) {
-	const sections = [];
-	sections.push("## Project");
-	sections.push(`Working on: ${ctx.projectDir}`);
-	sections.push("");
-	sections.push(`## Inbox (${ctx.inbox.length} message${ctx.inbox.length === 1 ? "" : "s"} for you)`);
-	sections.push(formatInbox(ctx.inbox));
-	sections.push("");
-	sections.push("## Recent Activity");
-	sections.push("Use channel_read tool to view recent channel messages and conversation context if needed.");
-	if (ctx.documentContent) {
-		sections.push("");
-		sections.push("## Shared Document");
-		sections.push(ctx.documentContent);
-	}
-	if (ctx.retryAttempt > 1) {
-		sections.push("");
-		sections.push(`## Note`);
-		sections.push(`This is retry attempt ${ctx.retryAttempt}. Previous attempt failed.`);
-	}
-	sections.push("");
-	sections.push("## Instructions");
-	sections.push("You are an agent in a multi-agent workflow. Communicate ONLY through the MCP tools below.");
-	sections.push("Your text output is NOT seen by other agents — you MUST use channel_send to communicate.");
-	sections.push("");
-	sections.push("### Channel Tools");
-	sections.push("- **channel_send**: Send a message to the shared channel. Use @agentname to mention/notify.");
-	sections.push("  Use the \"to\" parameter for private DMs: channel_send({ message: \"...\", to: \"bob\" })");
-	sections.push("- **channel_read**: Read recent channel messages (DMs and logs are auto-filtered).");
-	sections.push("");
-	sections.push("### Team Tools");
-	sections.push("- **team_members**: List all agents you can @mention. Pass includeStatus=true to see their current state and tasks.");
-	sections.push("- **team_doc_read/write/append/list/create**: Shared team documents.");
-	sections.push("");
-	sections.push("### Personal Tools");
-	sections.push("- **my_inbox**: Check your unread messages.");
-	sections.push("- **my_inbox_ack**: Acknowledge messages after processing (pass the latest message ID).");
-	sections.push("- **my_status_set**: Update your status. Call when starting work (state='running', task='...') or when done (state='idle').");
-	sections.push("");
-	sections.push("### Proposal & Voting Tools");
-	sections.push("- **team_proposal_create**: Create a proposal for team voting (types: election, decision, approval, assignment).");
-	sections.push("- **team_vote**: Cast your vote on an active proposal. You can change your vote by voting again.");
-	sections.push("- **team_proposal_status**: Check status of a proposal, or list all active proposals.");
-	sections.push("- **team_proposal_cancel**: Cancel a proposal you created.");
-	sections.push("");
-	sections.push("### Resource Tools");
-	sections.push("- **resource_create**: Store large content, get a reference (resource:id) for use anywhere.");
-	sections.push("- **resource_read**: Read resource content by ID.");
-	if (ctx.feedback) {
-		sections.push("");
-		sections.push("### Feedback Tool");
-		sections.push("- **feedback_submit**: Report workflow improvement needs — a missing tool, an awkward step, or a capability gap.");
-		sections.push("  Only use when you genuinely hit a pain point during your work.");
-	}
-	sections.push("");
-	sections.push("### Workflow");
-	sections.push("1. Read your inbox messages above");
-	sections.push("2. Do your assigned work using channel_send with @mentions");
-	sections.push("3. Acknowledge your inbox with my_inbox_ack");
-	sections.push("4. Exit when your task is complete");
-	sections.push("");
-	sections.push("### IMPORTANT: When to stop");
-	sections.push("- Once your assigned task is complete, acknowledge your inbox and exit. Do NOT keep chatting.");
-	sections.push("- Do NOT send pleasantries (\"you're welcome\", \"glad to help\", \"thanks again\") — they trigger unnecessary cycles.");
-	sections.push("- Do NOT @mention another agent in your final message unless you need them to do more work.");
-	sections.push("- If you receive a thank-you or acknowledgment, just call my_inbox_ack and exit. Do not reply.");
-	return sections.join("\n");
+	return assemblePrompt(DEFAULT_SECTIONS, ctx);
 }
 
 //#endregion
@@ -2849,6 +2880,12 @@ var daemon_exports = /* @__PURE__ */ __exportAll({
 	createDaemonApp: () => createDaemonApp,
 	startDaemon: () => startDaemon
 });
+/** Key prefix for standalone agent workflow handles */
+const STANDALONE_PREFIX = "standalone:";
+/** Build a workflow key for standalone agents */
+function standaloneKey(agentName) {
+	return `${STANDALONE_PREFIX}${agentName}`;
+}
 let state = null;
 let shuttingDown = false;
 const mcpSessions = /* @__PURE__ */ new Map();
@@ -2856,6 +2893,10 @@ async function gracefulShutdown() {
 	if (shuttingDown) return;
 	shuttingDown = true;
 	if (state) {
+		for (const [, loop] of state.loops) try {
+			await loop.stop();
+		} catch {}
+		state.loops.clear();
 		for (const [, wf] of state.workflows) try {
 			await wf.shutdown();
 		} catch {}
@@ -2877,8 +2918,8 @@ async function parseJsonBody(c) {
 		return null;
 	}
 }
-/** Map AgentConfig to the ResolvedAgent type needed by the factory */
-function configToResolvedAgent(cfg) {
+/** Map AgentConfig to the ResolvedWorkflowAgent type needed by the factory */
+function configToResolvedWorkflowAgent(cfg) {
 	return {
 		backend: cfg.backend,
 		model: cfg.model,
@@ -2888,10 +2929,16 @@ function configToResolvedAgent(cfg) {
 	};
 }
 /**
-* Find an agent's loop across all workflows.
-* Returns the loop if the agent exists in any workflow.
+* Find an agent's loop.
+* First checks daemon-level loops (standalone agents),
+* then falls back to workflow-scoped loops (workflow agents).
 */
 function findLoop(s, agentName) {
+	const daemonLoop = s.loops.get(agentName);
+	if (daemonLoop) return {
+		loop: daemonLoop,
+		workflow: s.workflows.get(standaloneKey(agentName)) ?? null
+	};
 	for (const wf of s.workflows.values()) {
 		const l = wf.loops.get(agentName);
 		if (l) return {
@@ -2902,9 +2949,12 @@ function findLoop(s, agentName) {
 	return null;
 }
 /**
-* Ensure a standalone agent has a workflow + loop.
+* Ensure a standalone agent has a loop + runtime.
 * Creates the infrastructure lazily on first call (starts MCP server, etc.).
 *
+* The loop is stored in `s.loops` (daemon-owned).
+* A WorkflowHandle is still created for runtime resource management (MCP, context).
+*
 * This is the bridge between POST /agents (stores config only) and
 * POST /run or /serve (needs a loop to execute).
 */
@@ -2913,11 +2963,13 @@ async function ensureAgentLoop(s, agentName) {
 	if (existing) return existing;
 	const cfg = s.configs.get(agentName);
 	if (!cfg) throw new Error(`Agent not found: ${agentName}`);
-	const agentDef = configToResolvedAgent(cfg);
-	const wfKey = `standalone:${agentName}`;
+	const agentDef = configToResolvedWorkflowAgent(cfg);
+	const wfKey = standaloneKey(agentName);
+	const workflowName = cfg.workflow ?? "global";
+	const workflowTag = cfg.tag ?? "main";
 	const runtime = await createMinimalRuntime({
-		workflowName: cfg.workflow,
-		tag: cfg.tag,
+		workflowName,
+		tag: workflowTag,
 		agentNames: [agentName]
 	});
 	let loop;
@@ -2931,10 +2983,12 @@ async function ensureAgentLoop(s, agentName) {
 		await runtime.shutdown();
 		throw err;
 	}
+	s.loops.set(agentName, loop);
 	const handle = {
-		name: cfg.workflow,
-		tag: cfg.tag,
+		name: workflowName,
+		tag: workflowTag,
 		key: wfKey,
+		standalone: true,
 		agents: [agentName],
 		loops: new Map([[agentName, loop]]),
 		contextProvider: runtime.contextProvider,
@@ -2978,7 +3032,7 @@ function createDaemonApp(options) {
 		const s = getState();
 		if (!s) return c.json({ status: "unavailable" }, 503);
 		const standaloneAgents = [...s.configs.keys()];
-		const workflowList = [...s.workflows.values()].map((wf) => ({
+		const workflowList = [...s.workflows.values()].filter((wf) => !wf.standalone).map((wf) => ({
 			name: wf.name,
 			tag: wf.tag,
 			agents: wf.agents
@@ -3032,7 +3086,7 @@ function createDaemonApp(options) {
 		if (!s) return c.json({ error: "Not ready" }, 503);
 		const body = await parseJsonBody(c);
 		if (!body || typeof body !== "object") return c.json({ error: "Invalid JSON body" }, 400);
-		const { name, model, system, backend = "default", provider, workflow = "global", tag = "main", schedule } = body;
+		const { name, model, system, backend = "default", provider, workflow, tag, schedule } = body;
 		if (!name || !model || !system) return c.json({ error: "name, model, system required" }, 400);
 		if (s.configs.has(name)) return c.json({ error: `Agent already exists: ${name}` }, 409);
 		const agentConfig = {
@@ -3077,7 +3131,14 @@ function createDaemonApp(options) {
 		if (!s) return c.json({ error: "Not ready" }, 503);
 		const name = c.req.param("name");
 		if (!s.configs.delete(name)) return c.json({ error: "Agent not found" }, 404);
-		const wfKey = `standalone:${name}`;
+		const daemonLoop = s.loops.get(name);
+		if (daemonLoop) {
+			try {
+				await daemonLoop.stop();
+			} catch {}
+			s.loops.delete(name);
+		}
+		const wfKey = standaloneKey(name);
 		const wf = s.workflows.get(wfKey);
 		if (wf) {
 			try {
@@ -3231,7 +3292,7 @@ function createDaemonApp(options) {
 		const key = `${workflowName}:${tag}`;
 		if (s.workflows.has(key)) return c.json({ error: `Workflow already running: ${key}` }, 409);
 		try {
-			const { runWorkflowWithLoops } = await import("../runner-IkYhcbio.mjs");
+			const { runWorkflowWithLoops } = await import("../runner-BmT0Y8MD.mjs");
 			const result = await runWorkflowWithLoops({
 				workflow,
 				workflowName,
@@ -3270,7 +3331,7 @@ function createDaemonApp(options) {
 	app.get("/workflows", (c) => {
 		const s = getState();
 		if (!s) return c.json({ error: "Not ready" }, 503);
-		const workflows = [...s.workflows.values()].map((wf) => {
+		const workflows = [...s.workflows.values()].filter((wf) => !wf.standalone).map((wf) => {
 			const agentStates = {};
 			for (const [name, loop] of wf.loops) agentStates[name] = loop.state;
 			return {
@@ -3334,6 +3395,7 @@ async function startDaemon(config = {}) {
 	});
 	state = {
 		configs: /* @__PURE__ */ new Map(),
+		loops: /* @__PURE__ */ new Map(),
 		workflows: /* @__PURE__ */ new Map(),
 		store,
 		server,
@@ -3541,6 +3603,380 @@ function outputJson(data) {
 	console.log(JSON.stringify(data, null, 2));
 }
 
+//#endregion
+//#region src/agent/definition.ts
+/**
+* AgentDefinition — Top-level persistent agent identity.
+*
+* This is the NEW AgentDefinition from AGENT-TOP-LEVEL architecture.
+* It describes WHO an agent is (prompt, soul, context) — not how it runs in a workflow.
+*
+* Loaded from .agents/*.yaml files. Workflows reference agents by name.
+*
+* Distinct from:
+*   - WorkflowAgentDef (workflow/types.ts) — inline agent config within a workflow
+*   - AgentConfig (agent/config.ts)        — runtime config for daemon-created agents
+*/
+/**
+* Standard subdirectories within an agent's context directory.
+* Created automatically when the agent is loaded.
+*/
+const CONTEXT_SUBDIRS = [
+	"memory",
+	"notes",
+	"conversations",
+	"todo"
+];
+const AgentSoulSchema = z$1.object({
+	role: z$1.string().optional(),
+	expertise: z$1.array(z$1.string()).optional(),
+	style: z$1.string().optional(),
+	principles: z$1.array(z$1.string()).optional()
+}).passthrough();
+const ProviderConfigSchema = z$1.object({
+	name: z$1.string(),
+	base_url: z$1.string().optional(),
+	api_key: z$1.string().optional()
+}).passthrough();
+const AgentPromptConfigSchema = z$1.union([z$1.object({
+	system: z$1.string(),
+	system_file: z$1.undefined().optional()
+}), z$1.object({
+	system_file: z$1.string(),
+	system: z$1.undefined().optional()
+})]);
+const AgentContextConfigSchema = z$1.object({
+	dir: z$1.string().optional(),
+	thin_thread: z$1.number().int().min(1).optional()
+});
+const ScheduleConfigSchema = z$1.object({
+	wakeup: z$1.union([z$1.string(), z$1.number()]),
+	prompt: z$1.string().optional()
+});
+const AgentDefinitionSchema = z$1.object({
+	name: z$1.string().min(1),
+	model: z$1.string().min(1),
+	backend: z$1.enum([
+		"sdk",
+		"claude",
+		"cursor",
+		"codex",
+		"opencode",
+		"mock"
+	]).optional(),
+	provider: z$1.union([z$1.string(), ProviderConfigSchema]).optional(),
+	prompt: AgentPromptConfigSchema,
+	soul: AgentSoulSchema.optional(),
+	context: AgentContextConfigSchema.optional(),
+	max_tokens: z$1.number().int().positive().optional(),
+	max_steps: z$1.number().int().positive().optional(),
+	schedule: ScheduleConfigSchema.optional()
+});
+
+//#endregion
+//#region src/agent/agent-handle.ts
+/**
+* AgentHandle — Runtime wrapper for an agent definition + persistent context.
+*
+* Created by AgentRegistry when an agent is loaded. Provides:
+*   - Context directory management (memory/, notes/, conversations/, todo/)
+*   - Read/write operations for personal context
+*   - State tracking (idle, running, stopped, error)
+*
+* Phase 1 scope: context directory + read/write ops.
+* Phase 3 adds: loop, workspaces, threads.
+*/
+var AgentHandle = class {
+	/** Agent definition (from YAML) */
+	definition;
+	/** Absolute path to agent's persistent context directory */
+	contextDir;
+	/** Current agent state */
+	state = "idle";
+	constructor(definition, contextDir) {
+		this.definition = definition;
+		this.contextDir = contextDir;
+	}
+	/** Agent name (convenience accessor) */
+	get name() {
+		return this.definition.name;
+	}
+	/**
+	* Ensure the context directory and all subdirectories exist.
+	* Called on agent load/creation. Idempotent.
+	*/
+	ensureContextDir() {
+		for (const sub of CONTEXT_SUBDIRS) mkdirSync(join(this.contextDir, sub), { recursive: true });
+	}
+	/**
+	* Read all memory entries as key-value records.
+	* Memory files are YAML in memory/<key>.yaml.
+	*/
+	async readMemory() {
+		const memDir = join(this.contextDir, "memory");
+		if (!existsSync(memDir)) return {};
+		const result = {};
+		const files = await readdir(memDir);
+		for (const file of files) {
+			if (!file.endsWith(".yaml") && !file.endsWith(".yml")) continue;
+			const key = basename(file).replace(/\.ya?ml$/i, "");
+			try {
+				result[key] = parse(await readFile(join(memDir, file), "utf-8"));
+			} catch (err) {
+				console.warn(`Skipping malformed memory file ${file}:`, err);
+			}
+		}
+		return result;
+	}
+	/**
+	* Write a memory entry. Creates/overwrites memory/<key>.yaml.
+	*/
+	async writeMemory(key, value) {
+		const memDir = join(this.contextDir, "memory");
+		await mkdir(memDir, { recursive: true });
+		await writeFile(join(memDir, `${key}.yaml`), stringify(value));
+	}
+	/**
+	* Read agent's notes, most recent first.
+	* Notes are markdown files in notes/.
+	*/
+	async readNotes(limit) {
+		const notesDir = join(this.contextDir, "notes");
+		if (!existsSync(notesDir)) return [];
+		const files = (await readdir(notesDir)).filter((f) => f.endsWith(".md")).sort().reverse();
+		const selected = limit ? files.slice(0, limit) : files;
+		return Promise.all(selected.map((f) => readFile(join(notesDir, f), "utf-8")));
+	}
+	/**
+	* Append a note. Creates notes/<date>-<slug>.md.
+	*/
+	async appendNote(content, slug) {
+		const notesDir = join(this.contextDir, "notes");
+		await mkdir(notesDir, { recursive: true });
+		const filename = `${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}-${slug ?? `note-${Date.now().toString(36)}`}.md`;
+		await writeFile(join(notesDir, filename), content);
+		return filename;
+	}
+	/**
+	* Read active todos from todo/index.md.
+	* Returns lines that look like incomplete tasks: "- [ ] ..."
+	*/
+	async readTodos() {
+		const todoFile = join(this.contextDir, "todo", "index.md");
+		if (!existsSync(todoFile)) return [];
+		return (await readFile(todoFile, "utf-8")).split("\n").filter((line) => line.match(/^\s*-\s*\[\s*\]/)).map((line) => line.replace(/^\s*-\s*\[\s*\]\s*/, "").trim());
+	}
+	/**
+	* Write the full todo list. Replaces todo/index.md.
+	*/
+	async writeTodos(todos) {
+		const todoDir = join(this.contextDir, "todo");
+		await mkdir(todoDir, { recursive: true });
+		const content = todos.map((t) => `- [ ] ${t}`).join("\n") + "\n";
+		await writeFile(join(todoDir, "index.md"), content);
+	}
+};
+
+//#endregion
+//#region src/agent/yaml-parser.ts
+/**
+* Agent YAML Parser — Load agent definitions from .agents/*.yaml files.
+*
+* Handles:
+*   - Single file: parseAgentFile("path/to/alice.yaml")
+*   - Directory:   discoverAgents("path/to/project") → scans .agents/*.yaml
+*   - Validation:  Zod schema + semantic checks (system XOR system_file)
+*   - Resolution:  system_file → reads content into system (relative to YAML dir)
+*
+* The name field is optional in YAML — defaults to filename (without .yaml).
+*/
+/** Default directory for agent definitions (relative to project root) */
+const AGENTS_DIR = ".agents";
+/**
+* Parse an agent definition from a YAML file.
+*
+* Validates the schema, resolves system_file to inline content,
+* and infers name from filename if not specified.
+*
+* @throws Error if file doesn't exist, YAML is malformed, or validation fails.
+*/
+function parseAgentFile(filePath) {
+	if (!existsSync(filePath)) throw new Error(`Agent file not found: ${filePath}`);
+	const data = parse(readFileSync(filePath, "utf-8"));
+	if (!data || typeof data !== "object") throw new Error(`Invalid YAML in ${filePath}: expected an object`);
+	const obj = data;
+	if (!obj.name) obj.name = basename(filePath).replace(/\.ya?ml$/i, "");
+	const result = AgentDefinitionSchema.safeParse(obj);
+	if (!result.success) {
+		const issues = result.error.issues.map((i) => `  ${i.path.join(".")}: ${i.message}`).join("\n");
+		throw new Error(`Invalid agent definition in ${filePath}:\n${issues}`);
+	}
+	const def = result.data;
+	if (def.prompt.system_file) {
+		const promptPath = join(dirname(filePath), def.prompt.system_file);
+		if (!existsSync(promptPath)) throw new Error(`system_file not found: ${def.prompt.system_file} (resolved: ${promptPath})`);
+		const content = readFileSync(promptPath, "utf-8");
+		return {
+			...def,
+			prompt: { system: content }
+		};
+	}
+	return def;
+}
+/**
+* Discover all agent YAML files in a project's .agents/ directory.
+* Returns parsed and validated definitions.
+*
+* Non-fatal: logs warnings for invalid files, skips them.
+*
+* @param projectDir - Project root directory
+* @param log - Optional warning logger (default: console.warn)
+* @returns Array of valid agent definitions
+*/
+function discoverAgents(projectDir, log) {
+	const agentsDir = join(projectDir, AGENTS_DIR);
+	if (!existsSync(agentsDir)) return [];
+	const warn = log ?? console.warn;
+	const agents = [];
+	let entries;
+	try {
+		entries = readdirSync(agentsDir);
+	} catch {
+		return [];
+	}
+	for (const entry of entries) {
+		if (!entry.endsWith(".yaml") && !entry.endsWith(".yml")) continue;
+		const filePath = join(agentsDir, entry);
+		try {
+			agents.push(parseAgentFile(filePath));
+		} catch (err) {
+			warn(`Skipping ${entry}: ${err instanceof Error ? err.message : String(err)}`);
+		}
+	}
+	return agents;
+}
+/**
+* Serialize an agent definition to YAML string.
+* Used by CLI `agent create` to write .agents/<name>.yaml.
+*/
+function serializeAgent(def) {
+	const obj = {
+		name: def.name,
+		model: def.model
+	};
+	if (def.backend) obj.backend = def.backend;
+	if (def.provider) obj.provider = def.provider;
+	obj.prompt = def.prompt;
+	if (def.soul) obj.soul = def.soul;
+	if (def.context) obj.context = def.context;
+	if (def.max_tokens) obj.max_tokens = def.max_tokens;
+	if (def.max_steps) obj.max_steps = def.max_steps;
+	if (def.schedule) obj.schedule = def.schedule;
+	return stringify(obj, { lineWidth: 120 });
+}
+
+//#endregion
+//#region src/agent/agent-registry.ts
+/**
+* AgentRegistry — Loads and manages top-level agent definitions.
+*
+* Responsibilities:
+*   - Discover agents from .agents/*.yaml
+*   - Load definitions → create AgentHandles
+*   - Register/unregister agents at runtime
+*   - Ensure context directories exist
+*   - Provide agent lookup by name
+*
+* Owned by the daemon. One registry per daemon process.
+*/
+var AgentRegistry = class {
+	/** Loaded agent handles, keyed by name */
+	agents = /* @__PURE__ */ new Map();
+	/** Project root directory */
+	projectDir;
+	/** Agents directory (.agents/) */
+	agentsDir;
+	constructor(projectDir) {
+		this.projectDir = projectDir;
+		this.agentsDir = join(projectDir, AGENTS_DIR);
+	}
+	/**
+	* Load all agents from .agents/*.yaml.
+	* Skips invalid files (logs warnings).
+	* Creates context directories for each loaded agent.
+	*/
+	loadFromDisk(log) {
+		const defs = discoverAgents(this.projectDir, log);
+		for (const def of defs) this.registerDefinition(def);
+	}
+	/**
+	* Register an agent definition. Creates AgentHandle + ensures context dir.
+	* Overwrites existing agent with same name (reload semantics).
+	*/
+	registerDefinition(def) {
+		const handle = new AgentHandle(def, this.resolveContextDir(def));
+		handle.ensureContextDir();
+		this.agents.set(def.name, handle);
+		return handle;
+	}
+	/**
+	* Create a new agent: write YAML file + register.
+	* @throws Error if agent already exists on disk.
+	*/
+	create(def) {
+		const yamlPath = this.agentYamlPath(def.name);
+		if (existsSync(yamlPath)) throw new Error(`Agent file already exists: ${yamlPath}`);
+		mkdirSync(this.agentsDir, { recursive: true });
+		writeFileSync(yamlPath, serializeAgent(def));
+		return this.registerDefinition(def);
+	}
+	/**
+	* Delete an agent: remove YAML file + context directory + unregister.
+	* @returns true if agent existed and was deleted.
+	*/
+	delete(name) {
+		const handle = this.agents.get(name);
+		if (!handle) return false;
+		this.agents.delete(name);
+		const yamlPath = this.agentYamlPath(name);
+		if (existsSync(yamlPath)) try {
+			unlinkSync(yamlPath);
+		} catch {}
+		if (existsSync(handle.contextDir)) try {
+			rmSync(handle.contextDir, {
+				recursive: true,
+				force: true
+			});
+		} catch {}
+		return true;
+	}
+	/** Get agent handle by name */
+	get(name) {
+		return this.agents.get(name);
+	}
+	/** Check if agent exists */
+	has(name) {
+		return this.agents.has(name);
+	}
+	/** List all registered agent handles */
+	list() {
+		return [...this.agents.values()];
+	}
+	/** Number of registered agents */
+	get size() {
+		return this.agents.size;
+	}
+	/** Resolve agent's context directory (absolute path) */
+	resolveContextDir(def) {
+		if (def.context?.dir) return join(this.projectDir, def.context.dir);
+		return join(this.agentsDir, def.name);
+	}
+	/** Path to agent's YAML file */
+	agentYamlPath(name) {
+		return join(this.agentsDir, `${name}.yaml`);
+	}
+};
+
 //#endregion
 //#region src/cli/commands/agent.ts
 var agent_exports = /* @__PURE__ */ __exportAll({
@@ -3655,7 +4091,7 @@ Examples:
 			return;
 		}
 		for (const a of agents) {
-			const wf = a.tag === "main" ? `@${a.workflow}` : `@${a.workflow}:${a.tag}`;
+			const wf = a.workflow ? a.tag === "main" ? `@${a.workflow}` : `@${a.workflow}:${a.tag}` : "";
 			const info = a.model || a.state || "";
 			console.log(`${a.name.padEnd(12)} ${info.padEnd(30)} ${wf}`);
 		}
@@ -3753,6 +4189,121 @@ Examples:
 			process.exit(1);
 		} else console.log(res.content ?? JSON.stringify(res));
 	});
+	const agentCmd = program.command("agent").description("Manage persistent agent definitions (.agents/*.yaml)");
+	agentCmd.command("create <name>").description("Create a persistent agent definition").option("-m, --model <model>", `Model (default: ${getDefaultModel()})`).addOption(new Option("-b, --backend <type>", "Backend type").choices([
+		"sdk",
+		"claude",
+		"codex",
+		"cursor",
+		"opencode",
+		"mock"
+	]).default(void 0)).option("-s, --system <prompt>", "System prompt").option("-f, --system-file <file>", "Read system prompt from file").option("--role <role>", "Soul: agent role").option("--expertise <items>", "Soul: expertise (comma-separated)").option("--style <style>", "Soul: communication style").option("--dir <path>", "Project directory", ".").option("--json", "Output as JSON").addHelpText("after", `
+Creates .agents/<name>.yaml and context directory (.agents/<name>/).
+
+Examples:
+  $ agent-worker agent create alice -m anthropic/claude-sonnet-4-5 -s "You are a code reviewer."
+  $ agent-worker agent create bob --role developer --expertise "typescript,testing"
+  $ agent-worker agent create coder -f ./prompts/coder.md
+      `).action(async (name, options) => {
+		const registry = new AgentRegistry(resolve(options.dir));
+		let system = options.system ?? "You are a helpful assistant.";
+		if (options.systemFile) system = readFileSync(options.systemFile, "utf-8");
+		const def = {
+			name,
+			model: options.model || getDefaultModel(),
+			prompt: { system }
+		};
+		if (options.backend) def.backend = options.backend;
+		if (options.role || options.expertise || options.style) {
+			def.soul = {};
+			if (options.role) def.soul.role = options.role;
+			if (options.expertise) def.soul.expertise = options.expertise.split(",").map((s) => s.trim());
+			if (options.style) def.soul.style = options.style;
+		}
+		try {
+			const handle = registry.create(def);
+			if (options.json) outputJson({
+				name,
+				model: def.model,
+				contextDir: handle.contextDir
+			});
+			else {
+				console.log(`Created: .agents/${name}.yaml`);
+				console.log(`Context: ${handle.contextDir}`);
+			}
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			console.error(`Error: ${msg}`);
+			process.exit(1);
+		}
+	});
+	agentCmd.command("list").description("List persistent agent definitions").option("--dir <path>", "Project directory", ".").option("--json", "Output as JSON").action(async (options) => {
+		const registry = new AgentRegistry(resolve(options.dir));
+		registry.loadFromDisk();
+		const agents = registry.list();
+		if (options.json) {
+			outputJson({ agents: agents.map((h) => ({
+				name: h.name,
+				model: h.definition.model,
+				backend: h.definition.backend,
+				soul: h.definition.soul,
+				contextDir: h.contextDir
+			})) });
+			return;
+		}
+		if (agents.length === 0) {
+			console.log("No agent definitions found in .agents/");
+			return;
+		}
+		for (const h of agents) {
+			const soul = h.definition.soul?.role ? ` (${h.definition.soul.role})` : "";
+			console.log(`${h.name.padEnd(16)} ${h.definition.model}${soul}`);
+		}
+	});
+	agentCmd.command("info <name>").description("Show agent definition details").option("--dir <path>", "Project directory", ".").option("--json", "Output as JSON").action(async (name, options) => {
+		const registry = new AgentRegistry(resolve(options.dir));
+		registry.loadFromDisk();
+		const handle = registry.get(name);
+		if (!handle) {
+			console.error(`Agent not found: ${name}`);
+			process.exit(1);
+		}
+		const def = handle.definition;
+		if (options.json) {
+			outputJson({
+				...def,
+				contextDir: handle.contextDir
+			});
+			return;
+		}
+		console.log(`Name:    ${def.name}`);
+		console.log(`Model:   ${def.model}`);
+		if (def.backend) console.log(`Backend: ${def.backend}`);
+		if (def.prompt.system) {
+			const preview = def.prompt.system.length > 80 ? def.prompt.system.slice(0, 77) + "..." : def.prompt.system;
+			console.log(`Prompt:  ${preview}`);
+		}
+		if (def.soul) {
+			if (def.soul.role) console.log(`Role:    ${def.soul.role}`);
+			if (def.soul.expertise) console.log(`Expert:  ${def.soul.expertise.join(", ")}`);
+			if (def.soul.style) console.log(`Style:   ${def.soul.style}`);
+			if (def.soul.principles) {
+				console.log(`Principles:`);
+				for (const p of def.soul.principles) console.log(`  - ${p}`);
+			}
+		}
+		console.log(`Context: ${handle.contextDir}`);
+	});
+	agentCmd.command("delete <name>").description("Delete agent definition and context").option("--dir <path>", "Project directory", ".").action(async (name, options) => {
+		const registry = new AgentRegistry(resolve(options.dir));
+		registry.loadFromDisk();
+		if (!registry.has(name)) {
+			console.error(`Agent not found: ${name}`);
+			process.exit(1);
+		}
+		registry.delete(name);
+		console.log(`Deleted: ${name}`);
+	});
 }
 
 //#endregion
@@ -3882,7 +4433,7 @@ Note: Workflow name is inferred from YAML 'name' field or filename.
       Workflow-defined params (see 'params:' in YAML) are passed after '--'.
       Set GITHUB_TOKEN env var to access private repositories.
     `).action(async (file, options) => {
-		const { parseWorkflowFile, parseWorkflowParams, formatParamHelp, runWorkflowWithLoops } = await import("../workflow-Ctto0bJt.mjs");
+		const { parseWorkflowFile, parseWorkflowParams, formatParamHelp, runWorkflowWithLoops } = await import("../workflow-LOZUlaDo.mjs");
 		const tag = options.tag || DEFAULT_TAG;
 		const parsedWorkflow = await parseWorkflowFile(file, { tag });
 		const workflowName = parsedWorkflow.name;
@@ -3905,7 +4456,7 @@ Note: Workflow name is inferred from YAML 'name' field or filename.
 			isCleaningUp = true;
 			console.log("\nInterrupted, cleaning up...");
 			if (loops) {
-				const { shutdownLoops } = await import("../workflow-Ctto0bJt.mjs");
+				const { shutdownLoops } = await import("../workflow-LOZUlaDo.mjs");
 				const { createSilentLogger } = await Promise.resolve().then(() => logger_exports);
 				await shutdownLoops(loops, createSilentLogger());
 			}
@@ -3980,7 +4531,7 @@ Workflow runs inside the daemon. Use ls/stop to manage:
 Note: Workflow name is inferred from YAML 'name' field or filename.
       Workflow-defined params (see 'params:' in YAML) are passed after '--'.
     `).action(async (file, options) => {
-		const { parseWorkflowFile, parseWorkflowParams, formatParamHelp } = await import("../workflow-Ctto0bJt.mjs");
+		const { parseWorkflowFile, parseWorkflowParams, formatParamHelp } = await import("../workflow-LOZUlaDo.mjs");
 		const { ensureDaemon } = await Promise.resolve().then(() => agent_exports);
 		const tag = options.tag || DEFAULT_TAG;
 		const parsedWorkflow = await parseWorkflowFile(file, { tag });
@@ -4209,7 +4760,7 @@ Examples:
   $ agent-worker doc read @review:pr-123     # Read specific workflow:tag document
     `).action(async (targetInput) => {
 		const dir = await resolveDir(targetInput);
-		const { createFileContextProvider } = await import("../context-CdcZpO-0.mjs");
+		const { createFileContextProvider } = await import("../context-CoRTddGx.mjs");
 		const content = await createFileContextProvider(dir, []).readDocument();
 		console.log(content || "(empty document)");
 	});
@@ -4227,7 +4778,7 @@ Examples:
 			process.exit(1);
 		}
 		const dir = await resolveDir(targetInput);
-		const { createFileContextProvider } = await import("../context-CdcZpO-0.mjs");
+		const { createFileContextProvider } = await import("../context-CoRTddGx.mjs");
 		await createFileContextProvider(dir, []).writeDocument(content);
 		console.log("Document written");
 	});
@@ -4245,7 +4796,7 @@ Examples:
 			process.exit(1);
 		}
 		const dir = await resolveDir(targetInput);
-		const { createFileContextProvider } = await import("../context-CdcZpO-0.mjs");
+		const { createFileContextProvider } = await import("../context-CoRTddGx.mjs");
 		await createFileContextProvider(dir, []).appendDocument(content);
 		console.log("Content appended");
 	});
@@ -4259,7 +4810,7 @@ async function resolveDir(targetInput) {
 
 //#endregion
 //#region package.json
-var version = "0.16.0";
+var version = "0.17.0";
 
 //#endregion
 //#region src/cli/index.ts
@@ -4289,4 +4840,4 @@ registerDocCommands(program);
 program.parse();
 
 //#endregion
-export { MENTION_PATTERN as A, formatProposal as B, DefaultDocumentStore as C, MemoryStorage as D, FileStorage as E, createResourceRef as F, getAgentId as G, createLogTool as H, extractMentions as I, EventLog as K, generateResourceId as L, RESOURCE_PREFIX$1 as M, RESOURCE_SCHEME as N, ContextProviderImpl as O, calculatePriority as P, shouldUseResource as R, DefaultResourceStore as S, DefaultChannelStore as T, formatInbox$1 as U, formatProposalList as V, formatToolParams as W, FileContextProvider as _, getBackendByType as a, resolveContextDir as b, createAgentLoop as c, generateWorkflowMCPConfig as d, writeBackendMcpConfig as f, runWithHttp as g, LOOP_DEFAULTS as h, createSilentLogger as i, MESSAGE_LENGTH_THRESHOLD as j, CONTEXT_DEFAULTS as k, runSdkAgent as l, formatInbox as m, createWiredLoop as n, getBackendForModel as o, buildAgentPrompt as p, createChannelLogger as r, checkWorkflowIdle as s, createMinimalRuntime as t, runMockAgent as u, createFileContextProvider as v, DefaultInboxStore as w, DefaultStatusStore as x, getDefaultContextDir as y, createContextMCPServer as z };
+export { formatInbox$1 as $, resolveContextDir as A, MENTION_PATTERN as B, retrySection as C, FileContextProvider as D, runWithHttp as E, DefaultChannelStore as F, createResourceRef as G, RESOURCE_PREFIX$1 as H, FileStorage as I, shouldUseResource as J, extractMentions as K, MemoryStorage as L, DefaultResourceStore as M, DefaultDocumentStore as N, createFileContextProvider as O, DefaultInboxStore as P, createLogTool as Q, ContextProviderImpl as R, projectSection as S, LOOP_DEFAULTS as T, RESOURCE_SCHEME as U, MESSAGE_LENGTH_THRESHOLD as V, calculatePriority as W, formatProposal as X, createContextMCPServer as Y, formatProposalList as Z, documentSection as _, getBackendByType as a, inboxSection as b, createAgentLoop as c, generateWorkflowMCPConfig as d, formatToolParams as et, writeBackendMcpConfig as f, buildAgentPrompt as g, assemblePrompt as h, createSilentLogger as i, DefaultStatusStore as j, getDefaultContextDir as k, runSdkAgent as l, activitySection as m, createWiredLoop as n, EventLog as nt, getBackendForModel as o, DEFAULT_SECTIONS as p, generateResourceId as q, createChannelLogger as r, checkWorkflowIdle as s, createMinimalRuntime as t, getAgentId as tt, runMockAgent as u, exitSection as v, workflowSection as w, instructionsSection as x, formatInbox as y, CONTEXT_DEFAULTS as z };

package/dist/context-CoRTddGx.mjs

@@ -0,0 +1,4 @@
+import { $ as formatInbox, A as resolveContextDir, B as MENTION_PATTERN, D as FileContextProvider, F as DefaultChannelStore, G as createResourceRef, H as RESOURCE_PREFIX, I as FileStorage, J as shouldUseResource, K as extractMentions, L as MemoryStorage, M as DefaultResourceStore, N as DefaultDocumentStore, O as createFileContextProvider, P as DefaultInboxStore, Q as createLogTool, R as ContextProviderImpl, U as RESOURCE_SCHEME, V as MESSAGE_LENGTH_THRESHOLD, W as calculatePriority, X as formatProposal, Y as createContextMCPServer, Z as formatProposalList, et as formatToolParams, j as DefaultStatusStore, k as getDefaultContextDir, nt as EventLog, q as generateResourceId, tt as getAgentId, z as CONTEXT_DEFAULTS } from "./cli/index.mjs";
+import { n as createMemoryContextProvider, t as MemoryContextProvider } from "./memory-provider-Z9D8NdwS.mjs";
+
+export { createFileContextProvider };

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 import { LanguageModel } from "ai";
 import { BashToolkit, CreateBashToolOptions, createBashTool } from "bash-tool";
+import { z } from "zod/v4";
 
 //#region src/backends/model-maps.d.ts
 /**

package/dist/{memory-provider-ZLOKyCxA.mjs → memory-provider-Z9D8NdwS.mjs}

@@ -1,4 +1,4 @@
-import { C as DefaultDocumentStore, D as MemoryStorage, O as ContextProviderImpl, S as DefaultResourceStore, T as DefaultChannelStore, w as DefaultInboxStore, x as DefaultStatusStore } from "./cli/index.mjs";
+import { F as DefaultChannelStore, L as MemoryStorage, M as DefaultResourceStore, N as DefaultDocumentStore, P as DefaultInboxStore, R as ContextProviderImpl, j as DefaultStatusStore } from "./cli/index.mjs";
 
 //#region src/workflow/context/memory-provider.ts
 /**

package/dist/{runner-IkYhcbio.mjs → runner-BmT0Y8MD.mjs}

@@ -1,7 +1,7 @@
 import "./backends-D7DT0uox.mjs";
 import "./create-tool-gcUuI1FD.mjs";
-import { K as EventLog, _ as FileContextProvider, g as runWithHttp, i as createSilentLogger, n as createWiredLoop, r as createChannelLogger, s as checkWorkflowIdle, v as createFileContextProvider, z as createContextMCPServer } from "./cli/index.mjs";
-import { n as createMemoryContextProvider } from "./memory-provider-ZLOKyCxA.mjs";
+import { D as FileContextProvider, E as runWithHttp, O as createFileContextProvider, Y as createContextMCPServer, i as createSilentLogger, n as createWiredLoop, nt as EventLog, r as createChannelLogger, s as checkWorkflowIdle } from "./cli/index.mjs";
+import { n as createMemoryContextProvider } from "./memory-provider-Z9D8NdwS.mjs";
 import { existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";

package/dist/{workflow-Ctto0bJt.mjs → workflow-LOZUlaDo.mjs}

@@ -1,8 +1,8 @@
 import "./backends-D7DT0uox.mjs";
 import "./create-tool-gcUuI1FD.mjs";
-import { a as getBackendByType, b as resolveContextDir, c as createAgentLoop, d as generateWorkflowMCPConfig, f as writeBackendMcpConfig, h as LOOP_DEFAULTS, i as createSilentLogger, k as CONTEXT_DEFAULTS, l as runSdkAgent, m as formatInbox, n as createWiredLoop, o as getBackendForModel, p as buildAgentPrompt, r as createChannelLogger, s as checkWorkflowIdle, t as createMinimalRuntime, u as runMockAgent } from "./cli/index.mjs";
-import "./memory-provider-ZLOKyCxA.mjs";
-import { createWorkflowProvider, initWorkflow, n as interpolate, runWorkflowWithLoops, shutdownLoops, t as createContext } from "./runner-IkYhcbio.mjs";
+import { A as resolveContextDir, C as retrySection, S as projectSection, T as LOOP_DEFAULTS, _ as documentSection, a as getBackendByType, b as inboxSection, c as createAgentLoop, d as generateWorkflowMCPConfig, f as writeBackendMcpConfig, g as buildAgentPrompt, h as assemblePrompt, i as createSilentLogger, l as runSdkAgent, m as activitySection, n as createWiredLoop, o as getBackendForModel, p as DEFAULT_SECTIONS, r as createChannelLogger, s as checkWorkflowIdle, t as createMinimalRuntime, u as runMockAgent, v as exitSection, w as workflowSection, x as instructionsSection, y as formatInbox, z as CONTEXT_DEFAULTS } from "./cli/index.mjs";
+import "./memory-provider-Z9D8NdwS.mjs";
+import { createWorkflowProvider, initWorkflow, n as interpolate, runWorkflowWithLoops, shutdownLoops, t as createContext } from "./runner-BmT0Y8MD.mjs";
 import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { parse } from "yaml";
@@ -10,6 +10,13 @@ import { homedir } from "node:os";
 import { execFileSync } from "node:child_process";
 import { parseArgs } from "node:util";
 
+//#region src/workflow/types.ts
+/** Type guard: is this agent entry a reference to a global agent? */
+function isRefAgentEntry(entry) {
+	return "ref" in entry && typeof entry.ref === "string";
+}
+
+//#endregion
 //#region src/workflow/source.ts
 /**
 * Workflow source resolver — supports local files and remote GitHub references.
@@ -263,7 +270,8 @@ async function parseWorkflowFile(filePath, options) {
 	}
 	const name = raw.name || source.inferredName;
 	const agents = {};
-	for (const [agentName, agentDef] of Object.entries(raw.agents)) agents[agentName] = await resolveAgent(agentDef, source.readRelativeFile);
+	for (const [agentName, entry] of Object.entries(raw.agents)) if (isRefAgentEntry(entry)) agents[agentName] = resolveRefAgent(entry, options?.agentRegistry);
+	else agents[agentName] = await resolveInlineAgent(entry, source.readRelativeFile);
 	const context = resolveContext(raw.context, contextBaseDir, name, workflow, tag);
 	return {
 		name,
@@ -315,14 +323,14 @@ function resolveContext(config, workflowDir, workflowName, workflow, tag) {
 	};
 }
 /**
-* Resolve agent definition (load system prompt from file if needed).
+* Resolve an inline agent definition (load system prompt from file if needed).
 *
 * Uses a `readRelativeFile` function to abstract local vs remote file access.
 * Also transforms `wakeup` and `wakeup_prompt` fields into a `ScheduleConfig`
 * object, which is the format expected by the daemon and loop layers
 * for setting up periodic wakeup timers.
 */
-async function resolveAgent(agent, readRelativeFile) {
+async function resolveInlineAgent(agent, readRelativeFile) {
 	let resolvedSystemPrompt = agent.system_prompt;
 	if (resolvedSystemPrompt?.endsWith(".txt") || resolvedSystemPrompt?.endsWith(".md")) {
 		const content = await readRelativeFile(resolvedSystemPrompt);
@@ -336,7 +344,34 @@ async function resolveAgent(agent, readRelativeFile) {
 	return {
 		...agent,
 		resolvedSystemPrompt,
-		schedule
+		schedule,
+		isRef: false
+	};
+}
+/**
+* Resolve a ref agent entry — load from AgentRegistry, map to WorkflowAgentDef,
+* apply workflow overrides (prompt.append, max_tokens, max_steps).
+*/
+function resolveRefAgent(entry, registry) {
+	if (!registry) throw new Error(`Agent ref "${entry.ref}" requires an AgentRegistry. Pass agentRegistry in ParseOptions.`);
+	const handle = registry.get(entry.ref);
+	if (!handle) throw new Error(`Agent ref "${entry.ref}" not found in registry. Available agents: ${registry.list().map((h) => h.definition.name).join(", ") || "(none)"}`);
+	const def = handle.definition;
+	const basePrompt = def.prompt.system ?? "";
+	let resolvedSystemPrompt = basePrompt;
+	if (entry.prompt?.append) resolvedSystemPrompt = basePrompt ? `${basePrompt}\n\n${entry.prompt.append}` : entry.prompt.append;
+	const backend = def.backend === "sdk" ? "default" : def.backend;
+	return {
+		model: def.model,
+		backend,
+		provider: def.provider,
+		system_prompt: basePrompt,
+		max_tokens: entry.max_tokens ?? def.max_tokens,
+		max_steps: entry.max_steps ?? def.max_steps,
+		schedule: def.schedule,
+		resolvedSystemPrompt,
+		handle,
+		isRef: true
 	};
 }
 /**
@@ -538,6 +573,51 @@ function validateAgent(name, agent, errors) {
 		return;
 	}
 	const a = agent;
+	if (typeof a.ref === "string") validateRefAgent(path, a, errors);
+	else validateInlineAgent(path, a, errors);
+}
+function validateRefAgent(path, a, errors) {
+	if (!a.ref.length) errors.push({
+		path: `${path}.ref`,
+		message: "Field \"ref\" must be a non-empty string"
+	});
+	if (a.prompt !== void 0) if (typeof a.prompt !== "object" || a.prompt === null) errors.push({
+		path: `${path}.prompt`,
+		message: "Field \"prompt\" for ref agents must be an object with optional \"append\""
+	});
+	else {
+		const p = a.prompt;
+		if (p.append !== void 0 && typeof p.append !== "string") errors.push({
+			path: `${path}.prompt.append`,
+			message: "Field \"prompt.append\" must be a string"
+		});
+	}
+	if (a.system_prompt !== void 0) errors.push({
+		path: `${path}.system_prompt`,
+		message: "Field \"system_prompt\" cannot be used with ref agents — use \"prompt.append\" instead"
+	});
+	for (const field of [
+		"model",
+		"backend",
+		"provider",
+		"tools",
+		"wakeup",
+		"wakeup_prompt",
+		"timeout"
+	]) if (a[field] !== void 0) errors.push({
+		path: `${path}.${field}`,
+		message: `Field "${field}" cannot be used with ref agents — it comes from the agent definition`
+	});
+	if (a.max_tokens !== void 0 && typeof a.max_tokens !== "number") errors.push({
+		path: `${path}.max_tokens`,
+		message: "Field \"max_tokens\" must be a number"
+	});
+	if (a.max_steps !== void 0 && typeof a.max_steps !== "number") errors.push({
+		path: `${path}.max_steps`,
+		message: "Field \"max_steps\" must be a number"
+	});
+}
+function validateInlineAgent(path, a, errors) {
 	const backend = typeof a.backend === "string" ? a.backend : "default";
 	if (a.model !== void 0 && typeof a.model !== "string") errors.push({
 		path: `${path}.model`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-worker",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "SDK and CLI for creating and testing agent workers with Vercel AI SDK",
   "type": "module",
   "main": "./dist/index.mjs",
@@ -29,6 +29,7 @@
     "format": "oxfmt src",
     "format:check": "oxfmt src --check",
     "typecheck": "tsgo",
+    "gen:schema": "bun scripts/gen-workflow-ref.ts > docs/workflow/SCHEMA.md",
     "prepublishOnly": "bun run build"
   },
   "dependencies": {

package/dist/context-CdcZpO-0.mjs

@@ -1,4 +0,0 @@
-import { A as MENTION_PATTERN, B as formatProposal, C as DefaultDocumentStore, D as MemoryStorage, E as FileStorage, F as createResourceRef, G as getAgentId, H as createLogTool, I as extractMentions, K as EventLog, L as generateResourceId, M as RESOURCE_PREFIX, N as RESOURCE_SCHEME, O as ContextProviderImpl, P as calculatePriority, R as shouldUseResource, S as DefaultResourceStore, T as DefaultChannelStore, U as formatInbox, V as formatProposalList, W as formatToolParams, _ as FileContextProvider, b as resolveContextDir, j as MESSAGE_LENGTH_THRESHOLD, k as CONTEXT_DEFAULTS, v as createFileContextProvider, w as DefaultInboxStore, x as DefaultStatusStore, y as getDefaultContextDir, z as createContextMCPServer } from "./cli/index.mjs";
-import { n as createMemoryContextProvider, t as MemoryContextProvider } from "./memory-provider-ZLOKyCxA.mjs";
-
-export { createFileContextProvider };