@xopcai/xopc 0.0.83 → 0.0.85

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

@@ -0,0 +1,137 @@
+import { parse } from "acorn";
+//#region src/agent/workflow/parser.ts
+/**
+* Workflow script parser.
+*
+* Responsibilities:
+*   1. Parse the script with acorn (latest ECMA, top-level await + return allowed).
+*   2. Enforce determinism — reject `Date.now()`, `Math.random()`, `new Date()`,
+*      `require`, `import`, dynamic eval. This keeps future resume/replay possible
+*      and surfaces non-deterministic mistakes early.
+*   3. Require the first statement to be `export const meta = <literal>`, validate
+*      the literal shape, and strip that line from the body returned to the runtime.
+*
+* Returning a `{ meta, body }` pair means the runtime can `vm.Script(body)` without
+* any further AST work.
+*/
+const NONDETERMINISM_ERROR = "Workflow scripts must be deterministic: Date.now()/Math.random()/new Date() are unavailable. Pass timestamps via args or stamp them after the workflow returns.";
+function parseWorkflowScript(script) {
+	let ast;
+	try {
+		ast = parse(script, {
+			ecmaVersion: "latest",
+			sourceType: "module",
+			allowAwaitOutsideFunction: true,
+			allowReturnOutsideFunction: true,
+			ranges: false
+		});
+	} catch (e) {
+		const msg = e instanceof Error ? e.message : String(e);
+		throw new Error(`Workflow script parse error: ${msg}`);
+	}
+	assertDeterministicAst(ast);
+	assertNoDangerousImports(ast);
+	const first = ast.body?.[0];
+	if (first?.type !== "ExportNamedDeclaration") throw new Error("`export const meta = { name, description }` must be the first statement in the script");
+	const declaration = first.declaration;
+	if (declaration?.type !== "VariableDeclaration" || declaration.kind !== "const") throw new Error("meta export must be `export const meta = ...`");
+	if (declaration.declarations.length !== 1) throw new Error("meta export must declare only `meta`");
+	const declarator = declaration.declarations[0];
+	if (declarator.id?.type !== "Identifier" || declarator.id.name !== "meta") throw new Error("meta export must declare `meta`");
+	if (!declarator.init) throw new Error("meta must have a literal value");
+	const meta = evaluateLiteral(declarator.init, "meta");
+	validateMeta(meta);
+	return {
+		meta,
+		body: script.slice(0, first.start) + script.slice(first.end)
+	};
+}
+function assertDeterministicAst(node) {
+	if (isDateNowCall(node) || isMathRandomCall(node) || isNewDateExpression(node)) throw new Error(NONDETERMINISM_ERROR);
+	for (const child of astChildren(node)) assertDeterministicAst(child);
+}
+function assertNoDangerousImports(node) {
+	if (node.type === "ImportDeclaration" || node.type === "ImportExpression") throw new Error("Workflow scripts cannot use `import` — only the exposed globals (agent, parallel, pipeline, phase, log, args, cwd, budget) are available.");
+	if (node.type === "CallExpression") {
+		const callee = node.callee;
+		if (callee?.type === "Identifier" && (callee.name === "require" || callee.name === "eval")) throw new Error(`Workflow scripts cannot call \`${callee.name}\`.`);
+	}
+	for (const child of astChildren(node)) assertNoDangerousImports(child);
+}
+function astChildren(node) {
+	const children = [];
+	for (const value of Object.values(node)) if (Array.isArray(value)) {
+		for (const v of value) if (isAstNode(v)) children.push(v);
+	} else if (isAstNode(value)) children.push(value);
+	return children;
+}
+function isAstNode(value) {
+	return !!value && typeof value === "object" && typeof value.type === "string";
+}
+function isDateNowCall(node) {
+	return node.type === "CallExpression" && isMemberExpression(node.callee, "Date", "now");
+}
+function isMathRandomCall(node) {
+	return node.type === "CallExpression" && isMemberExpression(node.callee, "Math", "random");
+}
+function isNewDateExpression(node) {
+	return node.type === "NewExpression" && node.callee?.type === "Identifier" && node.callee.name === "Date";
+}
+function isMemberExpression(node, objectName, propertyName) {
+	if (node?.type !== "MemberExpression" || node.object?.type !== "Identifier" || node.object.name !== objectName) return false;
+	const prop = node.property;
+	if (!node.computed && prop?.type === "Identifier") return prop.name === propertyName;
+	if (prop?.type === "Literal" && typeof prop.value === "string") return prop.value === propertyName;
+	return false;
+}
+function evaluateLiteral(node, path) {
+	switch (node.type) {
+		case "ObjectExpression": {
+			const out = {};
+			for (const prop of node.properties) {
+				if (prop.type === "SpreadElement") throw new Error(`spread not allowed in ${path}`);
+				if (prop.type !== "Property") throw new Error(`only plain properties allowed in ${path}`);
+				if (prop.computed) throw new Error(`computed keys not allowed in ${path}`);
+				if (prop.kind !== "init" || prop.method) throw new Error(`methods/accessors not allowed in ${path}`);
+				const key = propertyKey(prop.key, path);
+				if (key === "__proto__" || key === "constructor" || key === "prototype") throw new Error(`reserved key name not allowed in ${path}: ${key}`);
+				out[key] = evaluateLiteral(prop.value, `${path}.${key}`);
+			}
+			return out;
+		}
+		case "ArrayExpression": return node.elements.map((element, index) => {
+			if (!element) throw new Error(`sparse arrays not allowed in ${path}`);
+			if (element.type === "SpreadElement") throw new Error(`spread not allowed in ${path}`);
+			return evaluateLiteral(element, `${path}[${index}]`);
+		});
+		case "Literal": return node.value;
+		case "TemplateLiteral":
+			if (node.expressions.length > 0) throw new Error(`template interpolation not allowed in ${path}`);
+			return node.quasis.map((quasi) => quasi.value.cooked ?? quasi.value.raw).join("");
+		case "UnaryExpression":
+			if (node.operator === "-" && node.argument?.type === "Literal" && typeof node.argument.value === "number") return -node.argument.value;
+			throw new Error(`only negative-number unary allowed in ${path}`);
+		default: throw new Error(`non-literal node type in ${path}: ${node.type}`);
+	}
+}
+function propertyKey(node, path) {
+	if (node.type === "Identifier") return node.name;
+	if (node.type === "Literal" && (typeof node.value === "string" || typeof node.value === "number")) return String(node.value);
+	throw new Error(`unsupported key type in ${path}: ${node.type}`);
+}
+function validateMeta(meta) {
+	if (!meta || typeof meta !== "object") throw new Error("meta must be an object");
+	const value = meta;
+	if (typeof value.name !== "string" || !value.name.trim()) throw new Error("meta.name must be a non-empty string");
+	if (!/^[a-z][a-z0-9_-]*$/.test(value.name)) throw new Error(`meta.name must be lowercase snake_case (got "${value.name}"). Example: "audit_repo".`);
+	if (typeof value.description !== "string" || !value.description.trim()) throw new Error("meta.description must be a non-empty string");
+	if (value.whenToUse !== void 0 && typeof value.whenToUse !== "string") throw new Error("meta.whenToUse must be a string");
+	if (value.phases !== void 0) {
+		if (!Array.isArray(value.phases)) throw new Error("meta.phases must be an array");
+		for (const phase of value.phases) if (!phase || typeof phase !== "object" || typeof phase.title !== "string") throw new Error("each meta phase must have a title string");
+	}
+}
+//#endregion
+export { parseWorkflowScript };
+
+//# sourceMappingURL=parser.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"parser.js","names":[],"sources":["../../../../src/agent/workflow/parser.ts"],"sourcesContent":["/**\n * Workflow script parser.\n *\n * Responsibilities:\n *   1. Parse the script with acorn (latest ECMA, top-level await + return allowed).\n *   2. Enforce determinism — reject `Date.now()`, `Math.random()`, `new Date()`,\n *      `require`, `import`, dynamic eval. This keeps future resume/replay possible\n *      and surfaces non-deterministic mistakes early.\n *   3. Require the first statement to be `export const meta = <literal>`, validate\n *      the literal shape, and strip that line from the body returned to the runtime.\n *\n * Returning a `{ meta, body }` pair means the runtime can `vm.Script(body)` without\n * any further AST work.\n */\n\nimport { parse } from 'acorn';\nimport type { Node } from 'acorn';\n\nimport type { WorkflowMeta, WorkflowMetaPhase } from './types.js';\n\ntype AnyNode = Node & { [key: string]: any; start: number; end: number };\n\nconst NONDETERMINISM_ERROR =\n  'Workflow scripts must be deterministic: Date.now()/Math.random()/new Date() are unavailable. ' +\n  'Pass timestamps via args or stamp them after the workflow returns.';\n\nexport interface ParsedWorkflow {\n  meta: WorkflowMeta;\n  body: string;\n}\n\nexport function parseWorkflowScript(script: string): ParsedWorkflow {\n  let ast: AnyNode;\n  try {\n    ast = parse(script, {\n      ecmaVersion: 'latest',\n      sourceType: 'module',\n      allowAwaitOutsideFunction: true,\n      allowReturnOutsideFunction: true,\n      ranges: false,\n    }) as AnyNode;\n  } catch (e) {\n    const msg = e instanceof Error ? e.message : String(e);\n    throw new Error(`Workflow script parse error: ${msg}`);\n  }\n\n  assertDeterministicAst(ast);\n  assertNoDangerousImports(ast);\n\n  const first = ast.body?.[0] as AnyNode | undefined;\n  if (first?.type !== 'ExportNamedDeclaration') {\n    throw new Error(\n      '`export const meta = { name, description }` must be the first statement in the script',\n    );\n  }\n\n  const declaration = first.declaration as AnyNode | null;\n  if (declaration?.type !== 'VariableDeclaration' || declaration.kind !== 'const') {\n    throw new Error('meta export must be `export const meta = ...`');\n  }\n  if (declaration.declarations.length !== 1) {\n    throw new Error('meta export must declare only `meta`');\n  }\n  const declarator = declaration.declarations[0] as AnyNode;\n  if (declarator.id?.type !== 'Identifier' || declarator.id.name !== 'meta') {\n    throw new Error('meta export must declare `meta`');\n  }\n  if (!declarator.init) {\n    throw new Error('meta must have a literal value');\n  }\n\n  const meta = evaluateLiteral(declarator.init, 'meta');\n  validateMeta(meta);\n\n  return {\n    meta,\n    body: script.slice(0, first.start) + script.slice(first.end),\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Determinism / safety guards\n// ---------------------------------------------------------------------------\n\nfunction assertDeterministicAst(node: AnyNode): void {\n  if (isDateNowCall(node) || isMathRandomCall(node) || isNewDateExpression(node)) {\n    throw new Error(NONDETERMINISM_ERROR);\n  }\n  for (const child of astChildren(node)) {\n    assertDeterministicAst(child);\n  }\n}\n\nfunction assertNoDangerousImports(node: AnyNode): void {\n  if (node.type === 'ImportDeclaration' || node.type === 'ImportExpression') {\n    throw new Error(\n      \"Workflow scripts cannot use `import` — only the exposed globals (agent, parallel, pipeline, phase, log, args, cwd, budget) are available.\",\n    );\n  }\n  if (node.type === 'CallExpression') {\n    const callee = node.callee as AnyNode | undefined;\n    if (callee?.type === 'Identifier' && (callee.name === 'require' || callee.name === 'eval')) {\n      throw new Error(`Workflow scripts cannot call \\`${callee.name}\\`.`);\n    }\n  }\n  for (const child of astChildren(node)) {\n    assertNoDangerousImports(child);\n  }\n}\n\nfunction astChildren(node: AnyNode): AnyNode[] {\n  const children: AnyNode[] = [];\n  for (const value of Object.values(node)) {\n    if (Array.isArray(value)) {\n      for (const v of value) {\n        if (isAstNode(v)) children.push(v);\n      }\n    } else if (isAstNode(value)) {\n      children.push(value);\n    }\n  }\n  return children;\n}\n\nfunction isAstNode(value: unknown): value is AnyNode {\n  return !!value && typeof value === 'object' && typeof (value as AnyNode).type === 'string';\n}\n\nfunction isDateNowCall(node: AnyNode): boolean {\n  return node.type === 'CallExpression' && isMemberExpression(node.callee, 'Date', 'now');\n}\n\nfunction isMathRandomCall(node: AnyNode): boolean {\n  return node.type === 'CallExpression' && isMemberExpression(node.callee, 'Math', 'random');\n}\n\nfunction isNewDateExpression(node: AnyNode): boolean {\n  return (\n    node.type === 'NewExpression' &&\n    (node.callee as AnyNode | undefined)?.type === 'Identifier' &&\n    (node.callee as AnyNode).name === 'Date'\n  );\n}\n\nfunction isMemberExpression(\n  node: AnyNode | undefined,\n  objectName: string,\n  propertyName: string,\n): boolean {\n  if (\n    node?.type !== 'MemberExpression' ||\n    (node.object as AnyNode | undefined)?.type !== 'Identifier' ||\n    (node.object as AnyNode).name !== objectName\n  ) {\n    return false;\n  }\n  const prop = node.property as AnyNode | undefined;\n  if (!node.computed && prop?.type === 'Identifier') return prop.name === propertyName;\n  if (prop?.type === 'Literal' && typeof prop.value === 'string') return prop.value === propertyName;\n  return false;\n}\n\n// ---------------------------------------------------------------------------\n// Literal evaluator (meta must be a pure literal)\n// ---------------------------------------------------------------------------\n\nfunction evaluateLiteral(node: AnyNode, path: string): any {\n  switch (node.type) {\n    case 'ObjectExpression': {\n      const out: Record<string, unknown> = {};\n      for (const prop of node.properties as AnyNode[]) {\n        if (prop.type === 'SpreadElement') {\n          throw new Error(`spread not allowed in ${path}`);\n        }\n        if (prop.type !== 'Property') {\n          throw new Error(`only plain properties allowed in ${path}`);\n        }\n        if (prop.computed) {\n          throw new Error(`computed keys not allowed in ${path}`);\n        }\n        if (prop.kind !== 'init' || prop.method) {\n          throw new Error(`methods/accessors not allowed in ${path}`);\n        }\n        const key = propertyKey(prop.key as AnyNode, path);\n        if (key === '__proto__' || key === 'constructor' || key === 'prototype') {\n          throw new Error(`reserved key name not allowed in ${path}: ${key}`);\n        }\n        out[key] = evaluateLiteral(prop.value as AnyNode, `${path}.${key}`);\n      }\n      return out;\n    }\n    case 'ArrayExpression':\n      return (node.elements as Array<AnyNode | null>).map((element, index) => {\n        if (!element) throw new Error(`sparse arrays not allowed in ${path}`);\n        if (element.type === 'SpreadElement') {\n          throw new Error(`spread not allowed in ${path}`);\n        }\n        return evaluateLiteral(element, `${path}[${index}]`);\n      });\n    case 'Literal':\n      return node.value;\n    case 'TemplateLiteral':\n      if (node.expressions.length > 0) {\n        throw new Error(`template interpolation not allowed in ${path}`);\n      }\n      return node.quasis\n        .map((quasi: AnyNode) => quasi.value.cooked ?? quasi.value.raw)\n        .join('');\n    case 'UnaryExpression':\n      if (\n        node.operator === '-' &&\n        node.argument?.type === 'Literal' &&\n        typeof node.argument.value === 'number'\n      ) {\n        return -node.argument.value;\n      }\n      throw new Error(`only negative-number unary allowed in ${path}`);\n    default:\n      throw new Error(`non-literal node type in ${path}: ${node.type}`);\n  }\n}\n\nfunction propertyKey(node: AnyNode, path: string): string {\n  if (node.type === 'Identifier') return node.name;\n  if (node.type === 'Literal' && (typeof node.value === 'string' || typeof node.value === 'number')) {\n    return String(node.value);\n  }\n  throw new Error(`unsupported key type in ${path}: ${node.type}`);\n}\n\nfunction validateMeta(meta: unknown): asserts meta is WorkflowMeta {\n  if (!meta || typeof meta !== 'object') {\n    throw new Error('meta must be an object');\n  }\n  const value = meta as WorkflowMeta;\n  if (typeof value.name !== 'string' || !value.name.trim()) {\n    throw new Error('meta.name must be a non-empty string');\n  }\n  if (!/^[a-z][a-z0-9_-]*$/.test(value.name)) {\n    throw new Error(\n      `meta.name must be lowercase snake_case (got \"${value.name}\"). Example: \"audit_repo\".`,\n    );\n  }\n  if (typeof value.description !== 'string' || !value.description.trim()) {\n    throw new Error('meta.description must be a non-empty string');\n  }\n  if (value.whenToUse !== undefined && typeof value.whenToUse !== 'string') {\n    throw new Error('meta.whenToUse must be a string');\n  }\n  if (value.phases !== undefined) {\n    if (!Array.isArray(value.phases)) {\n      throw new Error('meta.phases must be an array');\n    }\n    for (const phase of value.phases) {\n      if (!phase || typeof phase !== 'object' || typeof (phase as WorkflowMetaPhase).title !== 'string') {\n        throw new Error('each meta phase must have a title string');\n      }\n    }\n  }\n}\n"],"mappings":"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"}

