@xopcai/xopc 0.0.84 → 0.0.85

package/dist/src/agent/workflow/runtime.js

@@ -0,0 +1,301 @@
+import { parseWorkflowScript } from "./parser.js";
+import { availableParallelism } from "node:os";
+import { Script, createContext } from "node:vm";
+//#region src/agent/workflow/runtime.ts
+/**
+* Sandboxed workflow runtime.
+*
+* Parses the script via {@link parseWorkflowScript} (which strips the `meta`
+* export), wraps the remaining body in an async IIFE, and runs it inside a
+* Node `vm` context with a curated set of globals:
+*
+*   - `agent(prompt, opts)` — spawns a subagent through the injected
+*     {@link SubagentRunner} and returns its result (string, or schema-validated
+*     object). Failures resolve to `null`.
+*   - `parallel(thunks)` — concurrent fan-out; thunks (not promises!) so the
+*     limiter sees each agent() call.
+*   - `pipeline(items, ...stages)` — per-item sequential stages, items run
+*     concurrently (no stage barrier). Each stage receives
+*     `(prevResult, originalItem, index)`. A stage that throws drops that item
+*     to `null` and skips remaining stages.
+*   - `phase(title)` — marks the current phase; surfaces through `onPhase`.
+*   - `log(message)` — appends to the workflow log.
+*   - `budget` — `{ total, spent(), remaining() }` for self-pacing scripts.
+*   - `args`, `cwd`, `process.cwd()`.
+*
+* The runtime is the only code that touches `vm`. It exposes no IO surface,
+* carries no LLM dependency, and is fully driven by injected callbacks — that
+* means the workflow tool, tests, and any future runner share one runtime.
+*/
+const DEFAULT_CONCURRENCY_FLOOR = 1;
+const DEFAULT_CONCURRENCY_CEILING = 16;
+const DEFAULT_MAX_SUBAGENTS = 1e3;
+async function runWorkflow(script, deps, options) {
+	const started = Date.now();
+	const { meta, body } = parseWorkflowScript(script);
+	const state = {
+		logs: [],
+		phases: [],
+		agentCount: 0,
+		spent: 0
+	};
+	const concurrency = clampConcurrency(options.concurrency);
+	const maxSubagents = Math.max(1, options.maxSubagents ?? DEFAULT_MAX_SUBAGENTS);
+	const limiter = createLimiter(concurrency);
+	const pendingAgentRuns = /* @__PURE__ */ new Set();
+	const log = (message) => {
+		const text = String(message);
+		state.logs.push(text);
+		options.onLog?.(text);
+	};
+	const phase = (title) => {
+		const text = requireString(title, "phase title");
+		state.currentPhase = text;
+		if (!state.phases.includes(text)) state.phases.push(text);
+		options.onPhase?.(text);
+	};
+	const budget = Object.freeze({
+		total: options.tokenBudget ?? null,
+		spent: () => state.spent,
+		remaining: () => options.tokenBudget == null ? Number.POSITIVE_INFINITY : Math.max(0, options.tokenBudget - state.spent)
+	});
+	const throwIfAborted = () => {
+		if (options.signal?.aborted) throw new Error("workflow aborted");
+	};
+	const agent = async (prompt, agentOptions = {}) => {
+		throwIfAborted();
+		if (budget.total !== null && budget.remaining() <= 0) throw new Error("workflow token budget exhausted");
+		if (state.agentCount >= maxSubagents) throw new Error(`workflow agent quota exhausted (max ${maxSubagents})`);
+		const taskPrompt = requireString(prompt, "agent prompt");
+		const normalized = normalizeAgentOptions(agentOptions);
+		const assignedPhase = normalized.phase ?? state.currentPhase;
+		const requestedLabel = normalized.label?.trim();
+		const runPromise = limiter(async () => {
+			state.agentCount += 1;
+			const id = state.agentCount;
+			const label = requestedLabel || defaultAgentLabel(assignedPhase, id);
+			options.onAgentStart?.({
+				id,
+				label,
+				phase: assignedPhase,
+				prompt: taskPrompt
+			});
+			try {
+				throwIfAborted();
+				const result = await deps.runner.run(taskPrompt, {
+					label,
+					schema: normalized.schema,
+					allowedToolNames: normalized.toolset,
+					maxIterations: normalized.maxIterations,
+					phase: assignedPhase,
+					signal: options.signal,
+					instructions: normalized.model ? `The parent workflow requested model "${normalized.model}".` : void 0
+				});
+				throwIfAborted();
+				const status = result === null ? "error" : "done";
+				state.spent += estimateTokens(result);
+				options.onAgentEnd?.({
+					id,
+					label,
+					phase: assignedPhase,
+					result,
+					status
+				});
+				return result;
+			} catch (e) {
+				if (options.signal?.aborted) {
+					options.onAgentEnd?.({
+						id,
+						label,
+						phase: assignedPhase,
+						result: null,
+						status: "skipped"
+					});
+					throw e;
+				}
+				log(`agent ${label} failed: ${e instanceof Error ? e.message : String(e)}`);
+				options.onAgentEnd?.({
+					id,
+					label,
+					phase: assignedPhase,
+					result: null,
+					status: "error"
+				});
+				return null;
+			}
+		});
+		pendingAgentRuns.add(runPromise);
+		runPromise.then(() => pendingAgentRuns.delete(runPromise), () => pendingAgentRuns.delete(runPromise));
+		return runPromise;
+	};
+	const parallel = async (thunks) => {
+		throwIfAborted();
+		if (!Array.isArray(thunks)) throw new TypeError("parallel() expects an array of functions");
+		for (const t of thunks) if (typeof t !== "function") throw new TypeError("parallel() expects an array of functions, not promises. Wrap each call: () => agent(...)");
+		return Promise.all(thunks.map(async (thunk, index) => {
+			try {
+				return await thunk();
+			} catch (e) {
+				if (options.signal?.aborted) throw e;
+				log(`parallel[${index}] failed: ${e instanceof Error ? e.message : String(e)}`);
+				return null;
+			}
+		}));
+	};
+	const pipeline = async (items, ...stages) => {
+		throwIfAborted();
+		if (!Array.isArray(items)) throw new TypeError("pipeline() expects an array as the first argument");
+		for (const stage of stages) if (typeof stage !== "function") throw new TypeError("pipeline() stages must be functions: pipeline(items, item => ..., result => ...)");
+		const typedStages = stages;
+		return Promise.all(items.map(async (item, index) => {
+			let value = item;
+			for (const stage of typedStages) try {
+				throwIfAborted();
+				value = await stage(value, item, index);
+				throwIfAborted();
+			} catch (e) {
+				if (options.signal?.aborted) throw e;
+				log(`pipeline[${index}] failed: ${e instanceof Error ? e.message : String(e)}`);
+				return null;
+			}
+			return value;
+		}));
+	};
+	const context = createContext({
+		agent,
+		parallel,
+		pipeline,
+		log,
+		phase,
+		args: options.args,
+		cwd: options.cwd,
+		process: Object.freeze({ cwd: () => options.cwd }),
+		budget,
+		console: {
+			log,
+			info: log,
+			warn: (m) => log(`[warn] ${String(m)}`),
+			error: (m) => log(`[error] ${String(m)}`)
+		},
+		JSON,
+		Math,
+		Array,
+		Object,
+		String,
+		Number,
+		Boolean,
+		Set,
+		Map,
+		Promise
+	});
+	const script$ = new Script(`(async () => {\n${body}\n})()`, { filename: `${meta.name}.workflow.js` });
+	let result;
+	try {
+		result = await script$.runInContext(context);
+		await Promise.allSettled([...pendingAgentRuns]);
+	} catch (e) {
+		await Promise.allSettled([...pendingAgentRuns]);
+		throw e;
+	}
+	assertStructuredCloneable(result, "workflow result");
+	return {
+		meta,
+		result,
+		logs: state.logs,
+		phases: state.phases,
+		agentCount: state.agentCount,
+		durationMs: Date.now() - started
+	};
+}
+function emptySnapshotFor(name, description) {
+	return {
+		name,
+		description,
+		phases: [],
+		logs: [],
+		agents: [],
+		agentCount: 0,
+		runningCount: 0,
+		doneCount: 0,
+		errorCount: 0,
+		skippedCount: 0
+	};
+}
+function clampConcurrency(requested) {
+	if (typeof requested === "number" && Number.isFinite(requested) && requested >= 1) return Math.min(Math.floor(requested), DEFAULT_CONCURRENCY_CEILING);
+	let cpu = DEFAULT_CONCURRENCY_CEILING;
+	try {
+		cpu = availableParallelism();
+	} catch {}
+	return Math.max(DEFAULT_CONCURRENCY_FLOOR, Math.min(DEFAULT_CONCURRENCY_CEILING, cpu - 2));
+}
+function createLimiter(limit) {
+	let active = 0;
+	const queue = [];
+	const next = () => {
+		active -= 1;
+		const resume = queue.shift();
+		if (resume) resume();
+	};
+	return async (fn) => {
+		if (active >= limit) await new Promise((resolve) => queue.push(resolve));
+		active += 1;
+		try {
+			return await fn();
+		} finally {
+			next();
+		}
+	};
+}
+function requireString(value, name) {
+	if (typeof value !== "string") throw new TypeError(`${name} must be a string`);
+	return value;
+}
+function optionalString(value, name) {
+	if (value === void 0) return void 0;
+	return requireString(value, name);
+}
+function normalizeAgentOptions(value) {
+	if (value === void 0 || value === null) return {};
+	if (typeof value !== "object") throw new TypeError("agent options must be an object");
+	const options = value;
+	const toolset = options.toolset;
+	if (toolset !== void 0) {
+		if (!Array.isArray(toolset) || toolset.some((t) => typeof t !== "string")) throw new TypeError("agent toolset must be an array of strings");
+	}
+	const maxIterations = options.maxIterations;
+	if (maxIterations !== void 0) {
+		if (typeof maxIterations !== "number" || !Number.isFinite(maxIterations) || maxIterations < 1) throw new TypeError("agent maxIterations must be a positive number");
+	}
+	return {
+		label: optionalString(options.label, "agent label"),
+		phase: optionalString(options.phase, "agent phase"),
+		schema: options.schema,
+		model: optionalString(options.model, "agent model"),
+		toolset,
+		maxIterations
+	};
+}
+function assertStructuredCloneable(value, name) {
+	try {
+		structuredClone(value);
+	} catch (e) {
+		const detail = e instanceof Error ? ` ${e.message}` : "";
+		throw new Error(`${name} must be structured-cloneable; did you forget to await agent(), parallel(), or pipeline()?${detail}`);
+	}
+}
+function defaultAgentLabel(phase, index) {
+	return phase ? `${phase} agent ${index}` : `agent ${index}`;
+}
+function estimateTokens(value) {
+	if (value === null || value === void 0) return 0;
+	try {
+		return Math.ceil(JSON.stringify(value).length / 4);
+	} catch {
+		return Math.ceil(String(value).length / 4);
+	}
+}
+//#endregion
+export { emptySnapshotFor, runWorkflow };
+
+//# sourceMappingURL=runtime.js.map

