agent-worker 0.3.0 → 0.4.0

package/dist/workflow-CaRCNEh6.mjs

@@ -0,0 +1,1784 @@
+import { a as createMockBackend, b as createModelAsync, g as parseModel, n as createBackend } from "./backends-DenGdkrj.mjs";
+import { c as CONTEXT_DEFAULTS, i as resolveContextDir, n as createFileContextProvider, t as FileContextProvider } from "./cli/index.mjs";
+import { a as createMemoryContextProvider, t as createContextMCPServer } from "./mcp-server-DtIApaBD.mjs";
+import { generateText, jsonSchema, stepCountIs, tool } from "ai";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { parse } from "yaml";
+import { tmpdir } from "node:os";
+import { exec, execSync } from "node:child_process";
+import { promisify } from "node:util";
+import { createServer } from "node:http";
+import { randomUUID } from "node:crypto";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { MockLanguageModelV3, mockValues } from "ai/test";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import chalk from "chalk";
+import wrapAnsi from "wrap-ansi";
+import stringWidth from "string-width";
+
+//#region src/workflow/parser.ts
+/**
+* Workflow file parser
+*/
+/**
+* Parse a workflow file
+*/
+async function parseWorkflowFile(filePath, options) {
+	const absolutePath = resolve(filePath);
+	const workflow = options?.workflow ?? options?.instance ?? "global";
+	const tag = options?.tag ?? "main";
+	if (!existsSync(absolutePath)) throw new Error(`Workflow file not found: ${absolutePath}`);
+	const content = readFileSync(absolutePath, "utf-8");
+	const workflowDir = dirname(absolutePath);
+	let raw;
+	try {
+		raw = parse(content);
+	} catch (error) {
+		throw new Error(`Failed to parse YAML: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	const validation = validateWorkflow(raw);
+	if (!validation.valid) {
+		const messages = validation.errors.map((e) => `  - ${e.path}: ${e.message}`).join("\n");
+		throw new Error(`Invalid workflow file:\n${messages}`);
+	}
+	const name = raw.name || basename(absolutePath, ".yml").replace(".yaml", "");
+	const agents = {};
+	for (const [agentName, agentDef] of Object.entries(raw.agents)) agents[agentName] = await resolveAgent(agentDef, workflowDir);
+	return {
+		name,
+		filePath: absolutePath,
+		agents,
+		context: resolveContext(raw.context, workflowDir, name, workflow, tag),
+		setup: raw.setup || [],
+		kickoff: raw.kickoff
+	};
+}
+/**
+* Resolve context configuration
+*
+* - undefined (not set): default file provider enabled
+* - null: default file provider enabled (YAML `context:` syntax)
+* - false: explicitly disabled
+* - { provider: 'file', config?: { dir | bind } }: file provider (ephemeral or persistent)
+* - { provider: 'memory' }: memory provider (for testing)
+*/
+function resolveContext(config, workflowDir, workflowName, workflow, tag) {
+	const resolve = (template) => resolveContextDir(template, {
+		workflowName,
+		workflow,
+		tag,
+		instance: workflow,
+		baseDir: workflowDir
+	});
+	if (config === false) return;
+	if (config === void 0 || config === null) return {
+		provider: "file",
+		dir: resolve(CONTEXT_DEFAULTS.dir)
+	};
+	if (config.provider === "memory") return {
+		provider: "memory",
+		documentOwner: config.documentOwner
+	};
+	const bindPath = config.config?.bind;
+	if (bindPath) return {
+		provider: "file",
+		dir: resolve(bindPath),
+		persistent: true,
+		documentOwner: config.documentOwner
+	};
+	return {
+		provider: "file",
+		dir: resolve(config.config?.dir || CONTEXT_DEFAULTS.dir),
+		documentOwner: config.documentOwner
+	};
+}
+/**
+* Resolve agent definition (load system prompt from file if needed)
+*/
+async function resolveAgent(agent, workflowDir) {
+	let resolvedSystemPrompt = agent.system_prompt;
+	if (resolvedSystemPrompt?.endsWith(".txt") || resolvedSystemPrompt?.endsWith(".md")) {
+		const promptPath = resolvedSystemPrompt.startsWith("/") ? resolvedSystemPrompt : join(workflowDir, resolvedSystemPrompt);
+		if (existsSync(promptPath)) resolvedSystemPrompt = readFileSync(promptPath, "utf-8");
+	}
+	return {
+		...agent,
+		resolvedSystemPrompt
+	};
+}
+/**
+* Validate workflow structure
+*/
+function validateWorkflow(workflow) {
+	const errors = [];
+	if (!workflow || typeof workflow !== "object") {
+		errors.push({
+			path: "",
+			message: "Workflow must be an object"
+		});
+		return {
+			valid: false,
+			errors
+		};
+	}
+	const w = workflow;
+	if (!w.agents || typeof w.agents !== "object") errors.push({
+		path: "agents",
+		message: "Required field \"agents\" must be an object"
+	});
+	else {
+		const agents = w.agents;
+		for (const [name, agent] of Object.entries(agents)) validateAgent(name, agent, errors);
+	}
+	if (w.context !== void 0 && w.context !== null && w.context !== false) validateContext(w.context, errors);
+	if (w.setup !== void 0) if (!Array.isArray(w.setup)) errors.push({
+		path: "setup",
+		message: "Setup must be an array"
+	});
+	else for (let i = 0; i < w.setup.length; i++) validateSetupTask(`setup[${i}]`, w.setup[i], errors);
+	if (w.kickoff !== void 0 && typeof w.kickoff !== "string") errors.push({
+		path: "kickoff",
+		message: "Kickoff must be a string"
+	});
+	return {
+		valid: errors.length === 0,
+		errors
+	};
+}
+function validateContext(context, errors) {
+	if (typeof context !== "object" || context === null) {
+		errors.push({
+			path: "context",
+			message: "Context must be an object or false"
+		});
+		return;
+	}
+	const c = context;
+	if (!c.provider || typeof c.provider !== "string") {
+		errors.push({
+			path: "context.provider",
+			message: "Context requires \"provider\" field (file or memory)"
+		});
+		return;
+	}
+	if (c.provider !== "file" && c.provider !== "memory") {
+		errors.push({
+			path: "context.provider",
+			message: "Context provider must be \"file\" or \"memory\""
+		});
+		return;
+	}
+	if (c.documentOwner !== void 0 && typeof c.documentOwner !== "string") errors.push({
+		path: "context.documentOwner",
+		message: "Context documentOwner must be a string"
+	});
+	if (c.provider === "file" && c.config !== void 0) {
+		if (typeof c.config !== "object" || c.config === null) {
+			errors.push({
+				path: "context.config",
+				message: "Context config must be an object"
+			});
+			return;
+		}
+		const cfg = c.config;
+		if (cfg.dir !== void 0 && cfg.bind !== void 0) {
+			errors.push({
+				path: "context.config",
+				message: "\"dir\" and \"bind\" are mutually exclusive — use one or the other"
+			});
+			return;
+		}
+		if (cfg.dir !== void 0 && typeof cfg.dir !== "string") errors.push({
+			path: "context.config.dir",
+			message: "Context config dir must be a string"
+		});
+		if (cfg.bind !== void 0 && typeof cfg.bind !== "string") errors.push({
+			path: "context.config.bind",
+			message: "Context config bind must be a string path"
+		});
+	}
+}
+function validateSetupTask(path, task, errors) {
+	if (!task || typeof task !== "object") {
+		errors.push({
+			path,
+			message: "Setup task must be an object"
+		});
+		return;
+	}
+	const t = task;
+	if (!t.shell || typeof t.shell !== "string") errors.push({
+		path: `${path}.shell`,
+		message: "Setup task requires \"shell\" field as string"
+	});
+	if (t.as !== void 0 && typeof t.as !== "string") errors.push({
+		path: `${path}.as`,
+		message: "Setup task \"as\" field must be a string"
+	});
+}
+/** Backends that don't require an explicit model field */
+const CLI_BACKENDS = [
+	"claude",
+	"cursor",
+	"codex",
+	"mock"
+];
+function validateAgent(name, agent, errors) {
+	const path = `agents.${name}`;
+	if (!agent || typeof agent !== "object") {
+		errors.push({
+			path,
+			message: "Agent must be an object"
+		});
+		return;
+	}
+	const a = agent;
+	const backend = typeof a.backend === "string" ? a.backend : "sdk";
+	if (a.model !== void 0 && typeof a.model !== "string") errors.push({
+		path: `${path}.model`,
+		message: "Field \"model\" must be a string"
+	});
+	else if (!a.model && !CLI_BACKENDS.includes(backend)) errors.push({
+		path: `${path}.model`,
+		message: "Required field \"model\" must be a string (required for sdk backend)"
+	});
+	if (a.system_prompt !== void 0 && typeof a.system_prompt !== "string") errors.push({
+		path: `${path}.system_prompt`,
+		message: "Optional field \"system_prompt\" must be a string"
+	});
+	if (a.tools !== void 0 && !Array.isArray(a.tools)) errors.push({
+		path: `${path}.tools`,
+		message: "Optional field \"tools\" must be an array"
+	});
+}
+
+//#endregion
+//#region src/workflow/interpolate.ts
+const VARIABLE_PATTERN = /\$\{\{\s*([^}]+)\s*\}\}/g;
+/**
+* Interpolate variables in a template string
+* @param warn Optional callback for unresolved variables
+*/
+function interpolate(template, context, warn) {
+	return template.replace(VARIABLE_PATTERN, (match, expression) => {
+		const value = resolveExpression(expression.trim(), context);
+		if (value === void 0 && warn) warn("Unresolved variable: ${{ " + expression.trim() + " }} — no setup task defines it");
+		return value ?? match;
+	});
+}
+/**
+* Resolve a variable expression
+*/
+function resolveExpression(expression, context) {
+	if (expression.startsWith("env.")) {
+		const varName = expression.slice(4);
+		return context.env?.[varName] ?? process.env[varName];
+	}
+	if (expression.startsWith("workflow.")) {
+		const field = expression.slice(9);
+		if (field === "name") return context.workflow?.name;
+		if (field === "tag") return context.workflow?.tag;
+		if (field === "instance") return context.workflow?.instance || context.workflow?.tag;
+		return;
+	}
+	const value = context[expression];
+	return typeof value === "string" ? value : void 0;
+}
+/**
+* Create a context from workflow metadata
+*/
+function createContext(workflowName, tag, taskOutputs = {}) {
+	return {
+		...taskOutputs,
+		env: process.env,
+		workflow: {
+			name: workflowName,
+			tag,
+			instance: tag
+		}
+	};
+}
+
+//#endregion
+//#region src/workflow/context/http-transport.ts
+/**
+* HTTP-based MCP Transport
+*
+* Hosts MCP server over HTTP using StreamableHTTPServerTransport.
+* CLI agents (cursor, claude, codex) connect directly via URL — no subprocess bridge needed.
+*
+* Each agent gets a unique URL: http://localhost:<port>/mcp?agent=<name>
+* The agent name is used as the MCP session ID, so tool handlers
+* receive it via extra.sessionId → getAgentId().
+*/
+/**
+* Parse request body as JSON
+*/
+function parseRequestBody(req) {
+	return new Promise((resolve, reject) => {
+		const chunks = [];
+		req.on("data", (chunk) => chunks.push(chunk));
+		req.on("end", () => {
+			try {
+				const body = Buffer.concat(chunks).toString();
+				resolve(body ? JSON.parse(body) : void 0);
+			} catch (err) {
+				reject(err);
+			}
+		});
+		req.on("error", reject);
+	});
+}
+/**
+* Check if a JSON-RPC message is an initialize request
+*/
+function isInitializeRequest(body) {
+	if (Array.isArray(body)) return body.some((msg) => msg?.method === "initialize");
+	return body?.method === "initialize";
+}
+/**
+* Start an HTTP MCP server
+*
+* Agents connect via: http://localhost:<port>/mcp?agent=<name>
+* The server creates a per-session StreamableHTTPServerTransport and McpServer.
+*/
+async function runWithHttp(options) {
+	const { createServerInstance, port = 0, onConnect, onDisconnect } = options;
+	const sessions = /* @__PURE__ */ new Map();
+	const httpServer = createServer(async (req, res) => {
+		const reqUrl = new URL(req.url || "/", `http://localhost`);
+		if (!reqUrl.pathname.startsWith("/mcp")) {
+			res.writeHead(404, { "Content-Type": "application/json" });
+			res.end(JSON.stringify({ error: "Not found" }));
+			return;
+		}
+		const agentName = reqUrl.searchParams.get("agent") || "anonymous";
+		const sessionId = req.headers["mcp-session-id"];
+		if (sessionId && sessions.has(sessionId)) {
+			const session = sessions.get(sessionId);
+			if (req.method === "DELETE") {
+				await session.transport.close();
+				sessions.delete(sessionId);
+				if (onDisconnect) onDisconnect(session.agentId, sessionId);
+				res.writeHead(200);
+				res.end();
+				return;
+			}
+			const body = req.method === "POST" ? await parseRequestBody(req) : void 0;
+			await session.transport.handleRequest(req, res, body);
+			return;
+		}
+		if (req.method === "POST") {
+			const body = await parseRequestBody(req);
+			if (!isInitializeRequest(body)) {
+				res.writeHead(400, { "Content-Type": "application/json" });
+				res.end(JSON.stringify({ error: "Bad request: session required" }));
+				return;
+			}
+			const transport = new StreamableHTTPServerTransport({
+				sessionIdGenerator: () => `${agentName}-${randomUUID().slice(0, 8)}`,
+				onsessioninitialized: (sid) => {
+					sessions.set(sid, {
+						transport,
+						agentId: agentName
+					});
+					if (onConnect) onConnect(agentName, sid);
+				}
+			});
+			Object.defineProperty(transport, "_agentId", {
+				value: agentName,
+				writable: true
+			});
+			await createServerInstance().connect(transport);
+			await transport.handleRequest(req, res, body);
+			return;
+		}
+		if (req.method === "GET") {
+			res.writeHead(400, { "Content-Type": "application/json" });
+			res.end(JSON.stringify({ error: "Session ID required for GET requests" }));
+			return;
+		}
+		res.writeHead(405, { "Content-Type": "application/json" });
+		res.end(JSON.stringify({ error: "Method not allowed" }));
+	});
+	const actualPort = await new Promise((resolve, reject) => {
+		httpServer.on("error", reject);
+		httpServer.listen(port, "127.0.0.1", () => {
+			httpServer.removeListener("error", reject);
+			const addr = httpServer.address();
+			if (typeof addr === "object" && addr) resolve(addr.port);
+			else reject(/* @__PURE__ */ new Error("Failed to get server address"));
+		});
+	});
+	return {
+		httpServer,
+		url: `http://127.0.0.1:${actualPort}/mcp`,
+		port: actualPort,
+		sessions,
+		async close() {
+			for (const [sid, session] of sessions) {
+				await session.transport.close();
+				if (onDisconnect) onDisconnect(session.agentId, sid);
+			}
+			sessions.clear();
+			await new Promise((resolve) => {
+				httpServer.close(() => resolve());
+			});
+		}
+	};
+}
+
+//#endregion
+//#region src/workflow/controller/types.ts
+/** Default controller configuration values */
+const CONTROLLER_DEFAULTS = {
+	pollInterval: 5e3,
+	retry: {
+		maxAttempts: 3,
+		backoffMs: 1e3,
+		backoffMultiplier: 2
+	},
+	recentChannelLimit: 50,
+	idleDebounceMs: 2e3
+};
+
+//#endregion
+//#region src/workflow/controller/prompt.ts
+/**
+* Format inbox messages for display
+*/
+function formatInbox(inbox) {
+	if (inbox.length === 0) return "(no messages)";
+	return inbox.map((m) => {
+		const priority = m.priority === "high" ? " [HIGH]" : "";
+		const time = m.entry.timestamp.slice(11, 19);
+		const dm = m.entry.to ? " [DM]" : "";
+		return `- [${time}] From @${m.entry.from}${priority}${dm}: ${m.entry.content}`;
+	}).join("\n");
+}
+/**
+* Format channel messages for display
+*/
+function formatChannel(entries) {
+	if (entries.length === 0) return "(no messages)";
+	return entries.map((e) => {
+		const dm = e.to ? ` [DM→@${e.to}]` : "";
+		return `[${e.timestamp.slice(11, 19)}] @${e.from}${dm}: ${e.content}`;
+	}).join("\n");
+}
+/**
+* Build the complete agent prompt from run context
+*/
+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 (last ${ctx.recentChannel.length} messages)`);
+	sections.push(formatChannel(ctx.recentChannel));
+	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.");
+	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 timestamp).");
+	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");
+}
+
+//#endregion
+//#region src/workflow/controller/mcp-config.ts
+/**
+* Generate MCP config for workflow context server.
+*
+* Uses HTTP transport — CLI agents connect directly via URL:
+*   { type: "http", url: "http://127.0.0.1:<port>/mcp?agent=<name>" }
+*/
+function generateWorkflowMCPConfig(mcpUrl, agentName) {
+	const url = `${mcpUrl}?agent=${encodeURIComponent(agentName)}`;
+	return { mcpServers: { "workflow-context": {
+		type: "http",
+		url
+	} } };
+}
+
+//#endregion
+//#region src/workflow/controller/mock-runner.ts
+/**
+* Mock Agent Runner
+*
+* Orchestrates mock agent execution for workflow integration testing.
+* Uses AI SDK generateText with MockLanguageModelV3 and real MCP tool calls.
+*
+* This lives in the controller layer (not backends) because it does orchestration:
+* connecting to MCP, building prompts, managing tool loops.
+* The mock backend itself is just a simple send() adapter.
+*/
+/**
+* Connect to workflow MCP server via HTTP and create AI SDK tool wrappers
+*/
+async function createMCPToolBridge$1(mcpUrl, agentName) {
+	const transport = new StreamableHTTPClientTransport(new URL(`${mcpUrl}?agent=${encodeURIComponent(agentName)}`));
+	const client = new Client({
+		name: agentName,
+		version: "1.0.0"
+	});
+	await client.connect(transport);
+	const { tools: mcpTools } = await client.listTools();
+	const aiTools = {};
+	for (const mcpTool of mcpTools) {
+		const toolName = mcpTool.name;
+		aiTools[toolName] = tool({
+			description: mcpTool.description || toolName,
+			inputSchema: jsonSchema(mcpTool.inputSchema),
+			execute: async (args) => {
+				return (await client.callTool({
+					name: toolName,
+					arguments: args
+				})).content;
+			}
+		});
+	}
+	return {
+		tools: aiTools,
+		close: () => client.close()
+	};
+}
+/**
+* Run a mock agent with AI SDK and real MCP tools.
+*
+* Used by the controller when backend.type === 'mock'.
+* Unlike real backends that just send(), the mock runner needs to:
+* 1. Connect to MCP server for real tool execution
+* 2. Generate scripted tool calls via MockLanguageModelV3
+* 3. Execute the full tool loop to test channel/document flow
+*/
+async function runMockAgent(ctx, debugLog) {
+	const startTime = Date.now();
+	const log = debugLog || (() => {});
+	try {
+		if (!ctx.mcpUrl) return {
+			success: false,
+			error: "Mock runner requires mcpUrl (HTTP MCP server)",
+			duration: 0
+		};
+		const mcp = await createMCPToolBridge$1(ctx.mcpUrl, ctx.name);
+		log(`MCP connected, ${Object.keys(mcp.tools).length} tools`);
+		const inboxSummary = ctx.inbox.map((m) => `${m.entry.from}: ${m.entry.content.slice(0, 80).replace(/@/g, "")}`).join("; ");
+		const mockModel = new MockLanguageModelV3({ doGenerate: mockValues({
+			content: [{
+				type: "tool-call",
+				toolCallId: `call-${ctx.name}-${Date.now()}`,
+				toolName: "channel_send",
+				input: JSON.stringify({ message: `[${ctx.name}] Processed: ${inboxSummary.slice(0, 200)}` })
+			}],
+			finishReason: {
+				unified: "tool-calls",
+				raw: "tool_use"
+			},
+			usage: {
+				inputTokens: {
+					total: 100,
+					noCache: 100,
+					cacheRead: 0,
+					cacheWrite: 0
+				},
+				outputTokens: {
+					total: 50,
+					text: 50,
+					reasoning: 0
+				}
+			}
+		}, {
+			content: [{
+				type: "text",
+				text: `${ctx.name} done.`
+			}],
+			finishReason: {
+				unified: "stop",
+				raw: "end_turn"
+			},
+			usage: {
+				inputTokens: {
+					total: 50,
+					noCache: 50,
+					cacheRead: 0,
+					cacheWrite: 0
+				},
+				outputTokens: {
+					total: 10,
+					text: 10,
+					reasoning: 0
+				}
+			}
+		}) });
+		const prompt = buildAgentPrompt(ctx);
+		log(`Prompt (${prompt.length} chars)`);
+		const result = await generateText({
+			model: mockModel,
+			tools: mcp.tools,
+			prompt,
+			system: ctx.agent.resolvedSystemPrompt,
+			stopWhen: stepCountIs(3)
+		});
+		const totalToolCalls = result.steps.reduce((n, s) => n + s.toolCalls.length, 0);
+		await mcp.close();
+		return {
+			success: true,
+			duration: Date.now() - startTime,
+			steps: result.steps.length,
+			toolCalls: totalToolCalls
+		};
+	} catch (error) {
+		return {
+			success: false,
+			error: error instanceof Error ? error.message : String(error),
+			duration: Date.now() - startTime
+		};
+	}
+}
+
+//#endregion
+//#region src/workflow/controller/sdk-runner.ts
+/**
+* SDK Agent Runner
+*
+* Runs SDK agents with full tool access in workflows:
+* - MCP context tools (channel_send, document_write, etc.)
+* - Bash tool for shell commands
+*
+* Same pattern as mock-runner.ts but with real models via createModelAsync.
+* This is the standard execution path for SDK backends in workflows —
+* all agents get MCP + bash regardless of backend type.
+*/
+/** Extract useful details from AI SDK errors (statusCode, url, responseBody) */
+function formatError(error) {
+	if (!(error instanceof Error)) return String(error);
+	const e = error;
+	const parts = [error.message];
+	if (e.statusCode) parts[0] = `HTTP ${e.statusCode}: ${error.message}`;
+	if (e.url) parts.push(`url=${e.url}`);
+	if (e.responseBody && typeof e.responseBody === "string") {
+		const body = e.responseBody.length > 200 ? e.responseBody.slice(0, 200) + "…" : e.responseBody;
+		parts.push(`body=${body}`);
+	}
+	return parts.join(" ");
+}
+/** Truncate string, flatten newlines */
+function truncate(s, max) {
+	const flat = s.replace(/\s+/g, " ").trim();
+	return flat.length > max ? flat.slice(0, max) + "…" : flat;
+}
+/** Format a tool call for concise single-line debug output (function call syntax) */
+function formatToolCall(tc) {
+	const input = tc.input ?? tc.args ?? {};
+	const pairs = Object.entries(input).map(([k, v]) => {
+		return `${k}=${truncate(typeof v === "string" ? v : JSON.stringify(v), 60)}`;
+	});
+	return `${tc.toolName}(${pairs.join(", ")})`;
+}
+/**
+* Connect to workflow MCP server and create AI SDK tool wrappers.
+* Same bridge as mock-runner — extracted here for SDK agents.
+*/
+async function createMCPToolBridge(mcpUrl, agentName) {
+	const transport = new StreamableHTTPClientTransport(new URL(`${mcpUrl}?agent=${encodeURIComponent(agentName)}`));
+	const client = new Client({
+		name: agentName,
+		version: "1.0.0"
+	});
+	await client.connect(transport);
+	const { tools: mcpTools } = await client.listTools();
+	const aiTools = {};
+	for (const mcpTool of mcpTools) {
+		const toolName = mcpTool.name;
+		aiTools[toolName] = tool({
+			description: mcpTool.description || toolName,
+			inputSchema: jsonSchema(mcpTool.inputSchema),
+			execute: async (args) => {
+				return (await client.callTool({
+					name: toolName,
+					arguments: args
+				})).content;
+			}
+		});
+	}
+	return {
+		tools: aiTools,
+		close: () => client.close()
+	};
+}
+function createBashTool() {
+	return tool({
+		description: "Execute a shell command and return stdout/stderr.",
+		inputSchema: jsonSchema({
+			type: "object",
+			properties: { command: {
+				type: "string",
+				description: "The shell command to execute"
+			} },
+			required: ["command"]
+		}),
+		execute: async ({ command }) => {
+			try {
+				return execSync(command, {
+					encoding: "utf-8",
+					timeout: 12e4
+				}).trim() || "(no output)";
+			} catch (error) {
+				return `Error (exit ${error.status}): ${error.stderr || error.message}`;
+			}
+		}
+	});
+}
+/**
+* Run an SDK agent with real model + MCP tools + bash.
+*
+* Used by the controller when backend.type === 'sdk'.
+* Unlike the simple SdkBackend.send() (text-only), this runner:
+* 1. Connects to MCP server for context tools (channel, document)
+* 2. Adds bash tool for shell access
+* 3. Runs generateText with full tool loop
+*/
+async function runSdkAgent(ctx, debugLog) {
+	const startTime = Date.now();
+	const log = debugLog || (() => {});
+	try {
+		if (!ctx.mcpUrl) return {
+			success: false,
+			error: "SDK runner requires mcpUrl",
+			duration: 0
+		};
+		const mcp = await createMCPToolBridge(ctx.mcpUrl, ctx.name);
+		log(`MCP connected, ${Object.keys(mcp.tools).length} context tools`);
+		const model = await createModelAsync(ctx.agent.model);
+		const tools = {
+			...mcp.tools,
+			bash: createBashTool()
+		};
+		const prompt = buildAgentPrompt(ctx);
+		log(`Prompt (${prompt.length} chars) → sdk with ${Object.keys(tools).length} tools`);
+		let _stepNum = 0;
+		const result = await generateText({
+			model,
+			tools,
+			system: ctx.agent.resolvedSystemPrompt,
+			prompt,
+			maxOutputTokens: ctx.agent.max_tokens ?? 8192,
+			stopWhen: stepCountIs(ctx.agent.max_steps ?? 30),
+			onStepFinish: (step) => {
+				_stepNum++;
+				if (step.toolCalls?.length) for (const tc of step.toolCalls) log(`CALL ${formatToolCall(tc)}`);
+			}
+		});
+		const totalToolCalls = result.steps.reduce((n, s) => n + s.toolCalls.length, 0);
+		await mcp.close();
+		return {
+			success: true,
+			duration: Date.now() - startTime,
+			content: result.text,
+			steps: result.steps.length,
+			toolCalls: totalToolCalls
+		};
+	} catch (error) {
+		return {
+			success: false,
+			error: formatError(error),
+			duration: Date.now() - startTime
+		};
+	}
+}
+
+//#endregion
+//#region src/workflow/controller/controller.ts
+/** Check if controller should continue running */
+function shouldContinue(state) {
+	return state !== "stopped";
+}
+/**
+* Create an agent controller
+*
+* The controller:
+* 1. Polls for inbox messages on an interval
+* 2. Runs the agent when messages are found
+* 3. Acknowledges inbox only on successful run
+* 4. Retries with exponential backoff on failure
+* 5. Can be woken early via wake()
+*/
+function createAgentController(config) {
+	const { name, agent, contextProvider, mcpUrl, workspaceDir, projectDir, backend, onRunComplete, log = () => {}, feedback } = config;
+	const errorLog = config.errorLog ?? log;
+	const pollInterval = config.pollInterval ?? CONTROLLER_DEFAULTS.pollInterval;
+	const retryConfig = {
+		maxAttempts: config.retry?.maxAttempts ?? CONTROLLER_DEFAULTS.retry.maxAttempts,
+		backoffMs: config.retry?.backoffMs ?? CONTROLLER_DEFAULTS.retry.backoffMs,
+		backoffMultiplier: config.retry?.backoffMultiplier ?? CONTROLLER_DEFAULTS.retry.backoffMultiplier
+	};
+	let state = "stopped";
+	let wakeResolver = null;
+	let pollTimeout = null;
+	/**
+	* Wait for either poll interval or wake() call
+	*/
+	async function waitForWakeOrPoll() {
+		return new Promise((resolve) => {
+			wakeResolver = resolve;
+			pollTimeout = setTimeout(() => {
+				wakeResolver = null;
+				resolve();
+			}, pollInterval);
+		});
+	}
+	/**
+	* Main controller loop
+	*/
+	async function runLoop() {
+		while (shouldContinue(state)) {
+			await waitForWakeOrPoll();
+			if (!shouldContinue(state)) break;
+			const inbox = await contextProvider.getInbox(name);
+			if (inbox.length === 0) {
+				state = "idle";
+				continue;
+			}
+			const senders = inbox.map((m) => m.entry.from);
+			log(`Inbox: ${inbox.length} message(s) from [${senders.join(", ")}]`);
+			for (const msg of inbox) {
+				const preview = msg.entry.content.length > 120 ? msg.entry.content.slice(0, 120) + "..." : msg.entry.content;
+				log(`  from @${msg.entry.from}: ${preview}`);
+			}
+			const latestId = inbox[inbox.length - 1].entry.id;
+			await contextProvider.markInboxSeen(name, latestId);
+			let attempt = 0;
+			let lastResult = null;
+			while (attempt < retryConfig.maxAttempts && shouldContinue(state)) {
+				attempt++;
+				state = "running";
+				log(`Running (attempt ${attempt}/${retryConfig.maxAttempts})`);
+				lastResult = await runAgent(backend, {
+					name,
+					agent,
+					inbox,
+					recentChannel: await contextProvider.readChannel({
+						limit: CONTROLLER_DEFAULTS.recentChannelLimit,
+						agent: name
+					}),
+					documentContent: await contextProvider.readDocument(),
+					mcpUrl,
+					workspaceDir,
+					projectDir,
+					retryAttempt: attempt,
+					feedback
+				}, log);
+				if (lastResult.success) {
+					log(`DONE ${lastResult.steps ? `${lastResult.steps} steps, ${lastResult.toolCalls} tool calls, ${lastResult.duration}ms` : `${lastResult.duration}ms`}`);
+					if (lastResult.content) await contextProvider.appendChannel(name, lastResult.content);
+					await contextProvider.ackInbox(name, latestId);
+					break;
+				}
+				errorLog(`ERROR ${lastResult.error}`);
+				if (attempt < retryConfig.maxAttempts && shouldContinue(state)) {
+					const delay = retryConfig.backoffMs * Math.pow(retryConfig.backoffMultiplier, attempt - 1);
+					log(`Retrying in ${delay}ms...`);
+					await sleep$2(delay);
+				}
+			}
+			if (lastResult && !lastResult.success) {
+				errorLog(`ERROR max retries exhausted, acknowledging to prevent loop`);
+				await contextProvider.ackInbox(name, latestId);
+			}
+			if (lastResult && onRunComplete) onRunComplete(lastResult);
+			state = "idle";
+		}
+	}
+	return {
+		get name() {
+			return name;
+		},
+		get state() {
+			return state;
+		},
+		async start() {
+			if (state !== "stopped") throw new Error(`Controller ${name} is already running`);
+			state = "idle";
+			log(`Starting`);
+			runLoop().catch((error) => {
+				errorLog(`ERROR ${error instanceof Error ? error.message : String(error)}`);
+				state = "stopped";
+			});
+		},
+		async stop() {
+			log(`Stopping`);
+			state = "stopped";
+			if (pollTimeout) {
+				clearTimeout(pollTimeout);
+				pollTimeout = null;
+			}
+			if (wakeResolver) {
+				wakeResolver();
+				wakeResolver = null;
+			}
+		},
+		wake() {
+			if (state === "idle" && wakeResolver) {
+				log(`Waking`);
+				if (pollTimeout) {
+					clearTimeout(pollTimeout);
+					pollTimeout = null;
+				}
+				wakeResolver();
+				wakeResolver = null;
+			}
+		}
+	};
+}
+/**
+* Run an agent: build prompt, configure workspace, call backend.send()
+*
+* This is the single orchestration function that the controller calls.
+* All the "how to run an agent" logic lives here — backends just send().
+*
+* SDK and mock backends get special runners with MCP tool bridge + bash,
+* because they can't manage tools on their own (unlike CLI backends).
+*/
+async function runAgent(backend, ctx, log) {
+	if (backend.type === "mock") return runMockAgent(ctx, (msg) => log(msg));
+	if (backend.type === "sdk") return runSdkAgent(ctx, (msg) => log(msg));
+	const startTime = Date.now();
+	try {
+		if (backend.setWorkspace) {
+			const mcpConfig = generateWorkflowMCPConfig(ctx.mcpUrl, ctx.name);
+			backend.setWorkspace(ctx.workspaceDir, mcpConfig);
+		}
+		const prompt = buildAgentPrompt(ctx);
+		log(`Prompt (${prompt.length} chars) → ${backend.type} backend`);
+		await backend.send(prompt, { system: ctx.agent.resolvedSystemPrompt });
+		return {
+			success: true,
+			duration: Date.now() - startTime
+		};
+	} catch (error) {
+		return {
+			success: false,
+			error: error instanceof Error ? error.message : String(error),
+			duration: Date.now() - startTime
+		};
+	}
+}
+/**
+* Sleep helper
+*/
+function sleep$2(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+* Check if workflow is complete (all agents idle, no pending work)
+*/
+async function checkWorkflowIdle(controllers, provider, debounceMs = CONTROLLER_DEFAULTS.idleDebounceMs) {
+	if (![...controllers.values()].every((c) => c.state === "idle")) return false;
+	for (const [name] of controllers) if ((await provider.getInbox(name)).length > 0) return false;
+	await sleep$2(debounceMs);
+	return [...controllers.values()].every((c) => c.state === "idle");
+}
+
+//#endregion
+//#region src/workflow/controller/backend.ts
+/**
+* Get backend by explicit backend type
+*
+* All backends are created via the canonical createBackend() factory
+* from backends/index.ts. Mock backend is handled specially (no model needed).
+*/
+function getBackendByType(backendType, options) {
+	if (backendType === "mock") return createMockBackend(options?.debugLog);
+	return createBackend({
+		type: backendType,
+		model: options?.model
+	});
+}
+/**
+* Get appropriate backend for a model identifier
+*
+* Infers backend type from model name and delegates to getBackendByType.
+* Prefer using getBackendByType with explicit backend field in workflow configs.
+*/
+function getBackendForModel(model, options) {
+	const { provider } = parseModel(model);
+	switch (provider) {
+		case "anthropic": return getBackendByType("sdk", {
+			...options,
+			model
+		});
+		case "claude": return getBackendByType("claude", {
+			...options,
+			model
+		});
+		case "codex": return getBackendByType("codex", {
+			...options,
+			model
+		});
+		default: throw new Error(`Unknown provider: ${provider}. Specify backend explicitly.`);
+	}
+}
+
+//#endregion
+//#region src/workflow/layout.ts
+/**
+* Adaptive Terminal Layout System
+*
+* Best practices implementation:
+* - Terminal-aware: Auto-detect width and adapt layout
+* - Smart wrapping: Preserve readability on long messages
+* - Background-agnostic: Colors work on any terminal theme
+* - Human-first: Optimize for visual clarity and scanning
+*
+* References:
+* - https://clig.dev/
+* - https://relay.sh/blog/command-line-ux-in-2020/
+*/
+/**
+* Calculate optimal layout based on terminal size and agent names
+*
+* Layout structure: TIME NAME SEP CONTENT
+* Example: "47:08 student │ Message here"
+*          └──┬─┘ └───┬──┘ │ └─────┬──────┘
+*             5      8     3     remaining
+*/
+function calculateLayout(options) {
+	const { agentNames, compact = false } = options;
+	const terminalWidth = options.terminalWidth ?? process.stdout.columns ?? 80;
+	const compactTime = compact || isShortSession();
+	const timeWidth = compactTime ? 5 : 8;
+	const longestName = Math.max(...agentNames.map((n) => stringWidth(n)), 6);
+	const nameWidth = Math.min(longestName + 1, 20);
+	const separatorWidth = 3;
+	const availableWidth = terminalWidth - (timeWidth + 1 + nameWidth + 1 + separatorWidth);
+	const requestedMaxContent = options.maxContentWidth ?? 80;
+	return {
+		terminalWidth,
+		timeWidth,
+		nameWidth,
+		maxContentWidth: Math.max(Math.min(requestedMaxContent, availableWidth), 40),
+		compactTime,
+		separatorWidth
+	};
+}
+/**
+* Detect if session is likely short (< 1 hour) based on current time
+* Heuristic: if it's early in the day, likely a short session
+*/
+function isShortSession() {
+	return false;
+}
+let lastTimestamp = null;
+/**
+* Format timestamp according to layout config
+*/
+function formatTime(timestamp, layout) {
+	const date = new Date(timestamp);
+	const current = {
+		hour: date.getHours(),
+		minute: date.getMinutes(),
+		second: date.getSeconds()
+	};
+	const last = lastTimestamp ? {
+		hour: lastTimestamp.getHours(),
+		minute: lastTimestamp.getMinutes()
+	} : null;
+	const hourChanged = !last || last.hour !== current.hour;
+	const minuteChanged = !last || last.minute !== current.minute;
+	lastTimestamp = date;
+	return {
+		formatted: layout.compactTime ? `${pad(current.minute)}:${pad(current.second)}` : `${pad(current.hour)}:${pad(current.minute)}:${pad(current.second)}`,
+		hourChanged,
+		minuteChanged
+	};
+}
+/**
+* Reset time tracking (call when starting new workflow)
+*/
+function resetTimeTracking() {
+	lastTimestamp = null;
+}
+function pad(num) {
+	return num.toString().padStart(2, "0");
+}
+function createGroupingState() {
+	return {
+		lastAgent: null,
+		lastMinute: null,
+		messageCount: 0
+	};
+}
+/**
+* Check if message should be grouped with previous one
+* Groups consecutive messages from same agent within same minute
+*/
+function shouldGroup(agent, timestamp, state, enableGrouping) {
+	if (!enableGrouping) return false;
+	const date = new Date(timestamp);
+	const minute = date.getHours() * 60 + date.getMinutes();
+	const isSameAgent = agent === state.lastAgent;
+	const isSameMinute = minute === state.lastMinute;
+	state.lastAgent = agent;
+	state.lastMinute = minute;
+	state.messageCount++;
+	return isSameAgent && isSameMinute && state.messageCount > 1;
+}
+
+//#endregion
+//#region src/workflow/layout-log.ts
+/**
+* Log-oriented layout strategies
+*
+* Optimized for workflow logs where readability > strict alignment
+* Provides alternative formatting styles for different use cases
+*/
+/**
+* Timeline style: Time with colored dot indicator for each agent
+*
+* Example:
+* 01:17:13 ● workflow
+*          │ Running workflow: test-simple with a very long message
+*          │ that wraps to the next line automatically
+* 01:17:20 ● alice
+*          │ @bob What are AI agents?
+* 01:17:25 ● bob
+*          │ @alice AI agents are autonomous software entities
+*/
+function formatTimelineLog(entry, layout, showTime = true) {
+	const time = formatTime(entry.timestamp, layout).formatted;
+	const timeStr = showTime ? chalk.dim(time) : " ".repeat(layout.timeWidth);
+	const agentColors = [
+		chalk.cyan,
+		chalk.yellow,
+		chalk.magenta,
+		chalk.green,
+		chalk.blue,
+		chalk.redBright
+	];
+	let dotColor;
+	if (entry.from === "workflow" || entry.from === "system") dotColor = agentColors[0];
+	else dotColor = agentColors[entry.from.split("").reduce((acc, c) => acc + c.charCodeAt(0), 0) % (agentColors.length - 1) + 1];
+	const dot = dotColor("●");
+	const separator = chalk.dim("│");
+	const prefixWidth = layout.timeWidth + 3;
+	const contentWidth = Math.min(layout.terminalWidth - prefixWidth - 3, 80);
+	const wrappedLines = wrapAnsi(entry.content, contentWidth, {
+		hard: true,
+		trim: false
+	}).split("\n");
+	const result = [];
+	result.push(`${timeStr} ${dot} ${chalk.bold(entry.from)}`);
+	const indent = " ".repeat(layout.timeWidth + 1) + `${separator} `;
+	result.push(...wrappedLines.map((line) => indent + line));
+	return result.join("\n");
+}
+/**
+* Standard log format: Minimal colors for TTY, plain text for pipes
+*
+* Format: TIMESTAMP SOURCE: MESSAGE
+* Example: 2026-02-09T01:17:13Z workflow: Running workflow: test
+*
+* TTY Mode (terminal):
+* - Dim timestamps for less visual weight
+* - Cyan source names for quick scanning
+* - Yellow [WARN] for warnings
+* - Red [ERROR] for errors
+*
+* Pipe Mode (file/grep):
+* - No colors (chalk auto-detects non-TTY)
+* - Pure text for maximum compatibility
+*
+* Designed for --debug mode, CI/CD logs, and piping to other tools
+*/
+function formatStandardLog(entry, includeMillis = false) {
+	const timestamp = includeMillis ? entry.timestamp : entry.timestamp.split(".")[0] + "Z";
+	const lines = entry.content.split("\n");
+	const isWarn = entry.content.includes("[WARN]");
+	const isError = entry.content.includes("[ERROR]");
+	let contentColor = (s) => s;
+	if (isWarn) contentColor = chalk.yellow;
+	if (isError) contentColor = chalk.red;
+	const result = [`${chalk.dim(timestamp)} ${chalk.cyan(entry.from)}: ${contentColor(lines[0])}`];
+	if (lines.length > 1) {
+		const indent = " ".repeat(timestamp.length + 1 + entry.from.length + 2);
+		result.push(...lines.slice(1).map((line) => indent + contentColor(line)));
+	}
+	return result.join("\n");
+}
+
+//#endregion
+//#region src/workflow/display.ts
+/**
+* Channel display formatting
+*
+* All output flows through the channel. This module formats and filters
+* channel entries for terminal display:
+* - kind=undefined (agent messages): always shown, colored
+* - kind="log" (operational logs): always shown, dimmed
+* - kind="debug" (debug details): only shown with --debug flag
+*
+* Two display modes:
+* - TTY (human): colored, aligned columns, smart wrapping
+* - Non-TTY (agent/pipe): plain text, no colors, simple separators
+*
+* Best practices implemented:
+* - Adaptive layout based on terminal width and agent names
+* - Smart text wrapping preserving ANSI colors
+* - Message grouping to reduce visual noise
+* - Background-agnostic color scheme
+*/
+/** Whether to use rich terminal formatting */
+const isTTY = !!process.stdout.isTTY && !process.env.NO_COLOR;
+/**
+* Background-agnostic color scheme
+* Uses only bold and standard colors that work on any theme
+*/
+const C = {
+	dim: isTTY ? chalk.dim : (s) => s,
+	bold: isTTY ? chalk.bold : (s) => s,
+	yellow: isTTY ? chalk.yellow : (s) => s,
+	red: isTTY ? chalk.red : (s) => s,
+	agents: isTTY ? [
+		chalk.cyan,
+		chalk.yellow,
+		chalk.magenta,
+		chalk.green,
+		chalk.blue,
+		chalk.redBright
+	] : Array(6).fill((s) => s),
+	system: isTTY ? chalk.gray : (s) => s
+};
+/**
+* Create display context for a workflow
+*/
+function createDisplayContext(agentNames, options) {
+	return {
+		layout: calculateLayout({ agentNames }),
+		grouping: createGroupingState(),
+		agentNames,
+		enableGrouping: options?.enableGrouping ?? true,
+		debugMode: options?.debugMode ?? false
+	};
+}
+function sleep$1(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+* Format a channel entry for display
+*
+* Two modes:
+* - Normal mode: Timeline-style layout for visual clarity
+* - Debug mode: Standard log format (timestamp source: message)
+*/
+function formatChannelEntry(entry, context) {
+	if (context.debugMode) return formatStandardLog(entry, false);
+	const isFirstMessage = !shouldGroup(entry.from, entry.timestamp, context.grouping, false);
+	return formatTimelineLog(entry, context.layout, isFirstMessage);
+}
+/**
+* Start watching channel and displaying new entries
+* with adaptive layout and smart formatting
+*/
+function startChannelWatcher(config) {
+	const { contextProvider, agentNames, log, showDebug = false, pollInterval = 500, enableGrouping = true } = config;
+	resetTimeTracking();
+	const context = createDisplayContext(agentNames, {
+		enableGrouping: !showDebug && enableGrouping,
+		debugMode: showDebug
+	});
+	let cursor = config.initialCursor ?? 0;
+	let running = true;
+	const poll = async () => {
+		while (running) {
+			try {
+				const tail = await contextProvider.tailChannel(cursor);
+				for (const entry of tail.entries) {
+					if (entry.kind === "debug" && !showDebug) continue;
+					log(formatChannelEntry(entry, context));
+				}
+				cursor = tail.cursor;
+			} catch {}
+			await sleep$1(pollInterval);
+		}
+	};
+	poll();
+	return { stop: () => {
+		running = false;
+	} };
+}
+
+//#endregion
+//#region src/workflow/logger.ts
+/**
+* Create a silent logger (no output)
+*/
+function createSilentLogger() {
+	const noop = () => {};
+	return {
+		debug: noop,
+		info: noop,
+		warn: noop,
+		error: noop,
+		isDebug: () => false,
+		child: () => createSilentLogger()
+	};
+}
+/**
+* Create a logger that writes to the channel.
+*
+* - info/warn/error → channel entry with kind="log" (always shown to user)
+* - debug → channel entry with kind="debug" (only shown with --debug)
+*
+* The display layer handles formatting and filtering.
+*/
+function createChannelLogger(config) {
+	const { provider, from = "system" } = config;
+	const formatContent = (level, message, args) => {
+		const argsStr = args.length > 0 ? " " + args.map(formatArg).join(" ") : "";
+		if (level === "warn") return `[WARN] ${message}${argsStr}`;
+		if (level === "error") return `[ERROR] ${message}${argsStr}`;
+		return `${message}${argsStr}`;
+	};
+	const write = (level, message, args) => {
+		const content = formatContent(level, message, args);
+		const kind = level === "debug" ? "debug" : "log";
+		provider.appendChannel(from, content, { kind }).catch(() => {});
+	};
+	return {
+		debug: (message, ...args) => write("debug", message, args),
+		info: (message, ...args) => write("info", message, args),
+		warn: (message, ...args) => write("warn", message, args),
+		error: (message, ...args) => write("error", message, args),
+		isDebug: () => true,
+		child: (childPrefix) => {
+			return createChannelLogger({
+				provider,
+				from: from ? `${from}:${childPrefix}` : childPrefix
+			});
+		}
+	};
+}
+/** Format an argument for logging */
+function formatArg(arg) {
+	if (arg === null || arg === void 0) return String(arg);
+	if (typeof arg === "object") try {
+		return JSON.stringify(arg);
+	} catch {
+		return String(arg);
+	}
+	return String(arg);
+}
+
+//#endregion
+//#region src/workflow/runner.ts
+/**
+* Workflow Runner
+*
+* All output flows through the channel:
+* - Operational events (init, setup, connect) → kind="log" (always visible)
+* - Debug details (MCP traces, idle checks) → kind="debug" (visible with --debug)
+* - Agent messages → kind=undefined (always visible)
+*
+* The display layer (display.ts) handles filtering and formatting.
+*/
+const execAsync = promisify(exec);
+/**
+* Create context provider and resolve context directory from workflow config.
+* Extracted so the channel logger can be created before full init.
+*/
+function createWorkflowProvider(workflow, _workflowName, tag) {
+	const agentNames = Object.keys(workflow.agents);
+	if (!workflow.context) throw new Error("Workflow context is disabled. Remove \"context: false\" to enable agent collaboration.");
+	const resolvedContext = workflow.context;
+	if (resolvedContext.provider === "memory") return {
+		contextProvider: createMemoryContextProvider(agentNames),
+		contextDir: join(tmpdir(), `agent-worker-${workflow.name}-${tag}`),
+		persistent: false
+	};
+	const fileContext = resolvedContext;
+	const contextDir = fileContext.dir;
+	const persistent = fileContext.persistent === true;
+	if (!existsSync(contextDir)) mkdirSync(contextDir, { recursive: true });
+	const fileProvider = createFileContextProvider(contextDir, agentNames);
+	fileProvider.acquireLock();
+	return {
+		contextProvider: fileProvider,
+		contextDir,
+		persistent
+	};
+}
+/**
+* Initialize workflow runtime
+*
+* This sets up:
+* 1. Context provider (file or memory) — or uses pre-created one
+* 2. Context directory (for file provider)
+* 3. MCP server (HTTP)
+* 4. Runs setup commands
+*/
+async function initWorkflow(config) {
+	const { workflow, workflowName: workflowNameParam, tag: tagParam, instance, onMention, debugLog, feedback: feedbackEnabled } = config;
+	const workflowName = workflowNameParam ?? instance ?? "global";
+	const tag = tagParam ?? "main";
+	const logger = config.logger ?? createSilentLogger();
+	const startTime = Date.now();
+	const agentNames = Object.keys(workflow.agents);
+	let contextProvider;
+	let contextDir;
+	let isPersistent = false;
+	if (config.contextProvider && config.contextDir) {
+		contextProvider = config.contextProvider;
+		contextDir = config.contextDir;
+		isPersistent = config.persistent ?? false;
+		logger.debug("Using pre-created context provider");
+	} else {
+		const created = createWorkflowProvider(workflow, workflowName, tag);
+		contextProvider = created.contextProvider;
+		contextDir = created.contextDir;
+		isPersistent = created.persistent;
+		const mode = isPersistent ? "persistent (bind)" : "ephemeral";
+		logger.debug(`Context directory: ${contextDir} [${mode}]`);
+		await contextProvider.markRunStart();
+	}
+	const projectDir = process.cwd();
+	let mcpGetFeedback;
+	const createMCPServerInstance = () => {
+		const mcp = createContextMCPServer({
+			provider: contextProvider,
+			validAgents: agentNames,
+			name: `${workflow.name}-context`,
+			version: "1.0.0",
+			onMention,
+			feedback: feedbackEnabled,
+			debugLog
+		});
+		mcpGetFeedback = mcp.getFeedback;
+		return mcp.server;
+	};
+	const httpMcpServer = await runWithHttp({
+		createServerInstance: createMCPServerInstance,
+		port: 0,
+		onConnect: (agentId, sessionId) => {
+			logger.debug(`Agent connected: ${agentId} (${sessionId.slice(0, 8)})`);
+		},
+		onDisconnect: (agentId, sessionId) => {
+			logger.debug(`Agent disconnected: ${agentId} (${sessionId.slice(0, 8)})`);
+		}
+	});
+	logger.debug(`MCP server: ${httpMcpServer.url}`);
+	const setupResults = {};
+	const context = createContext(workflow.name, tag, setupResults);
+	if (workflow.setup && workflow.setup.length > 0) {
+		logger.info("Running setup...");
+		for (const task of workflow.setup) try {
+			const result = await runSetupTask(task, context, logger);
+			if (task.as) {
+				setupResults[task.as] = result;
+				context[task.as] = result;
+			}
+		} catch (error) {
+			if (contextProvider instanceof FileContextProvider) contextProvider.releaseLock();
+			await httpMcpServer.close();
+			throw new Error(`Setup failed: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	const interpolatedKickoff = workflow.kickoff ? interpolate(workflow.kickoff, context, (msg) => logger.warn(msg)) : void 0;
+	const runtime = {
+		name: workflow.name,
+		instance: instance ?? `${workflowName}:${tag}`,
+		contextDir,
+		projectDir,
+		contextProvider,
+		httpMcpServer,
+		mcpUrl: httpMcpServer.url,
+		agentNames,
+		setupResults,
+		async sendKickoff() {
+			if (!interpolatedKickoff) {
+				logger.debug("No kickoff message configured");
+				return;
+			}
+			logger.debug(`Kickoff: ${interpolatedKickoff.slice(0, 100)}...`);
+			await contextProvider.appendChannel("system", interpolatedKickoff);
+		},
+		async shutdown() {
+			logger.debug("Shutting down...");
+			if (isPersistent) {
+				if (contextProvider instanceof FileContextProvider) contextProvider.releaseLock();
+			} else await contextProvider.destroy();
+			await httpMcpServer.close();
+		},
+		getFeedback: mcpGetFeedback
+	};
+	logger.debug(`Workflow initialized in ${Date.now() - startTime}ms`);
+	logger.debug(`Agents: ${agentNames.join(", ")}`);
+	return runtime;
+}
+/**
+* Run a setup task
+*/
+async function runSetupTask(task, context, logger) {
+	const command = interpolate(task.shell, context);
+	const displayCmd = command.length > 60 ? command.slice(0, 60) + "..." : command;
+	logger.debug(`  $ ${displayCmd}`);
+	try {
+		const { stdout, stderr } = await execAsync(command);
+		const result = stdout.trim();
+		if (stderr && stderr.trim()) logger.debug(`  stderr: ${stderr.trim().slice(0, 100)}${stderr.length > 100 ? "..." : ""}`);
+		if (task.as) {
+			const displayResult = result.length > 60 ? result.slice(0, 60) + "..." : result;
+			logger.debug(`  ${task.as} = ${displayResult}`);
+		}
+		return result;
+	} catch (error) {
+		throw new Error(`Command failed: ${command}\n${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+/**
+* Run a workflow with agent controllers
+*
+* All output flows through the channel. The channel watcher (display layer)
+* filters what to show: --debug includes kind="debug" entries.
+*/
+async function runWorkflowWithControllers(config) {
+	const { workflow, workflowName: workflowNameParam, tag: tagParam, instance, debug = false, log = console.log, mode = "run", pollInterval = 5e3, createBackend, feedback: feedbackEnabled } = config;
+	const startTime = Date.now();
+	const workflowName = workflowNameParam ?? instance ?? "global";
+	const tag = tagParam ?? "main";
+	try {
+		const { contextProvider, contextDir, persistent } = createWorkflowProvider(workflow, workflowName, tag);
+		const { cursor: channelStart } = await contextProvider.tailChannel(0);
+		await contextProvider.markRunStart();
+		const logger = createChannelLogger({
+			provider: contextProvider,
+			from: "workflow"
+		});
+		logger.info(`Running workflow: ${workflow.name}`);
+		logger.info(`Agents: ${Object.keys(workflow.agents).join(", ")}`);
+		logger.debug("Starting workflow with controllers", {
+			mode,
+			instance,
+			pollInterval
+		});
+		const controllers = /* @__PURE__ */ new Map();
+		logger.debug("Initializing workflow runtime...");
+		const runtime = await initWorkflow({
+			workflow,
+			instance,
+			startAgent: async () => {},
+			logger,
+			contextProvider,
+			contextDir,
+			persistent,
+			onMention: (from, target, entry) => {
+				const controller = controllers.get(target);
+				if (controller) {
+					const preview = entry.content.length > 80 ? entry.content.slice(0, 80) + "..." : entry.content;
+					logger.debug(`@mention: ${from} → @${target} (state=${controller.state}): ${preview}`);
+					controller.wake();
+				} else logger.debug(`@mention: ${from} → @${target} (no controller found!)`);
+			},
+			debugLog: (msg) => {
+				if (msg.startsWith("CALL ")) logger.info(msg);
+				else logger.debug(msg);
+			},
+			feedback: feedbackEnabled
+		});
+		logger.debug("Runtime initialized", {
+			agentNames: runtime.agentNames,
+			mcpUrl: runtime.mcpUrl
+		});
+		logger.info("Starting agents...");
+		for (const agentName of runtime.agentNames) {
+			const agentDef = workflow.agents[agentName];
+			logger.debug(`Creating controller for ${agentName}`, {
+				backend: agentDef.backend,
+				model: agentDef.model
+			});
+			const backendDebugLog = (msg) => {
+				if (msg.startsWith("CALL ")) logger.info(msg);
+				else logger.debug(msg);
+			};
+			let backend;
+			if (createBackend) backend = createBackend(agentName, agentDef);
+			else if (agentDef.backend) backend = getBackendByType(agentDef.backend, {
+				model: agentDef.model,
+				debugLog: backendDebugLog
+			});
+			else if (agentDef.model) backend = getBackendForModel(agentDef.model, { debugLog: backendDebugLog });
+			else throw new Error(`Agent "${agentName}" requires either a backend or model field`);
+			logger.debug(`Using backend: ${backend.type} for ${agentName}`);
+			const workspaceDir = join(runtime.contextDir, "workspaces", agentName);
+			if (!existsSync(workspaceDir)) mkdirSync(workspaceDir, { recursive: true });
+			const controllerLogger = logger.child(agentName);
+			const controller = createAgentController({
+				name: agentName,
+				agent: agentDef,
+				contextProvider: runtime.contextProvider,
+				mcpUrl: runtime.mcpUrl,
+				workspaceDir,
+				projectDir: runtime.projectDir,
+				backend,
+				pollInterval,
+				log: (msg) => controllerLogger.debug(msg),
+				errorLog: (msg) => controllerLogger.error(msg),
+				feedback: feedbackEnabled
+			});
+			controllers.set(agentName, controller);
+			await controller.start();
+			logger.debug(`Controller started: ${agentName}`);
+		}
+		logger.debug("Sending kickoff message...");
+		await runtime.sendKickoff();
+		logger.debug("Kickoff sent");
+		const channelWatcher = startChannelWatcher({
+			contextProvider: runtime.contextProvider,
+			agentNames: runtime.agentNames,
+			log,
+			showDebug: debug,
+			initialCursor: channelStart,
+			pollInterval: 250
+		});
+		if (mode === "run") {
+			logger.debug("Running in \"run\" mode, waiting for completion...");
+			let idleCheckCount = 0;
+			while (true) {
+				const isIdle = await checkWorkflowIdle(controllers, runtime.contextProvider);
+				idleCheckCount++;
+				if (idleCheckCount % 10 === 0) {
+					const states = [...controllers.entries()].map(([n, c]) => `${n}=${c.state}`).join(", ");
+					logger.debug(`Idle check #${idleCheckCount}: ${states}`);
+					for (const [agentName] of controllers) {
+						const inbox = await runtime.contextProvider.getInbox(agentName);
+						if (inbox.length > 0) {
+							const unseenCount = inbox.filter((m) => !m.seen).length;
+							const seenCount = inbox.filter((m) => m.seen).length;
+							const parts = [];
+							if (seenCount > 0) parts.push(`${seenCount} processing`);
+							if (unseenCount > 0) parts.push(`${unseenCount} unread`);
+							logger.debug(`  ${agentName} inbox: ${parts.join(", ")} from [${inbox.map((m) => m.entry.from).join(", ")}]`);
+						}
+					}
+				}
+				if (isIdle) {
+					const elapsed = ((Date.now() - startTime) / 1e3).toFixed(1);
+					logger.info(`Workflow complete (${elapsed}s)`);
+					break;
+				}
+				await sleep(1e3);
+			}
+			channelWatcher?.stop();
+			await shutdownControllers(controllers, logger);
+			await runtime.shutdown();
+			logger.debug(`Workflow finished in ${Date.now() - startTime}ms`);
+			return {
+				success: true,
+				setupResults: runtime.setupResults,
+				duration: Date.now() - startTime,
+				mcpUrl: runtime.mcpUrl,
+				contextProvider: runtime.contextProvider,
+				feedback: runtime.getFeedback?.()
+			};
+		}
+		logger.debug("Running in \"start\" mode, returning control to caller");
+		return {
+			success: true,
+			setupResults: runtime.setupResults,
+			duration: Date.now() - startTime,
+			mcpUrl: runtime.mcpUrl,
+			contextProvider: runtime.contextProvider,
+			controllers,
+			shutdown: async () => {
+				channelWatcher?.stop();
+				await shutdownControllers(controllers, logger);
+				await runtime.shutdown();
+			},
+			getFeedback: runtime.getFeedback
+		};
+	} catch (error) {
+		const errorMsg = error instanceof Error ? error.message : String(error);
+		log(`Error: ${errorMsg}`);
+		return {
+			success: false,
+			error: errorMsg,
+			setupResults: {},
+			duration: Date.now() - startTime
+		};
+	}
+}
+/**
+* Gracefully shutdown all controllers
+*/
+async function shutdownControllers(controllers, logger) {
+	logger.debug("Stopping controllers...");
+	const stopPromises = [...controllers.values()].map(async (controller) => {
+		await controller.stop();
+		logger.debug(`Stopped controller: ${controller.name}`);
+	});
+	await Promise.all(stopPromises);
+	logger.debug("All controllers stopped");
+}
+/**
+* Sleep helper
+*/
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+//#endregion
+export { parseWorkflowFile, runWorkflowWithControllers };