package/dist/src/agent/workflow/progress-broker.d.ts

@@ -0,0 +1,80 @@
+/**
+ * WorkflowProgressBroker — the single seam that turns mid-run `workflow`
+ * snapshots into IM messages (Telegram today, more channels later).
+ *
+ * Architecture:
+ *
+ *    pi-agent  ──tool_execution_update──▶  AgentEventHandler / SessionEventBus
+ *                                                       │
+ *                          attachTo(handler)            │
+ *                                                       ▼
+ *                                          WorkflowProgressBroker
+ *                                                       │
+ *                                  per-(sessionKey, toolCallId) state
+ *                                                       │
+ *                                   ┌───────────────────┼───────────────────┐
+ *                                   ▼                   ▼                   ▼
+ *                              Telegram cap         Feishu cap          WeChat cap
+ *
+ * Why broker + capability instead of "each channel subscribes the bus"?
+ *   - DRY snapshot aggregation and key-event detection.
+ *   - Per-channel throttling is enforced by the broker, so a slow / rate-limited
+ *     channel can't block a fast one.
+ *   - Adding a new channel = one capability + one register call. Broker code
+ *     never grows.
+ */
+import type { AgentEvent } from '@earendil-works/pi-agent-core';
+import type { Config } from '../../config/schema.js';
+import type { ChannelProgressCapability } from './channel-capability.js';
+import type { WorkflowSnapshot } from './types.js';
+export interface BrokerListenerHandle {
+    /** Detach broker from the session bus and clear all in-flight state. */
+    dispose(): void;
+}
+/**
+ * Tiny façade onto the AgentEventHandler. We don't import the concrete class to
+ * keep this module test-friendly — a stub listener pump is fine for unit tests.
+ */
+export interface SessionBusLike {
+    registerListener(type: AgentEvent['type'] | 'all', listener: (event: AgentEvent, context: {
+        sessionKey: string;
+    }) => void): () => void;
+}
+export declare class WorkflowProgressBroker {
+    private readonly opts;
+    private subscribers;
+    private states;
+    /** Now() factory — overridable in tests for deterministic time. */
+    private readonly now;
+    /** Cached resolved settings per (channelId), invalidated on registration. */
+    private resolved;
+    constructor(opts?: {
+        getConfig?: () => Config | undefined;
+        now?: () => number;
+    });
+    registerChannel(cap: ChannelProgressCapability): () => void;
+    attachTo(bus: SessionBusLike): BrokerListenerHandle;
+    /** Visible for tests — direct entry path bypassing the SessionBus glue. */
+    onUpdate(sessionKey: string, toolCallId: string, snapshot: WorkflowSnapshot): void;
+    /** Visible for tests — direct entry path bypassing the SessionBus glue. */
+    onEnd(sessionKey: string, toolCallId: string, snapshot: WorkflowSnapshot | null): void;
+    private dispatchToChannel;
+    private sendNow;
+    private cancelPending;
+    private disposeAllPending;
+    private getOrCreateState;
+    private getOrCreateChannelState;
+    /** Resolved (enabled / throttleMs / mode) for a channel, with config overrides. */
+    private resolveChannelSettings;
+    /** Drop any cached config so the next dispatch re-reads. Call after config reload. */
+    invalidateConfigCache(): void;
+    /** @internal — for tests only. */
+    _stateCount(): number;
+}
+/**
+ * Process-wide broker singleton. Channels register against this one; the
+ * service wires it to the session bus during startup.
+ */
+export declare function getWorkflowProgressBroker(): WorkflowProgressBroker;
+/** Test-only — reset the singleton between cases. */
+export declare function _resetWorkflowProgressBrokerForTests(): void;