package/dist/src/agent/workflow/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","names":[],"sources":["../../../../src/agent/workflow/runtime.ts"],"sourcesContent":["/**\n * Sandboxed workflow runtime.\n *\n * Parses the script via {@link parseWorkflowScript} (which strips the `meta`\n * export), wraps the remaining body in an async IIFE, and runs it inside a\n * Node `vm` context with a curated set of globals:\n *\n *   - `agent(prompt, opts)` — spawns a subagent through the injected\n *     {@link SubagentRunner} and returns its result (string, or schema-validated\n *     object). Failures resolve to `null`.\n *   - `parallel(thunks)` — concurrent fan-out; thunks (not promises!) so the\n *     limiter sees each agent() call.\n *   - `pipeline(items, ...stages)` — per-item sequential stages, items run\n *     concurrently (no stage barrier). Each stage receives\n *     `(prevResult, originalItem, index)`. A stage that throws drops that item\n *     to `null` and skips remaining stages.\n *   - `phase(title)` — marks the current phase; surfaces through `onPhase`.\n *   - `log(message)` — appends to the workflow log.\n *   - `budget` — `{ total, spent(), remaining() }` for self-pacing scripts.\n *   - `args`, `cwd`, `process.cwd()`.\n *\n * The runtime is the only code that touches `vm`. It exposes no IO surface,\n * carries no LLM dependency, and is fully driven by injected callbacks — that\n * means the workflow tool, tests, and any future runner share one runtime.\n */\n\nimport { availableParallelism } from 'node:os';\nimport { createContext, Script } from 'node:vm';\n\nimport { parseWorkflowScript } from './parser.js';\nimport type {\n  AgentScriptOptions,\n  SubagentRunner,\n  WorkflowRunOptions,\n  WorkflowRunResult,\n  WorkflowSnapshot,\n  WorkflowAgentStatus,\n} from './types.js';\n\nconst DEFAULT_CONCURRENCY_FLOOR = 1;\nconst DEFAULT_CONCURRENCY_CEILING = 16;\nconst DEFAULT_MAX_SUBAGENTS = 1000;\n\ninterface RuntimeState {\n  currentPhase?: string;\n  logs: string[];\n  phases: string[];\n  agentCount: number;\n  spent: number;\n}\n\nexport interface RunWorkflowDeps {\n  runner: SubagentRunner;\n}\n\nexport async function runWorkflow<T = unknown>(\n  script: string,\n  deps: RunWorkflowDeps,\n  options: WorkflowRunOptions,\n): Promise<WorkflowRunResult<T>> {\n  const started = Date.now();\n  const { meta, body } = parseWorkflowScript(script);\n\n  const state: RuntimeState = { logs: [], phases: [], agentCount: 0, spent: 0 };\n  const concurrency = clampConcurrency(options.concurrency);\n  const maxSubagents = Math.max(1, options.maxSubagents ?? DEFAULT_MAX_SUBAGENTS);\n  const limiter = createLimiter(concurrency);\n  const pendingAgentRuns = new Set<Promise<unknown>>();\n\n  const log = (message: unknown) => {\n    const text = String(message);\n    state.logs.push(text);\n    options.onLog?.(text);\n  };\n\n  const phase = (title: unknown) => {\n    const text = requireString(title, 'phase title');\n    state.currentPhase = text;\n    if (!state.phases.includes(text)) state.phases.push(text);\n    options.onPhase?.(text);\n  };\n\n  const budget = Object.freeze({\n    total: options.tokenBudget ?? null,\n    spent: () => state.spent,\n    remaining: () =>\n      options.tokenBudget == null\n        ? Number.POSITIVE_INFINITY\n        : Math.max(0, options.tokenBudget - state.spent),\n  });\n\n  const throwIfAborted = () => {\n    if (options.signal?.aborted) throw new Error('workflow aborted');\n  };\n\n  const agent = async (prompt: unknown, agentOptions: unknown = {}) => {\n    throwIfAborted();\n    if (budget.total !== null && budget.remaining() <= 0) {\n      throw new Error('workflow token budget exhausted');\n    }\n    if (state.agentCount >= maxSubagents) {\n      throw new Error(`workflow agent quota exhausted (max ${maxSubagents})`);\n    }\n\n    const taskPrompt = requireString(prompt, 'agent prompt');\n    const normalized = normalizeAgentOptions(agentOptions);\n    const assignedPhase = normalized.phase ?? state.currentPhase;\n    const requestedLabel = normalized.label?.trim();\n\n    const runPromise = limiter(async () => {\n      // Counter increments inside the limiter — id reflects start order, not enqueue order.\n      state.agentCount += 1;\n      const id = state.agentCount;\n      const label = requestedLabel || defaultAgentLabel(assignedPhase, id);\n      options.onAgentStart?.({ id, label, phase: assignedPhase, prompt: taskPrompt });\n\n      try {\n        throwIfAborted();\n        const result = await deps.runner.run<unknown>(taskPrompt, {\n          label,\n          schema: normalized.schema,\n          allowedToolNames: normalized.toolset,\n          maxIterations: normalized.maxIterations,\n          phase: assignedPhase,\n          signal: options.signal,\n          instructions: normalized.model\n            ? `The parent workflow requested model \"${normalized.model}\".`\n            : undefined,\n        });\n        throwIfAborted();\n\n        const status: WorkflowAgentStatus = result === null ? 'error' : 'done';\n        state.spent += estimateTokens(result);\n        options.onAgentEnd?.({ id, label, phase: assignedPhase, result, status });\n        return result;\n      } catch (e) {\n        if (options.signal?.aborted) {\n          options.onAgentEnd?.({ id, label, phase: assignedPhase, result: null, status: 'skipped' });\n          throw e;\n        }\n        const message = e instanceof Error ? e.message : String(e);\n        log(`agent ${label} failed: ${message}`);\n        options.onAgentEnd?.({ id, label, phase: assignedPhase, result: null, status: 'error' });\n        return null;\n      }\n    });\n\n    pendingAgentRuns.add(runPromise);\n    // `then` (not `finally`) keeps the bookkeeping promise from re-throwing into\n    // the unhandled-rejection channel when `runPromise` rejects on abort.\n    runPromise.then(\n      () => pendingAgentRuns.delete(runPromise),\n      () => pendingAgentRuns.delete(runPromise),\n    );\n    return runPromise;\n  };\n\n  const parallel = async (thunks: unknown) => {\n    throwIfAborted();\n    if (!Array.isArray(thunks)) throw new TypeError('parallel() expects an array of functions');\n    for (const t of thunks) {\n      if (typeof t !== 'function') {\n        throw new TypeError(\n          'parallel() expects an array of functions, not promises. Wrap each call: () => agent(...)',\n        );\n      }\n    }\n    return Promise.all(\n      thunks.map(async (thunk, index) => {\n        try {\n          return await (thunk as () => unknown)();\n        } catch (e) {\n          if (options.signal?.aborted) throw e;\n          const message = e instanceof Error ? e.message : String(e);\n          log(`parallel[${index}] failed: ${message}`);\n          return null;\n        }\n      }),\n    );\n  };\n\n  const pipeline = async (items: unknown, ...stages: Array<unknown>) => {\n    throwIfAborted();\n    if (!Array.isArray(items)) {\n      throw new TypeError('pipeline() expects an array as the first argument');\n    }\n    for (const stage of stages) {\n      if (typeof stage !== 'function') {\n        throw new TypeError(\n          'pipeline() stages must be functions: pipeline(items, item => ..., result => ...)',\n        );\n      }\n    }\n    const typedStages = stages as Array<\n      (prev: unknown, original: unknown, index: number) => unknown\n    >;\n    return Promise.all(\n      items.map(async (item, index) => {\n        let value: unknown = item;\n        for (const stage of typedStages) {\n          try {\n            throwIfAborted();\n            value = await stage(value, item, index);\n            throwIfAborted();\n          } catch (e) {\n            if (options.signal?.aborted) throw e;\n            const message = e instanceof Error ? e.message : String(e);\n            log(`pipeline[${index}] failed: ${message}`);\n            return null;\n          }\n        }\n        return value;\n      }),\n    );\n  };\n\n  const context = createContext({\n    agent,\n    parallel,\n    pipeline,\n    log,\n    phase,\n    args: options.args,\n    cwd: options.cwd,\n    process: Object.freeze({ cwd: () => options.cwd }),\n    budget,\n    console: {\n      log,\n      info: log,\n      warn: (m: unknown) => log(`[warn] ${String(m)}`),\n      error: (m: unknown) => log(`[error] ${String(m)}`),\n    },\n    JSON,\n    Math,\n    Array,\n    Object,\n    String,\n    Number,\n    Boolean,\n    Set,\n    Map,\n    Promise,\n  });\n\n  const wrapped = `(async () => {\\n${body}\\n})()`;\n  const script$ = new Script(wrapped, { filename: `${meta.name}.workflow.js` });\n\n  let result: unknown;\n  try {\n    result = await script$.runInContext(context);\n    // Wait for any agent() runs the script forgot to await before declaring success.\n    await Promise.allSettled([...pendingAgentRuns]);\n  } catch (e) {\n    // Drain pending agent calls before propagating, so the snapshot reflects final state.\n    await Promise.allSettled([...pendingAgentRuns]);\n    throw e;\n  }\n\n  assertStructuredCloneable(result, 'workflow result');\n\n  return {\n    meta,\n    result: result as T,\n    logs: state.logs,\n    phases: state.phases,\n    agentCount: state.agentCount,\n    durationMs: Date.now() - started,\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Initial snapshot helper — kept here so the runtime is the single source of\n// truth for \"what a fresh snapshot looks like for this workflow\".\n// ---------------------------------------------------------------------------\n\nexport function emptySnapshotFor(name: string, description?: string): WorkflowSnapshot {\n  return {\n    name,\n    description,\n    phases: [],\n    logs: [],\n    agents: [],\n    agentCount: 0,\n    runningCount: 0,\n    doneCount: 0,\n    errorCount: 0,\n    skippedCount: 0,\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Internals\n// ---------------------------------------------------------------------------\n\nfunction clampConcurrency(requested?: number): number {\n  if (typeof requested === 'number' && Number.isFinite(requested) && requested >= 1) {\n    return Math.min(Math.floor(requested), DEFAULT_CONCURRENCY_CEILING);\n  }\n  let cpu = DEFAULT_CONCURRENCY_CEILING;\n  try {\n    cpu = availableParallelism();\n  } catch {\n    // Some sandboxes throw; fall back to the ceiling.\n  }\n  return Math.max(DEFAULT_CONCURRENCY_FLOOR, Math.min(DEFAULT_CONCURRENCY_CEILING, cpu - 2));\n}\n\nfunction createLimiter(limit: number) {\n  let active = 0;\n  const queue: Array<() => void> = [];\n  const next = () => {\n    active -= 1;\n    const resume = queue.shift();\n    if (resume) resume();\n  };\n  return async <T>(fn: () => Promise<T>): Promise<T> => {\n    if (active >= limit) {\n      await new Promise<void>((resolve) => queue.push(resolve));\n    }\n    active += 1;\n    try {\n      return await fn();\n    } finally {\n      next();\n    }\n  };\n}\n\nfunction requireString(value: unknown, name: string): string {\n  if (typeof value !== 'string') throw new TypeError(`${name} must be a string`);\n  return value;\n}\n\nfunction optionalString(value: unknown, name: string): string | undefined {\n  if (value === undefined) return undefined;\n  return requireString(value, name);\n}\n\nfunction normalizeAgentOptions(value: unknown): AgentScriptOptions {\n  if (value === undefined || value === null) return {};\n  if (typeof value !== 'object') throw new TypeError('agent options must be an object');\n  const options = value as AgentScriptOptions;\n  const toolset = options.toolset;\n  if (toolset !== undefined) {\n    if (!Array.isArray(toolset) || toolset.some((t) => typeof t !== 'string')) {\n      throw new TypeError('agent toolset must be an array of strings');\n    }\n  }\n  const maxIterations = options.maxIterations;\n  if (maxIterations !== undefined) {\n    if (typeof maxIterations !== 'number' || !Number.isFinite(maxIterations) || maxIterations < 1) {\n      throw new TypeError('agent maxIterations must be a positive number');\n    }\n  }\n  return {\n    label: optionalString(options.label, 'agent label'),\n    phase: optionalString(options.phase, 'agent phase'),\n    schema: options.schema,\n    model: optionalString(options.model, 'agent model'),\n    toolset,\n    maxIterations,\n  };\n}\n\nfunction assertStructuredCloneable(value: unknown, name: string): void {\n  try {\n    structuredClone(value);\n  } catch (e) {\n    const detail = e instanceof Error ? ` ${e.message}` : '';\n    throw new Error(\n      `${name} must be structured-cloneable; did you forget to await agent(), parallel(), or pipeline()?${detail}`,\n    );\n  }\n}\n\nfunction defaultAgentLabel(phase: string | undefined, index: number): string {\n  return phase ? `${phase} agent ${index}` : `agent ${index}`;\n}\n\nfunction estimateTokens(value: unknown): number {\n  if (value === null || value === undefined) return 0;\n  try {\n    return Math.ceil(JSON.stringify(value).length / 4);\n  } catch {\n    return Math.ceil(String(value).length / 4);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,MAAM,4BAA4B;AAClC,MAAM,8BAA8B;AACpC,MAAM,wBAAwB;AAc9B,eAAsB,YACpB,QACA,MACA,SAC+B;CAC/B,MAAM,UAAU,KAAK,KAAK;CAC1B,MAAM,EAAE,MAAM,SAAS,oBAAoB,OAAO;CAElD,MAAM,QAAsB;EAAE,MAAM,EAAE;EAAE,QAAQ,EAAE;EAAE,YAAY;EAAG,OAAO;EAAG;CAC7E,MAAM,cAAc,iBAAiB,QAAQ,YAAY;CACzD,MAAM,eAAe,KAAK,IAAI,GAAG,QAAQ,gBAAgB,sBAAsB;CAC/E,MAAM,UAAU,cAAc,YAAY;CAC1C,MAAM,mCAAmB,IAAI,KAAuB;CAEpD,MAAM,OAAO,YAAqB;EAChC,MAAM,OAAO,OAAO,QAAQ;AAC5B,QAAM,KAAK,KAAK,KAAK;AACrB,UAAQ,QAAQ,KAAK;;CAGvB,MAAM,SAAS,UAAmB;EAChC,MAAM,OAAO,cAAc,OAAO,cAAc;AAChD,QAAM,eAAe;AACrB,MAAI,CAAC,MAAM,OAAO,SAAS,KAAK,CAAE,OAAM,OAAO,KAAK,KAAK;AACzD,UAAQ,UAAU,KAAK;;CAGzB,MAAM,SAAS,OAAO,OAAO;EAC3B,OAAO,QAAQ,eAAe;EAC9B,aAAa,MAAM;EACnB,iBACE,QAAQ,eAAe,OACnB,OAAO,oBACP,KAAK,IAAI,GAAG,QAAQ,cAAc,MAAM,MAAM;EACrD,CAAC;CAEF,MAAM,uBAAuB;AAC3B,MAAI,QAAQ,QAAQ,QAAS,OAAM,IAAI,MAAM,mBAAmB;;CAGlE,MAAM,QAAQ,OAAO,QAAiB,eAAwB,EAAE,KAAK;AACnE,kBAAgB;AAChB,MAAI,OAAO,UAAU,QAAQ,OAAO,WAAW,IAAI,EACjD,OAAM,IAAI,MAAM,kCAAkC;AAEpD,MAAI,MAAM,cAAc,aACtB,OAAM,IAAI,MAAM,uCAAuC,aAAa,GAAG;EAGzE,MAAM,aAAa,cAAc,QAAQ,eAAe;EACxD,MAAM,aAAa,sBAAsB,aAAa;EACtD,MAAM,gBAAgB,WAAW,SAAS,MAAM;EAChD,MAAM,iBAAiB,WAAW,OAAO,MAAM;EAE/C,MAAM,aAAa,QAAQ,YAAY;AAErC,SAAM,cAAc;GACpB,MAAM,KAAK,MAAM;GACjB,MAAM,QAAQ,kBAAkB,kBAAkB,eAAe,GAAG;AACpE,WAAQ,eAAe;IAAE;IAAI;IAAO,OAAO;IAAe,QAAQ;IAAY,CAAC;AAE/E,OAAI;AACF,oBAAgB;IAChB,MAAM,SAAS,MAAM,KAAK,OAAO,IAAa,YAAY;KACxD;KACA,QAAQ,WAAW;KACnB,kBAAkB,WAAW;KAC7B,eAAe,WAAW;KAC1B,OAAO;KACP,QAAQ,QAAQ;KAChB,cAAc,WAAW,QACrB,wCAAwC,WAAW,MAAM,MACzD,KAAA;KACL,CAAC;AACF,oBAAgB;IAEhB,MAAM,SAA8B,WAAW,OAAO,UAAU;AAChE,UAAM,SAAS,eAAe,OAAO;AACrC,YAAQ,aAAa;KAAE;KAAI;KAAO,OAAO;KAAe;KAAQ;KAAQ,CAAC;AACzE,WAAO;YACA,GAAG;AACV,QAAI,QAAQ,QAAQ,SAAS;AAC3B,aAAQ,aAAa;MAAE;MAAI;MAAO,OAAO;MAAe,QAAQ;MAAM,QAAQ;MAAW,CAAC;AAC1F,WAAM;;AAGR,QAAI,SAAS,MAAM,WADH,aAAa,QAAQ,EAAE,UAAU,OAAO,EAAE,GAClB;AACxC,YAAQ,aAAa;KAAE;KAAI;KAAO,OAAO;KAAe,QAAQ;KAAM,QAAQ;KAAS,CAAC;AACxF,WAAO;;IAET;AAEF,mBAAiB,IAAI,WAAW;AAGhC,aAAW,WACH,iBAAiB,OAAO,WAAW,QACnC,iBAAiB,OAAO,WAAW,CAC1C;AACD,SAAO;;CAGT,MAAM,WAAW,OAAO,WAAoB;AAC1C,kBAAgB;AAChB,MAAI,CAAC,MAAM,QAAQ,OAAO,CAAE,OAAM,IAAI,UAAU,2CAA2C;AAC3F,OAAK,MAAM,KAAK,OACd,KAAI,OAAO,MAAM,WACf,OAAM,IAAI,UACR,2FACD;AAGL,SAAO,QAAQ,IACb,OAAO,IAAI,OAAO,OAAO,UAAU;AACjC,OAAI;AACF,WAAO,MAAO,OAAyB;YAChC,GAAG;AACV,QAAI,QAAQ,QAAQ,QAAS,OAAM;AAEnC,QAAI,YAAY,MAAM,YADN,aAAa,QAAQ,EAAE,UAAU,OAAO,EAAE,GACd;AAC5C,WAAO;;IAET,CACH;;CAGH,MAAM,WAAW,OAAO,OAAgB,GAAG,WAA2B;AACpE,kBAAgB;AAChB,MAAI,CAAC,MAAM,QAAQ,MAAM,CACvB,OAAM,IAAI,UAAU,oDAAoD;AAE1E,OAAK,MAAM,SAAS,OAClB,KAAI,OAAO,UAAU,WACnB,OAAM,IAAI,UACR,mFACD;EAGL,MAAM,cAAc;AAGpB,SAAO,QAAQ,IACb,MAAM,IAAI,OAAO,MAAM,UAAU;GAC/B,IAAI,QAAiB;AACrB,QAAK,MAAM,SAAS,YAClB,KAAI;AACF,oBAAgB;AAChB,YAAQ,MAAM,MAAM,OAAO,MAAM,MAAM;AACvC,oBAAgB;YACT,GAAG;AACV,QAAI,QAAQ,QAAQ,QAAS,OAAM;AAEnC,QAAI,YAAY,MAAM,YADN,aAAa,QAAQ,EAAE,UAAU,OAAO,EAAE,GACd;AAC5C,WAAO;;AAGX,UAAO;IACP,CACH;;CAGH,MAAM,UAAU,cAAc;EAC5B;EACA;EACA;EACA;EACA;EACA,MAAM,QAAQ;EACd,KAAK,QAAQ;EACb,SAAS,OAAO,OAAO,EAAE,WAAW,QAAQ,KAAK,CAAC;EAClD;EACA,SAAS;GACP;GACA,MAAM;GACN,OAAO,MAAe,IAAI,UAAU,OAAO,EAAE,GAAG;GAChD,QAAQ,MAAe,IAAI,WAAW,OAAO,EAAE,GAAG;GACnD;EACD;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACD,CAAC;CAGF,MAAM,UAAU,IAAI,OAAO,mBADQ,KAAK,SACJ,EAAE,UAAU,GAAG,KAAK,KAAK,eAAe,CAAC;CAE7E,IAAI;AACJ,KAAI;AACF,WAAS,MAAM,QAAQ,aAAa,QAAQ;AAE5C,QAAM,QAAQ,WAAW,CAAC,GAAG,iBAAiB,CAAC;UACxC,GAAG;AAEV,QAAM,QAAQ,WAAW,CAAC,GAAG,iBAAiB,CAAC;AAC/C,QAAM;;AAGR,2BAA0B,QAAQ,kBAAkB;AAEpD,QAAO;EACL;EACQ;EACR,MAAM,MAAM;EACZ,QAAQ,MAAM;EACd,YAAY,MAAM;EAClB,YAAY,KAAK,KAAK,GAAG;EAC1B;;AAQH,SAAgB,iBAAiB,MAAc,aAAwC;AACrF,QAAO;EACL;EACA;EACA,QAAQ,EAAE;EACV,MAAM,EAAE;EACR,QAAQ,EAAE;EACV,YAAY;EACZ,cAAc;EACd,WAAW;EACX,YAAY;EACZ,cAAc;EACf;;AAOH,SAAS,iBAAiB,WAA4B;AACpD,KAAI,OAAO,cAAc,YAAY,OAAO,SAAS,UAAU,IAAI,aAAa,EAC9E,QAAO,KAAK,IAAI,KAAK,MAAM,UAAU,EAAE,4BAA4B;CAErE,IAAI,MAAM;AACV,KAAI;AACF,QAAM,sBAAsB;SACtB;AAGR,QAAO,KAAK,IAAI,2BAA2B,KAAK,IAAI,6BAA6B,MAAM,EAAE,CAAC;;AAG5F,SAAS,cAAc,OAAe;CACpC,IAAI,SAAS;CACb,MAAM,QAA2B,EAAE;CACnC,MAAM,aAAa;AACjB,YAAU;EACV,MAAM,SAAS,MAAM,OAAO;AAC5B,MAAI,OAAQ,SAAQ;;AAEtB,QAAO,OAAU,OAAqC;AACpD,MAAI,UAAU,MACZ,OAAM,IAAI,SAAe,YAAY,MAAM,KAAK,QAAQ,CAAC;AAE3D,YAAU;AACV,MAAI;AACF,UAAO,MAAM,IAAI;YACT;AACR,SAAM;;;;AAKZ,SAAS,cAAc,OAAgB,MAAsB;AAC3D,KAAI,OAAO,UAAU,SAAU,OAAM,IAAI,UAAU,GAAG,KAAK,mBAAmB;AAC9E,QAAO;;AAGT,SAAS,eAAe,OAAgB,MAAkC;AACxE,KAAI,UAAU,KAAA,EAAW,QAAO,KAAA;AAChC,QAAO,cAAc,OAAO,KAAK;;AAGnC,SAAS,sBAAsB,OAAoC;AACjE,KAAI,UAAU,KAAA,KAAa,UAAU,KAAM,QAAO,EAAE;AACpD,KAAI,OAAO,UAAU,SAAU,OAAM,IAAI,UAAU,kCAAkC;CACrF,MAAM,UAAU;CAChB,MAAM,UAAU,QAAQ;AACxB,KAAI,YAAY,KAAA;MACV,CAAC,MAAM,QAAQ,QAAQ,IAAI,QAAQ,MAAM,MAAM,OAAO,MAAM,SAAS,CACvE,OAAM,IAAI,UAAU,4CAA4C;;CAGpE,MAAM,gBAAgB,QAAQ;AAC9B,KAAI,kBAAkB,KAAA;MAChB,OAAO,kBAAkB,YAAY,CAAC,OAAO,SAAS,cAAc,IAAI,gBAAgB,EAC1F,OAAM,IAAI,UAAU,gDAAgD;;AAGxE,QAAO;EACL,OAAO,eAAe,QAAQ,OAAO,cAAc;EACnD,OAAO,eAAe,QAAQ,OAAO,cAAc;EACnD,QAAQ,QAAQ;EAChB,OAAO,eAAe,QAAQ,OAAO,cAAc;EACnD;EACA;EACD;;AAGH,SAAS,0BAA0B,OAAgB,MAAoB;AACrE,KAAI;AACF,kBAAgB,MAAM;UACf,GAAG;EACV,MAAM,SAAS,aAAa,QAAQ,IAAI,EAAE,YAAY;AACtD,QAAM,IAAI,MACR,GAAG,KAAK,4FAA4F,SACrG;;;AAIL,SAAS,kBAAkB,OAA2B,OAAuB;AAC3E,QAAO,QAAQ,GAAG,MAAM,SAAS,UAAU,SAAS;;AAGtD,SAAS,eAAe,OAAwB;AAC9C,KAAI,UAAU,QAAQ,UAAU,KAAA,EAAW,QAAO;AAClD,KAAI;AACF,SAAO,KAAK,KAAK,KAAK,UAAU,MAAM,CAAC,SAAS,EAAE;SAC5C;AACN,SAAO,KAAK,KAAK,OAAO,MAAM,CAAC,SAAS,EAAE"}

package/dist/src/agent/workflow/snapshot.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Workflow progress snapshot model + text renderers.
+ *
+ * The runtime emits per-event callbacks (`onPhase`, `onAgentStart`, `onAgentEnd`,
+ * `onLog`). The workflow tool wraps those callbacks to mutate a snapshot and push
+ * a text rendering through `onUpdate` — keeping TUI / Gateway / IM consumers in
+ * lock-step from a single source of truth.
+ */
+import type { WorkflowMeta, WorkflowSnapshot } from './types.js';
+export declare function createWorkflowSnapshot(meta: WorkflowMeta): WorkflowSnapshot;
+export declare function recomputeCounts(snapshot: WorkflowSnapshot): void;
+export interface RenderOptions {
+    maxAgentsPerPhase?: number;
+    maxLogs?: number;
+    showResultPreviews?: boolean;
+}
+export declare function renderWorkflowText(snapshot: WorkflowSnapshot, completed?: boolean, options?: RenderOptions): string;
+export declare function previewValue(value: unknown, max?: number): string;

package/dist/src/agent/workflow/snapshot.js

@@ -0,0 +1,144 @@
+//#region src/agent/workflow/snapshot.ts
+function createWorkflowSnapshot(meta) {
+	return {
+		name: meta.name,
+		description: meta.description,
+		phases: [],
+		logs: [],
+		agents: [],
+		agentCount: 0,
+		runningCount: 0,
+		doneCount: 0,
+		errorCount: 0,
+		skippedCount: 0
+	};
+}
+function recomputeCounts(snapshot) {
+	let running = 0;
+	let done = 0;
+	let error = 0;
+	let skipped = 0;
+	for (const agent of snapshot.agents) switch (agent.status) {
+		case "running":
+			running++;
+			break;
+		case "done":
+			done++;
+			break;
+		case "error":
+			error++;
+			break;
+		case "skipped":
+			skipped++;
+			break;
+	}
+	snapshot.agentCount = snapshot.agents.length;
+	snapshot.runningCount = running;
+	snapshot.doneCount = done;
+	snapshot.errorCount = error;
+	snapshot.skippedCount = skipped;
+}
+function renderWorkflowText(snapshot, completed = false, options = {}) {
+	const maxAgentsPerPhase = options.maxAgentsPerPhase ?? 6;
+	const maxLogs = options.maxLogs ?? 2;
+	const showPreviews = options.showResultPreviews ?? false;
+	const state = stateSuffix(snapshot);
+	const lines = [completed ? `◆ workflow ✓ ${snapshot.name} (${snapshot.doneCount}/${snapshot.agentCount} done${state})` : `◆ workflow: ${snapshot.name} (${snapshot.doneCount}/${snapshot.agentCount} done${state})`];
+	const phaseNames = uniqueOrdered([
+		...snapshot.phases,
+		...snapshot.currentPhase ? [snapshot.currentPhase] : [],
+		...snapshot.agents.map((a) => a.phase).filter((p) => Boolean(p))
+	]);
+	const rendered = /* @__PURE__ */ new Set();
+	for (const phase of phaseNames) {
+		const agents = snapshot.agents.filter((a) => a.phase === phase);
+		if (agents.length === 0 && snapshot.currentPhase !== phase) continue;
+		for (const a of agents) rendered.add(a);
+		const counts = countAgents(agents);
+		const completeHere = agents.length > 0 && counts.done + counts.error + counts.skipped === agents.length;
+		const marker = counts.running > 0 || !completeHere && snapshot.currentPhase === phase ? "▶" : completeHere ? "✓" : " ";
+		const tail = (counts.running ? ` · ${counts.running} running` : "") + (counts.error ? ` · ${counts.error} errors` : "") + (counts.skipped ? ` · ${counts.skipped} skipped` : "");
+		lines.push(`  ${marker} ${phase} ${counts.done}/${agents.length}${tail}`);
+		const visible = agents.slice(-maxAgentsPerPhase);
+		for (const agent of visible) {
+			const previewText = showPreviews && agent.resultPreview ? ` — ${agent.resultPreview}` : "";
+			lines.push(`    #${agent.id} ${statusIcon(agent.status)} ${shorten(agent.label, 56)}${previewText}`);
+		}
+		if (agents.length > visible.length) lines.push(`    … ${agents.length - visible.length} earlier agents`);
+	}
+	const unphased = snapshot.agents.filter((a) => !rendered.has(a));
+	if (unphased.length > 0) {
+		lines.push("  unphased");
+		for (const agent of unphased.slice(-maxAgentsPerPhase)) {
+			const previewText = showPreviews && agent.resultPreview ? ` — ${agent.resultPreview}` : "";
+			lines.push(`    #${agent.id} ${statusIcon(agent.status)} ${shorten(agent.label, 56)}${previewText}`);
+		}
+	}
+	const visibleLogs = snapshot.logs.slice(-maxLogs);
+	if (visibleLogs.length > 0) {
+		lines.push("");
+		for (const log of visibleLogs) lines.push(`  log: ${shorten(log, 80)}`);
+	}
+	return lines.join("\n");
+}
+function previewValue(value, max = 80) {
+	if (value === null || value === void 0) return "";
+	const text = typeof value === "string" ? value : safeStringify(value);
+	if (!text) return "";
+	return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+function countAgents(agents) {
+	let done = 0;
+	let running = 0;
+	let error = 0;
+	let skipped = 0;
+	for (const a of agents) if (a.status === "done") done++;
+	else if (a.status === "running") running++;
+	else if (a.status === "error") error++;
+	else if (a.status === "skipped") skipped++;
+	return {
+		done,
+		running,
+		error,
+		skipped
+	};
+}
+function statusIcon(status) {
+	switch (status) {
+		case "queued": return "○";
+		case "running": return "●";
+		case "done": return "✓";
+		case "error": return "✗";
+		case "skipped": return "-";
+	}
+}
+function stateSuffix(snapshot) {
+	if (snapshot.errorCount > 0) return `, ${snapshot.errorCount} errors`;
+	if (snapshot.skippedCount > 0) return `, ${snapshot.skippedCount} skipped`;
+	if (snapshot.runningCount > 0) return `, ${snapshot.runningCount} running`;
+	return "";
+}
+function uniqueOrdered(values) {
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	for (const v of values) if (!seen.has(v)) {
+		seen.add(v);
+		out.push(v);
+	}
+	return out;
+}
+function shorten(value, max) {
+	const text = value.replace(/\s+/g, " ").trim();
+	return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+function safeStringify(value) {
+	try {
+		return JSON.stringify(value);
+	} catch {
+		return String(value);
+	}
+}
+//#endregion
+export { createWorkflowSnapshot, previewValue, recomputeCounts, renderWorkflowText };
+
+//# sourceMappingURL=snapshot.js.map

package/dist/src/agent/workflow/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","names":[],"sources":["../../../../src/agent/workflow/snapshot.ts"],"sourcesContent":["/**\n * Workflow progress snapshot model + text renderers.\n *\n * The runtime emits per-event callbacks (`onPhase`, `onAgentStart`, `onAgentEnd`,\n * `onLog`). The workflow tool wraps those callbacks to mutate a snapshot and push\n * a text rendering through `onUpdate` — keeping TUI / Gateway / IM consumers in\n * lock-step from a single source of truth.\n */\n\nimport type {\n  WorkflowAgentSnapshot,\n  WorkflowAgentStatus,\n  WorkflowMeta,\n  WorkflowSnapshot,\n} from './types.js';\n\nexport function createWorkflowSnapshot(meta: WorkflowMeta): WorkflowSnapshot {\n  return {\n    name: meta.name,\n    description: meta.description,\n    phases: [],\n    logs: [],\n    agents: [],\n    agentCount: 0,\n    runningCount: 0,\n    doneCount: 0,\n    errorCount: 0,\n    skippedCount: 0,\n  };\n}\n\nexport function recomputeCounts(snapshot: WorkflowSnapshot): void {\n  let running = 0;\n  let done = 0;\n  let error = 0;\n  let skipped = 0;\n  for (const agent of snapshot.agents) {\n    switch (agent.status) {\n      case 'running':\n        running++;\n        break;\n      case 'done':\n        done++;\n        break;\n      case 'error':\n        error++;\n        break;\n      case 'skipped':\n        skipped++;\n        break;\n    }\n  }\n  snapshot.agentCount = snapshot.agents.length;\n  snapshot.runningCount = running;\n  snapshot.doneCount = done;\n  snapshot.errorCount = error;\n  snapshot.skippedCount = skipped;\n}\n\nexport interface RenderOptions {\n  maxAgentsPerPhase?: number;\n  maxLogs?: number;\n  showResultPreviews?: boolean;\n}\n\nexport function renderWorkflowText(\n  snapshot: WorkflowSnapshot,\n  completed = false,\n  options: RenderOptions = {},\n): string {\n  const maxAgentsPerPhase = options.maxAgentsPerPhase ?? 6;\n  const maxLogs = options.maxLogs ?? 2;\n  const showPreviews = options.showResultPreviews ?? false;\n\n  const state = stateSuffix(snapshot);\n  const header = completed\n    ? `◆ workflow ✓ ${snapshot.name} (${snapshot.doneCount}/${snapshot.agentCount} done${state})`\n    : `◆ workflow: ${snapshot.name} (${snapshot.doneCount}/${snapshot.agentCount} done${state})`;\n  const lines = [header];\n\n  const phaseNames = uniqueOrdered([\n    ...snapshot.phases,\n    ...(snapshot.currentPhase ? [snapshot.currentPhase] : []),\n    ...snapshot.agents.map((a) => a.phase).filter((p): p is string => Boolean(p)),\n  ]);\n  const rendered = new Set<WorkflowAgentSnapshot>();\n\n  for (const phase of phaseNames) {\n    const agents = snapshot.agents.filter((a) => a.phase === phase);\n    if (agents.length === 0 && snapshot.currentPhase !== phase) continue;\n    for (const a of agents) rendered.add(a);\n\n    const counts = countAgents(agents);\n    const completeHere = agents.length > 0 && counts.done + counts.error + counts.skipped === agents.length;\n    const marker =\n      counts.running > 0 || (!completeHere && snapshot.currentPhase === phase)\n        ? '▶'\n        : completeHere\n          ? '✓'\n          : ' ';\n\n    const tail =\n      (counts.running ? ` · ${counts.running} running` : '') +\n      (counts.error ? ` · ${counts.error} errors` : '') +\n      (counts.skipped ? ` · ${counts.skipped} skipped` : '');\n    lines.push(`  ${marker} ${phase} ${counts.done}/${agents.length}${tail}`);\n\n    const visible = agents.slice(-maxAgentsPerPhase);\n    for (const agent of visible) {\n      const previewText = showPreviews && agent.resultPreview ? ` — ${agent.resultPreview}` : '';\n      lines.push(\n        `    #${agent.id} ${statusIcon(agent.status)} ${shorten(agent.label, 56)}${previewText}`,\n      );\n    }\n    if (agents.length > visible.length) {\n      lines.push(`    … ${agents.length - visible.length} earlier agents`);\n    }\n  }\n\n  const unphased = snapshot.agents.filter((a) => !rendered.has(a));\n  if (unphased.length > 0) {\n    lines.push('  unphased');\n    for (const agent of unphased.slice(-maxAgentsPerPhase)) {\n      const previewText = showPreviews && agent.resultPreview ? ` — ${agent.resultPreview}` : '';\n      lines.push(\n        `    #${agent.id} ${statusIcon(agent.status)} ${shorten(agent.label, 56)}${previewText}`,\n      );\n    }\n  }\n\n  const visibleLogs = snapshot.logs.slice(-maxLogs);\n  if (visibleLogs.length > 0) {\n    lines.push('');\n    for (const log of visibleLogs) {\n      lines.push(`  log: ${shorten(log, 80)}`);\n    }\n  }\n  return lines.join('\\n');\n}\n\nexport function previewValue(value: unknown, max = 80): string {\n  if (value === null || value === undefined) return '';\n  const text = typeof value === 'string' ? value : safeStringify(value);\n  if (!text) return '';\n  return text.length > max ? `${text.slice(0, max - 1)}…` : text;\n}\n\n// ---------------------------------------------------------------------------\n\nfunction countAgents(agents: WorkflowAgentSnapshot[]) {\n  let done = 0;\n  let running = 0;\n  let error = 0;\n  let skipped = 0;\n  for (const a of agents) {\n    if (a.status === 'done') done++;\n    else if (a.status === 'running') running++;\n    else if (a.status === 'error') error++;\n    else if (a.status === 'skipped') skipped++;\n  }\n  return { done, running, error, skipped };\n}\n\nfunction statusIcon(status: WorkflowAgentStatus): string {\n  switch (status) {\n    case 'queued':\n      return '○';\n    case 'running':\n      return '●';\n    case 'done':\n      return '✓';\n    case 'error':\n      return '✗';\n    case 'skipped':\n      return '-';\n  }\n}\n\nfunction stateSuffix(snapshot: WorkflowSnapshot): string {\n  if (snapshot.errorCount > 0) return `, ${snapshot.errorCount} errors`;\n  if (snapshot.skippedCount > 0) return `, ${snapshot.skippedCount} skipped`;\n  if (snapshot.runningCount > 0) return `, ${snapshot.runningCount} running`;\n  return '';\n}\n\nfunction uniqueOrdered(values: string[]): string[] {\n  const seen = new Set<string>();\n  const out: string[] = [];\n  for (const v of values) {\n    if (!seen.has(v)) {\n      seen.add(v);\n      out.push(v);\n    }\n  }\n  return out;\n}\n\nfunction shorten(value: string, max: number): string {\n  const text = value.replace(/\\s+/g, ' ').trim();\n  return text.length > max ? `${text.slice(0, max - 1)}…` : text;\n}\n\nfunction safeStringify(value: unknown): string {\n  try {\n    return JSON.stringify(value);\n  } catch {\n    return String(value);\n  }\n}\n"],"mappings":"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"}

package/dist/src/agent/workflow/structured-output-tool.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `structured_output` — terminating tool used to capture a subagent's final result.
+ *
+ * Injected into a subagent's toolset only when the workflow script asked for
+ * structured output via `agent(prompt, { schema })`. The subagent is instructed
+ * to invoke this tool exactly once with its final result; the tool sets
+ * `terminate: true` so the agent loop stops without paying for an extra
+ * assistant turn.
+ *
+ * Validation is done with ajv (already a xopc dep). pi-agent-core also validates
+ * arguments against `parameters` before calling `execute`, but we re-check here
+ * to (1) surface a clear error message back to the model when the schema is
+ * non-trivial, and (2) avoid trusting the upstream layer's validator strictness.
+ *
+ * Note: the file is named `structured-output-tool.ts` to avoid clashing with the
+ * existing `src/agent/tools/structured-output.ts` (an XML Element builder — a
+ * completely unrelated utility).
+ */
+import type { AgentTool } from '@earendil-works/pi-agent-core';
+import type { TSchema } from '@sinclair/typebox';
+import type { JsonSchema } from './types.js';
+export declare const STRUCTURED_OUTPUT_TOOL_NAME = "structured_output";
+export interface StructuredOutputCapture<T = unknown> {
+    called: boolean;
+    value?: T;
+}
+export interface CreateStructuredOutputToolOptions<T = unknown> {
+    schema: JsonSchema;
+    capture: StructuredOutputCapture<T>;
+    /** Override the tool name (rarely needed; default `structured_output`). */
+    name?: string;
+}
+export declare function createStructuredOutputTool<T = unknown>(options: CreateStructuredOutputToolOptions<T>): AgentTool<TSchema, T>;

package/dist/src/agent/workflow/structured-output-tool.js

@@ -0,0 +1,58 @@
+import Ajv from "ajv";
+//#region src/agent/workflow/structured-output-tool.ts
+/**
+* `structured_output` — terminating tool used to capture a subagent's final result.
+*
+* Injected into a subagent's toolset only when the workflow script asked for
+* structured output via `agent(prompt, { schema })`. The subagent is instructed
+* to invoke this tool exactly once with its final result; the tool sets
+* `terminate: true` so the agent loop stops without paying for an extra
+* assistant turn.
+*
+* Validation is done with ajv (already a xopc dep). pi-agent-core also validates
+* arguments against `parameters` before calling `execute`, but we re-check here
+* to (1) surface a clear error message back to the model when the schema is
+* non-trivial, and (2) avoid trusting the upstream layer's validator strictness.
+*
+* Note: the file is named `structured-output-tool.ts` to avoid clashing with the
+* existing `src/agent/tools/structured-output.ts` (an XML Element builder — a
+* completely unrelated utility).
+*/
+const STRUCTURED_OUTPUT_TOOL_NAME = "structured_output";
+const ajv = new Ajv({
+	allErrors: true,
+	strict: false
+});
+function createStructuredOutputTool(options) {
+	const name = options.name ?? "structured_output";
+	const validator = ajv.compile(options.schema);
+	return {
+		name,
+		label: "Structured Output",
+		description: "Return the final machine-readable result for this subagent task. Call this tool exactly once when finished. Do not emit a prose final answer afterwards.",
+		parameters: options.schema,
+		async execute(_toolCallId, params) {
+			if (!validator(params)) return {
+				content: [{
+					type: "text",
+					text: `structured_output: invalid arguments — ${ajv.errorsText(validator.errors, { separator: "; " })}. Adjust and call structured_output again.`
+				}],
+				details: params
+			};
+			options.capture.called = true;
+			options.capture.value = params;
+			return {
+				content: [{
+					type: "text",
+					text: "Structured output received."
+				}],
+				details: params,
+				terminate: true
+			};
+		}
+	};
+}
+//#endregion
+export { STRUCTURED_OUTPUT_TOOL_NAME, createStructuredOutputTool };
+
+//# sourceMappingURL=structured-output-tool.js.map

package/dist/src/agent/workflow/structured-output-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured-output-tool.js","names":[],"sources":["../../../../src/agent/workflow/structured-output-tool.ts"],"sourcesContent":["/**\n * `structured_output` — terminating tool used to capture a subagent's final result.\n *\n * Injected into a subagent's toolset only when the workflow script asked for\n * structured output via `agent(prompt, { schema })`. The subagent is instructed\n * to invoke this tool exactly once with its final result; the tool sets\n * `terminate: true` so the agent loop stops without paying for an extra\n * assistant turn.\n *\n * Validation is done with ajv (already a xopc dep). pi-agent-core also validates\n * arguments against `parameters` before calling `execute`, but we re-check here\n * to (1) surface a clear error message back to the model when the schema is\n * non-trivial, and (2) avoid trusting the upstream layer's validator strictness.\n *\n * Note: the file is named `structured-output-tool.ts` to avoid clashing with the\n * existing `src/agent/tools/structured-output.ts` (an XML Element builder — a\n * completely unrelated utility).\n */\n\nimport Ajv, { type ValidateFunction } from 'ajv';\nimport type { AgentTool, AgentToolResult } from '@earendil-works/pi-agent-core';\nimport type { TSchema } from '@sinclair/typebox';\n\nimport type { JsonSchema } from './types.js';\n\nexport const STRUCTURED_OUTPUT_TOOL_NAME = 'structured_output';\n\nexport interface StructuredOutputCapture<T = unknown> {\n  called: boolean;\n  value?: T;\n}\n\nexport interface CreateStructuredOutputToolOptions<T = unknown> {\n  schema: JsonSchema;\n  capture: StructuredOutputCapture<T>;\n  /** Override the tool name (rarely needed; default `structured_output`). */\n  name?: string;\n}\n\n// One Ajv instance per schema is fine — Ajv caches compiled validators internally.\n// We re-use a singleton to avoid the per-call construction cost.\nconst ajv = new Ajv({ allErrors: true, strict: false });\n\nexport function createStructuredOutputTool<T = unknown>(\n  options: CreateStructuredOutputToolOptions<T>,\n): AgentTool<TSchema, T> {\n  const name = options.name ?? STRUCTURED_OUTPUT_TOOL_NAME;\n  const validator: ValidateFunction = ajv.compile(options.schema);\n\n  return {\n    name,\n    label: 'Structured Output',\n    description:\n      'Return the final machine-readable result for this subagent task. ' +\n      'Call this tool exactly once when finished. Do not emit a prose final answer afterwards.',\n    parameters: options.schema as unknown as TSchema,\n    async execute(\n      _toolCallId: string,\n      params: unknown,\n    ): Promise<AgentToolResult<T>> {\n      const valid = validator(params);\n      if (!valid) {\n        const reason = ajv.errorsText(validator.errors, { separator: '; ' });\n        // Do NOT terminate on invalid input — let the model retry within the same run.\n        return {\n          content: [\n            {\n              type: 'text',\n              text: `structured_output: invalid arguments — ${reason}. Adjust and call structured_output again.`,\n            },\n          ],\n          details: params as T,\n        };\n      }\n      options.capture.called = true;\n      options.capture.value = params as T;\n      return {\n        content: [{ type: 'text', text: 'Structured output received.' }],\n        details: params as T,\n        terminate: true,\n      };\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAyBA,MAAa,8BAA8B;AAgB3C,MAAM,MAAM,IAAI,IAAI;CAAE,WAAW;CAAM,QAAQ;CAAO,CAAC;AAEvD,SAAgB,2BACd,SACuB;CACvB,MAAM,OAAO,QAAQ,QAAA;CACrB,MAAM,YAA8B,IAAI,QAAQ,QAAQ,OAAO;AAE/D,QAAO;EACL;EACA,OAAO;EACP,aACE;EAEF,YAAY,QAAQ;EACpB,MAAM,QACJ,aACA,QAC6B;AAE7B,OAAI,CADU,UAAU,OACd,CAGR,QAAO;IACL,SAAS,CACP;KACE,MAAM;KACN,MAAM,0CANG,IAAI,WAAW,UAAU,QAAQ,EAAE,WAAW,MAAM,CAMP,CAAC;KACxD,CACF;IACD,SAAS;IACV;AAEH,WAAQ,QAAQ,SAAS;AACzB,WAAQ,QAAQ,QAAQ;AACxB,UAAO;IACL,SAAS,CAAC;KAAE,MAAM;KAAQ,MAAM;KAA+B,CAAC;IAChE,SAAS;IACT,WAAW;IACZ;;EAEJ"}