package/dist/src/agent/workflow/progress-broker.js

@@ -0,0 +1,263 @@
+import { createLogger } from "../../utils/logger/index.js";
+import { init_logger } from "../../utils/logger.js";
+import { renderWorkflowText } from "./snapshot.js";
+//#region src/agent/workflow/progress-broker.ts
+init_logger();
+const log = createLogger("workflow-progress-broker");
+const WORKFLOW_TOOL_NAME = "workflow";
+const RENDER_MAX_AGENTS_PER_PHASE = 4;
+const RENDER_MAX_LOGS = 2;
+var WorkflowProgressBroker = class {
+	subscribers = [];
+	states = /* @__PURE__ */ new Map();
+	/** Now() factory — overridable in tests for deterministic time. */
+	now;
+	/** Cached resolved settings per (channelId), invalidated on registration. */
+	resolved = /* @__PURE__ */ new Map();
+	constructor(opts = {}) {
+		this.opts = opts;
+		this.now = opts.now ?? (() => Date.now());
+	}
+	registerChannel(cap) {
+		if (this.subscribers.some((s) => s.channelId === cap.channelId)) {
+			log.warn({ channelId: cap.channelId }, "channel capability already registered; replacing");
+			this.subscribers = this.subscribers.filter((s) => s.channelId !== cap.channelId);
+		}
+		this.subscribers.push(cap);
+		this.resolved.delete(cap.channelId);
+		return () => {
+			this.subscribers = this.subscribers.filter((s) => s !== cap);
+			this.resolved.delete(cap.channelId);
+		};
+	}
+	attachTo(bus) {
+		const offUpdate = bus.registerListener("tool_execution_update", (event, ctx) => {
+			const e = event;
+			if (e.toolName !== WORKFLOW_TOOL_NAME) return;
+			const snap = extractWorkflowSnapshot(e.partialResult);
+			if (!snap) return;
+			this.onUpdate(ctx.sessionKey, e.toolCallId, snap);
+		});
+		const offEnd = bus.registerListener("tool_execution_end", (event, ctx) => {
+			const e = event;
+			if (e.toolName !== WORKFLOW_TOOL_NAME) return;
+			const snap = extractWorkflowSnapshot(e.result, { fromResultEnvelope: true });
+			this.onEnd(ctx.sessionKey, e.toolCallId, snap);
+		});
+		return { dispose: () => {
+			offUpdate();
+			offEnd();
+			this.disposeAllPending();
+		} };
+	}
+	/** Visible for tests — direct entry path bypassing the SessionBus glue. */
+	onUpdate(sessionKey, toolCallId, snapshot) {
+		const key = stateKey(sessionKey, toolCallId);
+		const state = this.getOrCreateState(key, snapshot);
+		state.prevSnapshot = state.snapshot;
+		state.snapshot = snapshot;
+		const isKey = isKeyEvent(state.prevSnapshot, snapshot);
+		for (const cap of this.subscribers) this.dispatchToChannel(state, sessionKey, cap, {
+			isFinal: false,
+			isKey
+		});
+	}
+	/** Visible for tests — direct entry path bypassing the SessionBus glue. */
+	onEnd(sessionKey, toolCallId, snapshot) {
+		const key = stateKey(sessionKey, toolCallId);
+		const state = this.states.get(key);
+		if (!state) return;
+		if (snapshot) state.snapshot = snapshot;
+		for (const cap of this.subscribers) {
+			this.cancelPending(state, cap.channelId);
+			this.dispatchToChannel(state, sessionKey, cap, {
+				isFinal: true,
+				isKey: true
+			});
+		}
+		setTimeout(() => this.states.delete(key), 2e3);
+	}
+	dispatchToChannel(state, sessionKey, cap, flags) {
+		const cfg = this.resolveChannelSettings(cap);
+		if (!cfg.enabled) return;
+		if (cfg.mode === "final-only" && !flags.isFinal) return;
+		const chState = this.getOrCreateChannelState(state, cap.channelId);
+		if (flags.isFinal || flags.isKey) {
+			this.cancelPending(state, cap.channelId);
+			this.sendNow(state, sessionKey, cap, cfg, flags.isFinal);
+			return;
+		}
+		const elapsed = this.now() - chState.lastSentAt;
+		const wait = Math.max(0, cfg.throttleMs - elapsed);
+		if (wait === 0) {
+			this.sendNow(state, sessionKey, cap, cfg, false);
+			return;
+		}
+		if (chState.pendingTimer) return;
+		chState.pendingTimer = setTimeout(() => {
+			chState.pendingTimer = void 0;
+			this.sendNow(state, sessionKey, cap, cfg, false);
+		}, wait);
+	}
+	async sendNow(state, sessionKey, cap, cfg, isFinal) {
+		const chState = this.getOrCreateChannelState(state, cap.channelId);
+		if (chState.inflight) await chState.inflight.catch(() => void 0);
+		const text = renderWorkflowText(state.snapshot, isFinal, {
+			maxAgentsPerPhase: RENDER_MAX_AGENTS_PER_PHASE,
+			maxLogs: RENDER_MAX_LOGS,
+			showResultPreviews: isFinal
+		});
+		const previousMessageId = cfg.mode === "edit" ? chState.lastMessageId : void 0;
+		const task = cap.postProgress({
+			sessionKey,
+			text,
+			previousMessageId,
+			isFinal,
+			mode: cfg.mode
+		}).then((r) => {
+			chState.lastMessageId = r.messageId;
+			chState.lastSentAt = this.now();
+		}).catch((err) => {
+			const msg = err instanceof Error ? err.message : String(err);
+			log.warn({
+				err,
+				errorMessage: msg,
+				channelId: cap.channelId,
+				sessionKey
+			}, `workflow progress postProgress failed: ${msg}`);
+		}).finally(() => {
+			chState.inflight = void 0;
+		});
+		chState.inflight = task;
+		await task;
+	}
+	cancelPending(state, channelId) {
+		const chState = state.perChannel.get(channelId);
+		if (chState?.pendingTimer) {
+			clearTimeout(chState.pendingTimer);
+			chState.pendingTimer = void 0;
+		}
+	}
+	disposeAllPending() {
+		for (const state of this.states.values()) for (const ch of state.perChannel.values()) if (ch.pendingTimer) clearTimeout(ch.pendingTimer);
+		this.states.clear();
+	}
+	getOrCreateState(key, snapshot) {
+		let state = this.states.get(key);
+		if (!state) {
+			state = {
+				snapshot,
+				perChannel: /* @__PURE__ */ new Map()
+			};
+			this.states.set(key, state);
+		}
+		return state;
+	}
+	getOrCreateChannelState(state, channelId) {
+		let ch = state.perChannel.get(channelId);
+		if (!ch) {
+			ch = { lastSentAt: 0 };
+			state.perChannel.set(channelId, ch);
+		}
+		return ch;
+	}
+	/** Resolved (enabled / throttleMs / mode) for a channel, with config overrides. */
+	resolveChannelSettings(cap) {
+		const cached = this.resolved.get(cap.channelId);
+		if (cached) return cached;
+		const override = readChannelConfig(this.opts.getConfig?.(), cap.channelId);
+		const resolved = {
+			enabled: override?.enabled ?? true,
+			throttleMs: override?.throttleMs ?? cap.defaultThrottleMs,
+			mode: override?.mode ?? cap.defaultMode
+		};
+		this.resolved.set(cap.channelId, resolved);
+		return resolved;
+	}
+	/** Drop any cached config so the next dispatch re-reads. Call after config reload. */
+	invalidateConfigCache() {
+		this.resolved.clear();
+	}
+	/** @internal — for tests only. */
+	_stateCount() {
+		return this.states.size;
+	}
+};
+let singleton = null;
+/**
+* Process-wide broker singleton. Channels register against this one; the
+* service wires it to the session bus during startup.
+*/
+function getWorkflowProgressBroker() {
+	if (!singleton) singleton = new WorkflowProgressBroker();
+	return singleton;
+}
+/** Test-only — reset the singleton between cases. */
+function _resetWorkflowProgressBrokerForTests() {
+	singleton = null;
+}
+function stateKey(sessionKey, toolCallId) {
+	return `${sessionKey}
${toolCallId ?? ""}`;
+}
+/**
+* Compare two snapshots and decide whether the new one is "key" — i.e. worth
+* bypassing the per-channel throttle. Anything visible to the user as a
+* progress milestone qualifies; counts ticking by alone do not.
+*/
+function isKeyEvent(prev, next) {
+	if (!prev) return true;
+	if (prev.currentPhase !== next.currentPhase) return true;
+	if (next.errorCount > prev.errorCount) return true;
+	if (next.skippedCount > prev.skippedCount) return true;
+	if (prev.phases.length !== next.phases.length) return true;
+	if (hasNewFailedAgent(prev.agents, next.agents)) return true;
+	return false;
+}
+function hasNewFailedAgent(prev, next) {
+	const prevBad = new Set(prev.filter((a) => a.status === "error" || a.status === "skipped").map((a) => a.id));
+	for (const a of next) if ((a.status === "error" || a.status === "skipped") && !prevBad.has(a.id)) return true;
+	return false;
+}
+/**
+* Pull a {@link WorkflowSnapshot} out of an AgentToolResult-shaped value.
+* Returns null when the payload is not snapshot-shaped (text-only updates,
+* non-workflow tools, etc.).
+*
+* `fromResultEnvelope = true` (used for `tool_end.result`) tolerates the
+* `{ content, details }` wrapper.
+*/
+function extractWorkflowSnapshot(payload, opts = {}) {
+	if (!payload || typeof payload !== "object") return null;
+	const rec = payload;
+	if (opts.fromResultEnvelope) {
+		const details = rec.details;
+		if (details && typeof details === "object") return coerce(details);
+		return null;
+	}
+	if ("details" in rec) {
+		const details = rec.details;
+		if (details && typeof details === "object") return coerce(details);
+		return null;
+	}
+	return coerce(rec);
+}
+function coerce(value) {
+	if (!value || typeof value !== "object") return null;
+	const rec = value;
+	if (typeof rec.name !== "string") return null;
+	if (!Array.isArray(rec.agents)) return null;
+	return value;
+}
+function readChannelConfig(config, channelId) {
+	const channels = config?.channels;
+	if (!channels) return void 0;
+	const cfg = channels[channelId];
+	if (!cfg || typeof cfg !== "object") return void 0;
+	const wf = cfg.workflowProgress;
+	if (!wf || typeof wf !== "object") return void 0;
+	return wf;
+}
+//#endregion
+export { WorkflowProgressBroker, _resetWorkflowProgressBrokerForTests, getWorkflowProgressBroker };
+
+//# sourceMappingURL=progress-broker.js.map

package/dist/src/agent/workflow/progress-broker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress-broker.js","names":[],"sources":["../../../../src/agent/workflow/progress-broker.ts"],"sourcesContent":["/**\n * WorkflowProgressBroker — the single seam that turns mid-run `workflow`\n * snapshots into IM messages (Telegram today, more channels later).\n *\n * Architecture:\n *\n *    pi-agent  ──tool_execution_update──▶  AgentEventHandler / SessionEventBus\n *                                                       │\n *                          attachTo(handler)            │\n *                                                       ▼\n *                                          WorkflowProgressBroker\n *                                                       │\n *                                  per-(sessionKey, toolCallId) state\n *                                                       │\n *                                   ┌───────────────────┼───────────────────┐\n *                                   ▼                   ▼                   ▼\n *                              Telegram cap         Feishu cap          WeChat cap\n *\n * Why broker + capability instead of \"each channel subscribes the bus\"?\n *   - DRY snapshot aggregation and key-event detection.\n *   - Per-channel throttling is enforced by the broker, so a slow / rate-limited\n *     channel can't block a fast one.\n *   - Adding a new channel = one capability + one register call. Broker code\n *     never grows.\n */\n\nimport type { AgentEvent } from '@earendil-works/pi-agent-core';\n\nimport { createLogger } from '../../utils/logger.js';\nimport type { Config } from '../../config/schema.js';\n\nimport type {\n  ChannelProgressCapability,\n  WorkflowProgressMode,\n} from './channel-capability.js';\nimport { renderWorkflowText } from './snapshot.js';\nimport type { WorkflowAgentSnapshot, WorkflowSnapshot } from './types.js';\n\nconst log = createLogger('workflow-progress-broker');\n\nconst WORKFLOW_TOOL_NAME = 'workflow';\nconst RENDER_MAX_AGENTS_PER_PHASE = 4;\nconst RENDER_MAX_LOGS = 2;\n\n/** Per-channel resolved settings after applying config overrides on capability defaults. */\ninterface ChannelResolvedSettings {\n  enabled: boolean;\n  throttleMs: number;\n  mode: WorkflowProgressMode;\n}\n\n/** Per-(sessionKey, toolCallId) progress state. */\ninterface RunState {\n  /** Latest snapshot seen for this run. Always overwritten on update. */\n  snapshot: WorkflowSnapshot;\n  /** Previous snapshot used to detect \"key events\" (phase change, new errors). */\n  prevSnapshot?: WorkflowSnapshot;\n  /** Per-channel last-send bookkeeping. */\n  perChannel: Map<string, ChannelRunState>;\n}\n\ninterface ChannelRunState {\n  /** Server timestamp of the last successful postProgress. */\n  lastSentAt: number;\n  /** Returned messageId of the last successful postProgress — drives edit mode. */\n  lastMessageId?: string;\n  /** Pending timer id (Node `setTimeout`) when a throttled flush is scheduled. */\n  pendingTimer?: ReturnType<typeof setTimeout>;\n  /** Inflight `postProgress` promise; we serialise per-(state, channel) to avoid race. */\n  inflight?: Promise<void>;\n}\n\nexport interface BrokerListenerHandle {\n  /** Detach broker from the session bus and clear all in-flight state. */\n  dispose(): void;\n}\n\n/**\n * Tiny façade onto the AgentEventHandler. We don't import the concrete class to\n * keep this module test-friendly — a stub listener pump is fine for unit tests.\n */\nexport interface SessionBusLike {\n  registerListener(\n    type: AgentEvent['type'] | 'all',\n    listener: (event: AgentEvent, context: { sessionKey: string }) => void,\n  ): () => void;\n}\n\nexport class WorkflowProgressBroker {\n  private subscribers: ChannelProgressCapability[] = [];\n  private states = new Map<string, RunState>();\n  /** Now() factory — overridable in tests for deterministic time. */\n  private readonly now: () => number;\n  /** Cached resolved settings per (channelId), invalidated on registration. */\n  private resolved = new Map<string, ChannelResolvedSettings>();\n\n  constructor(\n    private readonly opts: {\n      getConfig?: () => Config | undefined;\n      now?: () => number;\n    } = {},\n  ) {\n    this.now = opts.now ?? (() => Date.now());\n  }\n\n  // ── Registration ────────────────────────────────────────────────────────────\n\n  registerChannel(cap: ChannelProgressCapability): () => void {\n    if (this.subscribers.some((s) => s.channelId === cap.channelId)) {\n      log.warn({ channelId: cap.channelId }, 'channel capability already registered; replacing');\n      this.subscribers = this.subscribers.filter((s) => s.channelId !== cap.channelId);\n    }\n    this.subscribers.push(cap);\n    this.resolved.delete(cap.channelId);\n    return () => {\n      this.subscribers = this.subscribers.filter((s) => s !== cap);\n      this.resolved.delete(cap.channelId);\n    };\n  }\n\n  attachTo(bus: SessionBusLike): BrokerListenerHandle {\n    const offUpdate = bus.registerListener('tool_execution_update', (event, ctx) => {\n      const e = event as Extract<AgentEvent, { type: 'tool_execution_update' }>;\n      if (e.toolName !== WORKFLOW_TOOL_NAME) return;\n      const snap = extractWorkflowSnapshot(e.partialResult);\n      if (!snap) return;\n      this.onUpdate(ctx.sessionKey, e.toolCallId, snap);\n    });\n\n    const offEnd = bus.registerListener('tool_execution_end', (event, ctx) => {\n      const e = event as Extract<AgentEvent, { type: 'tool_execution_end' }>;\n      if (e.toolName !== WORKFLOW_TOOL_NAME) return;\n      // tool_end ships the final envelope in `result`; reach in for the\n      // authoritative snapshot (durationMs / result / final counts).\n      const snap = extractWorkflowSnapshot(e.result, { fromResultEnvelope: true });\n      this.onEnd(ctx.sessionKey, e.toolCallId, snap);\n    });\n\n    return {\n      dispose: () => {\n        offUpdate();\n        offEnd();\n        this.disposeAllPending();\n      },\n    };\n  }\n\n  // ── Core state machine ──────────────────────────────────────────────────────\n\n  /** Visible for tests — direct entry path bypassing the SessionBus glue. */\n  onUpdate(sessionKey: string, toolCallId: string, snapshot: WorkflowSnapshot): void {\n    const key = stateKey(sessionKey, toolCallId);\n    const state = this.getOrCreateState(key, snapshot);\n    state.prevSnapshot = state.snapshot;\n    state.snapshot = snapshot;\n\n    const isKey = isKeyEvent(state.prevSnapshot, snapshot);\n    for (const cap of this.subscribers) {\n      this.dispatchToChannel(state, sessionKey, cap, { isFinal: false, isKey });\n    }\n  }\n\n  /** Visible for tests — direct entry path bypassing the SessionBus glue. */\n  onEnd(sessionKey: string, toolCallId: string, snapshot: WorkflowSnapshot | null): void {\n    const key = stateKey(sessionKey, toolCallId);\n    const state = this.states.get(key);\n    if (!state) return;\n    if (snapshot) state.snapshot = snapshot;\n\n    for (const cap of this.subscribers) {\n      // Always flush the final message — bypass throttle and any pending timer.\n      this.cancelPending(state, cap.channelId);\n      this.dispatchToChannel(state, sessionKey, cap, { isFinal: true, isKey: true });\n    }\n    // State is GC'd lazily after a small grace period so any straggler\n    // `update` event arriving after `end` is silently dropped (instead of\n    // resurrecting the run).\n    setTimeout(() => this.states.delete(key), 2_000);\n  }\n\n  // ── Dispatch + throttle ─────────────────────────────────────────────────────\n\n  private dispatchToChannel(\n    state: RunState,\n    sessionKey: string,\n    cap: ChannelProgressCapability,\n    flags: { isFinal: boolean; isKey: boolean },\n  ): void {\n    const cfg = this.resolveChannelSettings(cap);\n    if (!cfg.enabled) return;\n    if (cfg.mode === 'final-only' && !flags.isFinal) return;\n\n    const chState = this.getOrCreateChannelState(state, cap.channelId);\n\n    // Key events and the final message bypass throttle.\n    if (flags.isFinal || flags.isKey) {\n      this.cancelPending(state, cap.channelId);\n      void this.sendNow(state, sessionKey, cap, cfg, flags.isFinal);\n      return;\n    }\n\n    const elapsed = this.now() - chState.lastSentAt;\n    const wait = Math.max(0, cfg.throttleMs - elapsed);\n    if (wait === 0) {\n      void this.sendNow(state, sessionKey, cap, cfg, false);\n      return;\n    }\n    if (chState.pendingTimer) return; // already scheduled; latest snapshot will be picked up\n    chState.pendingTimer = setTimeout(() => {\n      chState.pendingTimer = undefined;\n      void this.sendNow(state, sessionKey, cap, cfg, false);\n    }, wait);\n  }\n\n  private async sendNow(\n    state: RunState,\n    sessionKey: string,\n    cap: ChannelProgressCapability,\n    cfg: ChannelResolvedSettings,\n    isFinal: boolean,\n  ): Promise<void> {\n    const chState = this.getOrCreateChannelState(state, cap.channelId);\n    // Serialise per-channel sends so a slow editMessage call doesn't get\n    // overtaken by a faster one and leave the bubble out of order.\n    if (chState.inflight) await chState.inflight.catch(() => undefined);\n\n    const text = renderWorkflowText(state.snapshot, isFinal, {\n      maxAgentsPerPhase: RENDER_MAX_AGENTS_PER_PHASE,\n      maxLogs: RENDER_MAX_LOGS,\n      showResultPreviews: isFinal,\n    });\n\n    const previousMessageId = cfg.mode === 'edit' ? chState.lastMessageId : undefined;\n    const task = cap\n      .postProgress({ sessionKey, text, previousMessageId, isFinal, mode: cfg.mode })\n      .then((r) => {\n        chState.lastMessageId = r.messageId;\n        chState.lastSentAt = this.now();\n      })\n      .catch((err) => {\n        const msg = err instanceof Error ? err.message : String(err);\n        log.warn(\n          { err, errorMessage: msg, channelId: cap.channelId, sessionKey },\n          `workflow progress postProgress failed: ${msg}`,\n        );\n      })\n      .finally(() => {\n        chState.inflight = undefined;\n      });\n\n    chState.inflight = task;\n    await task;\n  }\n\n  private cancelPending(state: RunState, channelId: string): void {\n    const chState = state.perChannel.get(channelId);\n    if (chState?.pendingTimer) {\n      clearTimeout(chState.pendingTimer);\n      chState.pendingTimer = undefined;\n    }\n  }\n\n  private disposeAllPending(): void {\n    for (const state of this.states.values()) {\n      for (const ch of state.perChannel.values()) {\n        if (ch.pendingTimer) clearTimeout(ch.pendingTimer);\n      }\n    }\n    this.states.clear();\n  }\n\n  // ── State helpers ───────────────────────────────────────────────────────────\n\n  private getOrCreateState(key: string, snapshot: WorkflowSnapshot): RunState {\n    let state = this.states.get(key);\n    if (!state) {\n      state = { snapshot, perChannel: new Map() };\n      this.states.set(key, state);\n    }\n    return state;\n  }\n\n  private getOrCreateChannelState(state: RunState, channelId: string): ChannelRunState {\n    let ch = state.perChannel.get(channelId);\n    if (!ch) {\n      ch = { lastSentAt: 0 };\n      state.perChannel.set(channelId, ch);\n    }\n    return ch;\n  }\n\n  /** Resolved (enabled / throttleMs / mode) for a channel, with config overrides. */\n  private resolveChannelSettings(cap: ChannelProgressCapability): ChannelResolvedSettings {\n    const cached = this.resolved.get(cap.channelId);\n    if (cached) return cached;\n    const override = readChannelConfig(this.opts.getConfig?.(), cap.channelId);\n    const resolved: ChannelResolvedSettings = {\n      enabled: override?.enabled ?? true,\n      throttleMs: override?.throttleMs ?? cap.defaultThrottleMs,\n      mode: override?.mode ?? cap.defaultMode,\n    };\n    this.resolved.set(cap.channelId, resolved);\n    return resolved;\n  }\n\n  /** Drop any cached config so the next dispatch re-reads. Call after config reload. */\n  invalidateConfigCache(): void {\n    this.resolved.clear();\n  }\n\n  // ── Test introspection ──────────────────────────────────────────────────────\n\n  /** @internal — for tests only. */\n  _stateCount(): number {\n    return this.states.size;\n  }\n}\n\n// ── Singleton ───────────────────────────────────────────────────────────────\n\nlet singleton: WorkflowProgressBroker | null = null;\n\n/**\n * Process-wide broker singleton. Channels register against this one; the\n * service wires it to the session bus during startup.\n */\nexport function getWorkflowProgressBroker(): WorkflowProgressBroker {\n  if (!singleton) singleton = new WorkflowProgressBroker();\n  return singleton;\n}\n\n/** Test-only — reset the singleton between cases. */\nexport function _resetWorkflowProgressBrokerForTests(): void {\n  singleton = null;\n}\n\n// ── Pure helpers ────────────────────────────────────────────────────────────\n\nfunction stateKey(sessionKey: string, toolCallId: string | undefined): string {\n  return `${sessionKey}\u0001${toolCallId ?? ''}`;\n}\n\n/**\n * Compare two snapshots and decide whether the new one is \"key\" — i.e. worth\n * bypassing the per-channel throttle. Anything visible to the user as a\n * progress milestone qualifies; counts ticking by alone do not.\n */\nfunction isKeyEvent(prev: WorkflowSnapshot | undefined, next: WorkflowSnapshot): boolean {\n  if (!prev) return true; // first update of the run\n  if (prev.currentPhase !== next.currentPhase) return true;\n  if (next.errorCount > prev.errorCount) return true;\n  if (next.skippedCount > prev.skippedCount) return true;\n  // New phase row in the rollup (declared via `phase(...)` mid-run)\n  if (prev.phases.length !== next.phases.length) return true;\n  if (hasNewFailedAgent(prev.agents, next.agents)) return true;\n  return false;\n}\n\nfunction hasNewFailedAgent(\n  prev: WorkflowAgentSnapshot[],\n  next: WorkflowAgentSnapshot[],\n): boolean {\n  const prevBad = new Set(\n    prev.filter((a) => a.status === 'error' || a.status === 'skipped').map((a) => a.id),\n  );\n  for (const a of next) {\n    if ((a.status === 'error' || a.status === 'skipped') && !prevBad.has(a.id)) return true;\n  }\n  return false;\n}\n\n/**\n * Pull a {@link WorkflowSnapshot} out of an AgentToolResult-shaped value.\n * Returns null when the payload is not snapshot-shaped (text-only updates,\n * non-workflow tools, etc.).\n *\n * `fromResultEnvelope = true` (used for `tool_end.result`) tolerates the\n * `{ content, details }` wrapper.\n */\nfunction extractWorkflowSnapshot(\n  payload: unknown,\n  opts: { fromResultEnvelope?: boolean } = {},\n): WorkflowSnapshot | null {\n  if (!payload || typeof payload !== 'object') return null;\n  const rec = payload as Record<string, unknown>;\n  if (opts.fromResultEnvelope) {\n    const details = rec.details;\n    if (details && typeof details === 'object') return coerce(details);\n    return null;\n  }\n  if ('details' in rec) {\n    const details = rec.details;\n    if (details && typeof details === 'object') return coerce(details);\n    return null;\n  }\n  return coerce(rec);\n}\n\nfunction coerce(value: unknown): WorkflowSnapshot | null {\n  if (!value || typeof value !== 'object') return null;\n  const rec = value as Record<string, unknown>;\n  if (typeof rec.name !== 'string') return null;\n  if (!Array.isArray(rec.agents)) return null;\n  return value as WorkflowSnapshot;\n}\n\nfunction readChannelConfig(\n  config: Config | undefined,\n  channelId: string,\n): { enabled?: boolean; throttleMs?: number; mode?: WorkflowProgressMode } | undefined {\n  const channels = config?.channels as Record<string, unknown> | undefined;\n  if (!channels) return undefined;\n  const cfg = channels[channelId];\n  if (!cfg || typeof cfg !== 'object') return undefined;\n  const wf = (cfg as { workflowProgress?: unknown }).workflowProgress;\n  if (!wf || typeof wf !== 'object') return undefined;\n  return wf as { enabled?: boolean; throttleMs?: number; mode?: WorkflowProgressMode };\n}\n"],"mappings":";;;;aA4BqD;AAUrD,MAAM,MAAM,aAAa,2BAA2B;AAEpD,MAAM,qBAAqB;AAC3B,MAAM,8BAA8B;AACpC,MAAM,kBAAkB;AA8CxB,IAAa,yBAAb,MAAoC;CAClC,cAAmD,EAAE;CACrD,yBAAiB,IAAI,KAAuB;;CAE5C;;CAEA,2BAAmB,IAAI,KAAsC;CAE7D,YACE,OAGI,EAAE,EACN;AAJiB,OAAA,OAAA;AAKjB,OAAK,MAAM,KAAK,cAAc,KAAK,KAAK;;CAK1C,gBAAgB,KAA4C;AAC1D,MAAI,KAAK,YAAY,MAAM,MAAM,EAAE,cAAc,IAAI,UAAU,EAAE;AAC/D,OAAI,KAAK,EAAE,WAAW,IAAI,WAAW,EAAE,mDAAmD;AAC1F,QAAK,cAAc,KAAK,YAAY,QAAQ,MAAM,EAAE,cAAc,IAAI,UAAU;;AAElF,OAAK,YAAY,KAAK,IAAI;AAC1B,OAAK,SAAS,OAAO,IAAI,UAAU;AACnC,eAAa;AACX,QAAK,cAAc,KAAK,YAAY,QAAQ,MAAM,MAAM,IAAI;AAC5D,QAAK,SAAS,OAAO,IAAI,UAAU;;;CAIvC,SAAS,KAA2C;EAClD,MAAM,YAAY,IAAI,iBAAiB,0BAA0B,OAAO,QAAQ;GAC9E,MAAM,IAAI;AACV,OAAI,EAAE,aAAa,mBAAoB;GACvC,MAAM,OAAO,wBAAwB,EAAE,cAAc;AACrD,OAAI,CAAC,KAAM;AACX,QAAK,SAAS,IAAI,YAAY,EAAE,YAAY,KAAK;IACjD;EAEF,MAAM,SAAS,IAAI,iBAAiB,uBAAuB,OAAO,QAAQ;GACxE,MAAM,IAAI;AACV,OAAI,EAAE,aAAa,mBAAoB;GAGvC,MAAM,OAAO,wBAAwB,EAAE,QAAQ,EAAE,oBAAoB,MAAM,CAAC;AAC5E,QAAK,MAAM,IAAI,YAAY,EAAE,YAAY,KAAK;IAC9C;AAEF,SAAO,EACL,eAAe;AACb,cAAW;AACX,WAAQ;AACR,QAAK,mBAAmB;KAE3B;;;CAMH,SAAS,YAAoB,YAAoB,UAAkC;EACjF,MAAM,MAAM,SAAS,YAAY,WAAW;EAC5C,MAAM,QAAQ,KAAK,iBAAiB,KAAK,SAAS;AAClD,QAAM,eAAe,MAAM;AAC3B,QAAM,WAAW;EAEjB,MAAM,QAAQ,WAAW,MAAM,cAAc,SAAS;AACtD,OAAK,MAAM,OAAO,KAAK,YACrB,MAAK,kBAAkB,OAAO,YAAY,KAAK;GAAE,SAAS;GAAO;GAAO,CAAC;;;CAK7E,MAAM,YAAoB,YAAoB,UAAyC;EACrF,MAAM,MAAM,SAAS,YAAY,WAAW;EAC5C,MAAM,QAAQ,KAAK,OAAO,IAAI,IAAI;AAClC,MAAI,CAAC,MAAO;AACZ,MAAI,SAAU,OAAM,WAAW;AAE/B,OAAK,MAAM,OAAO,KAAK,aAAa;AAElC,QAAK,cAAc,OAAO,IAAI,UAAU;AACxC,QAAK,kBAAkB,OAAO,YAAY,KAAK;IAAE,SAAS;IAAM,OAAO;IAAM,CAAC;;AAKhF,mBAAiB,KAAK,OAAO,OAAO,IAAI,EAAE,IAAM;;CAKlD,kBACE,OACA,YACA,KACA,OACM;EACN,MAAM,MAAM,KAAK,uBAAuB,IAAI;AAC5C,MAAI,CAAC,IAAI,QAAS;AAClB,MAAI,IAAI,SAAS,gBAAgB,CAAC,MAAM,QAAS;EAEjD,MAAM,UAAU,KAAK,wBAAwB,OAAO,IAAI,UAAU;AAGlE,MAAI,MAAM,WAAW,MAAM,OAAO;AAChC,QAAK,cAAc,OAAO,IAAI,UAAU;AACnC,QAAK,QAAQ,OAAO,YAAY,KAAK,KAAK,MAAM,QAAQ;AAC7D;;EAGF,MAAM,UAAU,KAAK,KAAK,GAAG,QAAQ;EACrC,MAAM,OAAO,KAAK,IAAI,GAAG,IAAI,aAAa,QAAQ;AAClD,MAAI,SAAS,GAAG;AACT,QAAK,QAAQ,OAAO,YAAY,KAAK,KAAK,MAAM;AACrD;;AAEF,MAAI,QAAQ,aAAc;AAC1B,UAAQ,eAAe,iBAAiB;AACtC,WAAQ,eAAe,KAAA;AAClB,QAAK,QAAQ,OAAO,YAAY,KAAK,KAAK,MAAM;KACpD,KAAK;;CAGV,MAAc,QACZ,OACA,YACA,KACA,KACA,SACe;EACf,MAAM,UAAU,KAAK,wBAAwB,OAAO,IAAI,UAAU;AAGlE,MAAI,QAAQ,SAAU,OAAM,QAAQ,SAAS,YAAY,KAAA,EAAU;EAEnE,MAAM,OAAO,mBAAmB,MAAM,UAAU,SAAS;GACvD,mBAAmB;GACnB,SAAS;GACT,oBAAoB;GACrB,CAAC;EAEF,MAAM,oBAAoB,IAAI,SAAS,SAAS,QAAQ,gBAAgB,KAAA;EACxE,MAAM,OAAO,IACV,aAAa;GAAE;GAAY;GAAM;GAAmB;GAAS,MAAM,IAAI;GAAM,CAAC,CAC9E,MAAM,MAAM;AACX,WAAQ,gBAAgB,EAAE;AAC1B,WAAQ,aAAa,KAAK,KAAK;IAC/B,CACD,OAAO,QAAQ;GACd,MAAM,MAAM,eAAe,QAAQ,IAAI,UAAU,OAAO,IAAI;AAC5D,OAAI,KACF;IAAE;IAAK,cAAc;IAAK,WAAW,IAAI;IAAW;IAAY,EAChE,0CAA0C,MAC3C;IACD,CACD,cAAc;AACb,WAAQ,WAAW,KAAA;IACnB;AAEJ,UAAQ,WAAW;AACnB,QAAM;;CAGR,cAAsB,OAAiB,WAAyB;EAC9D,MAAM,UAAU,MAAM,WAAW,IAAI,UAAU;AAC/C,MAAI,SAAS,cAAc;AACzB,gBAAa,QAAQ,aAAa;AAClC,WAAQ,eAAe,KAAA;;;CAI3B,oBAAkC;AAChC,OAAK,MAAM,SAAS,KAAK,OAAO,QAAQ,CACtC,MAAK,MAAM,MAAM,MAAM,WAAW,QAAQ,CACxC,KAAI,GAAG,aAAc,cAAa,GAAG,aAAa;AAGtD,OAAK,OAAO,OAAO;;CAKrB,iBAAyB,KAAa,UAAsC;EAC1E,IAAI,QAAQ,KAAK,OAAO,IAAI,IAAI;AAChC,MAAI,CAAC,OAAO;AACV,WAAQ;IAAE;IAAU,4BAAY,IAAI,KAAK;IAAE;AAC3C,QAAK,OAAO,IAAI,KAAK,MAAM;;AAE7B,SAAO;;CAGT,wBAAgC,OAAiB,WAAoC;EACnF,IAAI,KAAK,MAAM,WAAW,IAAI,UAAU;AACxC,MAAI,CAAC,IAAI;AACP,QAAK,EAAE,YAAY,GAAG;AACtB,SAAM,WAAW,IAAI,WAAW,GAAG;;AAErC,SAAO;;;CAIT,uBAA+B,KAAyD;EACtF,MAAM,SAAS,KAAK,SAAS,IAAI,IAAI,UAAU;AAC/C,MAAI,OAAQ,QAAO;EACnB,MAAM,WAAW,kBAAkB,KAAK,KAAK,aAAa,EAAE,IAAI,UAAU;EAC1E,MAAM,WAAoC;GACxC,SAAS,UAAU,WAAW;GAC9B,YAAY,UAAU,cAAc,IAAI;GACxC,MAAM,UAAU,QAAQ,IAAI;GAC7B;AACD,OAAK,SAAS,IAAI,IAAI,WAAW,SAAS;AAC1C,SAAO;;;CAIT,wBAA8B;AAC5B,OAAK,SAAS,OAAO;;;CAMvB,cAAsB;AACpB,SAAO,KAAK,OAAO;;;AAMvB,IAAI,YAA2C;;;;;AAM/C,SAAgB,4BAAoD;AAClE,KAAI,CAAC,UAAW,aAAY,IAAI,wBAAwB;AACxD,QAAO;;;AAIT,SAAgB,uCAA6C;AAC3D,aAAY;;AAKd,SAAS,SAAS,YAAoB,YAAwC;AAC5E,QAAO,GAAG,WAAW,GAAG,cAAc;;;;;;;AAQxC,SAAS,WAAW,MAAoC,MAAiC;AACvF,KAAI,CAAC,KAAM,QAAO;AAClB,KAAI,KAAK,iBAAiB,KAAK,aAAc,QAAO;AACpD,KAAI,KAAK,aAAa,KAAK,WAAY,QAAO;AAC9C,KAAI,KAAK,eAAe,KAAK,aAAc,QAAO;AAElD,KAAI,KAAK,OAAO,WAAW,KAAK,OAAO,OAAQ,QAAO;AACtD,KAAI,kBAAkB,KAAK,QAAQ,KAAK,OAAO,CAAE,QAAO;AACxD,QAAO;;AAGT,SAAS,kBACP,MACA,MACS;CACT,MAAM,UAAU,IAAI,IAClB,KAAK,QAAQ,MAAM,EAAE,WAAW,WAAW,EAAE,WAAW,UAAU,CAAC,KAAK,MAAM,EAAE,GAAG,CACpF;AACD,MAAK,MAAM,KAAK,KACd,MAAK,EAAE,WAAW,WAAW,EAAE,WAAW,cAAc,CAAC,QAAQ,IAAI,EAAE,GAAG,CAAE,QAAO;AAErF,QAAO;;;;;;;;;;AAWT,SAAS,wBACP,SACA,OAAyC,EAAE,EAClB;AACzB,KAAI,CAAC,WAAW,OAAO,YAAY,SAAU,QAAO;CACpD,MAAM,MAAM;AACZ,KAAI,KAAK,oBAAoB;EAC3B,MAAM,UAAU,IAAI;AACpB,MAAI,WAAW,OAAO,YAAY,SAAU,QAAO,OAAO,QAAQ;AAClE,SAAO;;AAET,KAAI,aAAa,KAAK;EACpB,MAAM,UAAU,IAAI;AACpB,MAAI,WAAW,OAAO,YAAY,SAAU,QAAO,OAAO,QAAQ;AAClE,SAAO;;AAET,QAAO,OAAO,IAAI;;AAGpB,SAAS,OAAO,OAAyC;AACvD,KAAI,CAAC,SAAS,OAAO,UAAU,SAAU,QAAO;CAChD,MAAM,MAAM;AACZ,KAAI,OAAO,IAAI,SAAS,SAAU,QAAO;AACzC,KAAI,CAAC,MAAM,QAAQ,IAAI,OAAO,CAAE,QAAO;AACvC,QAAO;;AAGT,SAAS,kBACP,QACA,WACqF;CACrF,MAAM,WAAW,QAAQ;AACzB,KAAI,CAAC,SAAU,QAAO,KAAA;CACtB,MAAM,MAAM,SAAS;AACrB,KAAI,CAAC,OAAO,OAAO,QAAQ,SAAU,QAAO,KAAA;CAC5C,MAAM,KAAM,IAAuC;AACnD,KAAI,CAAC,MAAM,OAAO,OAAO,SAAU,QAAO,KAAA;AAC1C,QAAO"}

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

@@ -0,0 +1,31 @@
+/**
+ * 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.
+ */
+import type { SubagentRunner, WorkflowRunOptions, WorkflowRunResult, WorkflowSnapshot } from './types.js';
+export interface RunWorkflowDeps {
+    runner: SubagentRunner;
+}
+export declare function runWorkflow<T = unknown>(script: string, deps: RunWorkflowDeps, options: WorkflowRunOptions): Promise<WorkflowRunResult<T>>;
+export declare function emptySnapshotFor(name: string, description?: string): WorkflowSnapshot;