@xopcai/xopc 0.0.83 → 0.0.85

package/dist/src/agent/tools/workflow-tool.js

@@ -0,0 +1,271 @@
+import { createLogger } from "../../utils/logger/index.js";
+import { init_logger } from "../../utils/logger.js";
+import { parseWorkflowScript } from "../workflow/parser.js";
+import { getLastWorkflowMemory } from "../workflow/last-run-memory.js";
+import { previewValue, recomputeCounts, renderWorkflowText } from "../workflow/snapshot.js";
+import { runWorkflow } from "../workflow/runtime.js";
+import { DelegateSubagentRunner } from "../workflow/subagent-runner.js";
+import "../workflow/index.js";
+import { Type } from "@sinclair/typebox";
+//#region src/agent/tools/workflow-tool.ts
+/**
+* `workflow` — the AgentTool the parent model calls to spawn a fan-out run.
+*
+* Shape mirrors `delegate-tool`: factory builds a closure over deps; `execute`
+* parses the script, instantiates the {@link DelegateSubagentRunner}, drives the
+* {@link runWorkflow} runtime, and pushes a live text snapshot through
+* `onUpdate` for streaming UIs (TUI, gateway console).
+*
+* Why this lives in `src/agent/tools/` (not under `src/agent/workflow/`):
+* the runtime is reusable infrastructure; the AgentTool wrapping is a
+* presentation concern that depends on the AgentToolsFactory wiring. Keeping
+* the wrapper here matches how `delegate-tool` and `execute-code-tool` are
+* organised today.
+*/
+init_logger();
+const log = createLogger("workflow-tool");
+const DEFAULT_TIMEOUT_SEC = 1800;
+const MAX_TIMEOUT_SEC = 14400;
+const DEFAULT_MAX_CONCURRENCY = 16;
+const DEFAULT_MAX_SUBAGENTS = 1e3;
+const WorkflowToolSchema = Type.Object({
+	name: Type.Optional(Type.String({ description: "Name of a saved workflow to run. Either `name` or `script` is required. Use `name` whenever the user references a known workflow (built-in or in ~/.xopc/workflows/)." })),
+	script: Type.Optional(Type.String({ description: [
+		"Raw JavaScript workflow script (no Markdown fences, no TypeScript syntax). Ignored when `name` is set.",
+		"First statement: export const meta = { name: 'snake_case', description: 'short, human-readable' }.",
+		"Use phase(title), agent(prompt, opts), parallel(arrayOfFunctions), pipeline(items, ...stages), log(message), args, and budget.",
+		"The script must call agent() at least once.",
+		"parallel() requires functions: await parallel(items.map(item => () => agent(...)))."
+	].join(" ") })),
+	args: Type.Optional(Type.Any({ description: "Optional JSON value exposed to the workflow script as the global `args`." }))
+});
+function createWorkflowTool(deps) {
+	return {
+		name: "workflow",
+		label: "◆ Workflow",
+		description: [
+			"Run a deterministic JavaScript workflow that orchestrates multiple isolated subagents through agent(), parallel(), and pipeline().",
+			"Two ways to invoke:",
+			"  1. `name`: run a saved workflow from the catalog (built-in or ~/.xopc/workflows/). Prefer this when the user references a known name.",
+			"  2. `script`: provide a raw JS workflow inline. Use when no saved workflow fits. Header is required: export const meta = { name, description }.",
+			"Named-workflow triggers — call this tool with `{ name: \"<name>\" }` IMMEDIATELY when the user message is any of:",
+			"  • a bare workflow name like \"/audit_repo\", \"/research\", or \"audit_repo\"",
+			"  • \"run the audit_repo workflow\", \"kick off research\", \"do a multi_perspective_review on X\" (extract args.target when natural)",
+			"  • after /workflows lists saved workflows and the user picks one",
+			"Use phase(title) at runtime to mark progress groups. Each agent() returns a string, or a schema-validated object when opts.schema is set.",
+			"Prefer for decomposable work: repo audits, multi-perspective review, fan-out research, large refactors. Do not use for a single quick read/edit.",
+			"parallel() takes thunks, not promises: parallel(items.map(item => () => agent(...))).",
+			"pipeline(items, ...stages) interleaves items across stages — fastest path by default; only use parallel() when you genuinely need a cross-item barrier.",
+			"Failed agent()/parallel()/pipeline() entries resolve to null; check before synthesizing.",
+			"Do not use Date.now(), Math.random(), new Date(), require, import, fs, or network APIs — they are unavailable for determinism.",
+			"Always end with a synthesis agent() that consolidates findings, especially when you fan out for review or research."
+		].join("\n\n"),
+		parameters: WorkflowToolSchema,
+		async execute(_toolCallId, params, signal, onUpdate) {
+			let script;
+			let resolvedSource = "script";
+			try {
+				const resolved = resolveScript(params, deps.catalog);
+				script = resolved.script;
+				resolvedSource = resolved.source;
+			} catch (e) {
+				const message = e instanceof Error ? e.message : String(e);
+				return {
+					content: [{
+						type: "text",
+						text: `workflow: ${message}`
+					}],
+					details: { error: message }
+				};
+			}
+			const wfCfg = deps.getConfig()?.agents?.defaults?.workflow;
+			const concurrency = wfCfg?.maxConcurrency ?? DEFAULT_MAX_CONCURRENCY;
+			const maxSubagents = wfCfg?.maxSubagents ?? DEFAULT_MAX_SUBAGENTS;
+			const timeoutSec = clampTimeout(wfCfg?.defaultTimeoutSec);
+			let meta;
+			try {
+				meta = parseWorkflowScript(script).meta;
+			} catch (e) {
+				const message = e instanceof Error ? e.message : String(e);
+				return {
+					content: [{
+						type: "text",
+						text: resolvedSource === "name" ? `workflow "${params.name}" failed to parse: ${message}` : `workflow parse error: ${message}`
+					}],
+					details: { error: message }
+				};
+			}
+			const snapshot = {
+				name: meta.name,
+				description: meta.description,
+				phases: [],
+				logs: [],
+				agents: [],
+				agentCount: 0,
+				runningCount: 0,
+				doneCount: 0,
+				errorCount: 0,
+				skippedCount: 0
+			};
+			const pushUpdate = (completed = false) => {
+				recomputeCounts(snapshot);
+				onUpdate?.({
+					content: [{
+						type: "text",
+						text: renderWorkflowText(snapshot, completed, { showResultPreviews: false })
+					}],
+					details: snapshot
+				});
+			};
+			const runner = new DelegateSubagentRunner({
+				workspace: deps.workspace,
+				bus: deps.bus,
+				getDefaultModel: deps.getSubagentModel,
+				getConfig: deps.getConfig,
+				toolExecutorConfig: deps.toolExecutorConfig,
+				buildChildTools: deps.buildChildTools
+			});
+			const controller = new AbortController();
+			const onParentAbort = () => controller.abort();
+			signal?.addEventListener("abort", onParentAbort, { once: true });
+			const timeoutHandle = timeoutSec > 0 ? setTimeout(() => controller.abort(), timeoutSec * 1e3) : void 0;
+			pushUpdate();
+			try {
+				const result = await runWorkflow(script, { runner }, {
+					cwd: deps.workspace,
+					args: params.args,
+					signal: controller.signal,
+					concurrency,
+					maxSubagents,
+					onLog: (message) => {
+						snapshot.logs.push(message);
+						pushUpdate();
+					},
+					onPhase: (title) => {
+						snapshot.currentPhase = title;
+						if (!snapshot.phases.includes(title)) snapshot.phases.push(title);
+						pushUpdate();
+					},
+					onAgentStart: (event) => {
+						snapshot.agents.push({
+							id: event.id,
+							label: event.label,
+							phase: event.phase,
+							prompt: event.prompt,
+							status: "running"
+						});
+						pushUpdate();
+					},
+					onAgentEnd: (event) => {
+						const agent = findAgentById(snapshot.agents, event.id);
+						if (agent) {
+							agent.status = event.status;
+							agent.resultPreview = previewValue(event.result);
+						}
+						pushUpdate();
+					}
+				});
+				if (result.agentCount === 0) {
+					const reason = "workflow scripts must call agent() at least once; this workflow declared phases but never ran a subagent.";
+					snapshot.logs.push(reason);
+					pushUpdate(true);
+					return {
+						content: [{
+							type: "text",
+							text: reason
+						}],
+						details: snapshot
+					};
+				}
+				snapshot.result = result.result;
+				snapshot.durationMs = result.durationMs;
+				pushUpdate(true);
+				try {
+					getLastWorkflowMemory().record(deps.getCurrentSessionKey?.(), {
+						script,
+						metaName: result.meta.name,
+						source: resolvedSource,
+						recordedAt: Date.now()
+					});
+				} catch {}
+				return {
+					content: [{
+						type: "text",
+						text: `workflow ${result.meta.name} completed: ${result.agentCount} subagent(s), ${snapshot.errorCount} error(s).\n\nResult:\n${safeStringify(result.result)}`
+					}],
+					details: snapshot
+				};
+			} catch (e) {
+				if (controller.signal.aborted) {
+					for (const a of snapshot.agents) if (a.status === "running") {
+						a.status = "skipped";
+						a.error = "aborted";
+					}
+					pushUpdate(true);
+					return {
+						content: [{
+							type: "text",
+							text: signal?.aborted ? "workflow aborted" : `workflow timed out after ${timeoutSec}s`
+						}],
+						details: snapshot
+					};
+				}
+				const message = e instanceof Error ? e.message : String(e);
+				log.warn({
+					err: e,
+					errorMessage: message,
+					workflow: meta.name
+				}, `workflow failed: ${message}`);
+				snapshot.logs.push(`workflow failed: ${message}`);
+				pushUpdate(true);
+				return {
+					content: [{
+						type: "text",
+						text: `workflow failed: ${message}`
+					}],
+					details: snapshot
+				};
+			} finally {
+				if (timeoutHandle) clearTimeout(timeoutHandle);
+				signal?.removeEventListener("abort", onParentAbort);
+			}
+		}
+	};
+}
+function normalizeScript(script) {
+	let text = script.trim();
+	const fence = text.match(/^```(?:js|javascript)?\s*\n([\s\S]*?)\n```$/i);
+	if (fence) text = fence[1].trim();
+	return text;
+}
+function resolveScript(params, catalog) {
+	const name = params.name?.trim();
+	if (name) return {
+		script: catalog.load(name).script,
+		source: "name"
+	};
+	if (!params.script || !params.script.trim()) throw new Error("either `name` or `script` is required.");
+	return {
+		script: normalizeScript(params.script),
+		source: "script"
+	};
+}
+function clampTimeout(requested) {
+	const v = typeof requested === "number" && Number.isFinite(requested) ? requested : DEFAULT_TIMEOUT_SEC;
+	if (v <= 0) return 0;
+	return Math.min(MAX_TIMEOUT_SEC, Math.max(1, Math.floor(v)));
+}
+function findAgentById(agents, id) {
+	for (let i = agents.length - 1; i >= 0; i--) if (agents[i].id === id) return agents[i];
+}
+function safeStringify(value) {
+	try {
+		return JSON.stringify(value, null, 2);
+	} catch {
+		return String(value);
+	}
+}
+//#endregion
+export { createWorkflowTool };
+
+//# sourceMappingURL=workflow-tool.js.map

package/dist/src/agent/tools/workflow-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-tool.js","names":[],"sources":["../../../../src/agent/tools/workflow-tool.ts"],"sourcesContent":["/**\n * `workflow` — the AgentTool the parent model calls to spawn a fan-out run.\n *\n * Shape mirrors `delegate-tool`: factory builds a closure over deps; `execute`\n * parses the script, instantiates the {@link DelegateSubagentRunner}, drives the\n * {@link runWorkflow} runtime, and pushes a live text snapshot through\n * `onUpdate` for streaming UIs (TUI, gateway console).\n *\n * Why this lives in `src/agent/tools/` (not under `src/agent/workflow/`):\n * the runtime is reusable infrastructure; the AgentTool wrapping is a\n * presentation concern that depends on the AgentToolsFactory wiring. Keeping\n * the wrapper here matches how `delegate-tool` and `execute-code-tool` are\n * organised today.\n */\n\nimport { Type } from '@sinclair/typebox';\nimport type { AgentTool, AgentToolResult } from '@earendil-works/pi-agent-core';\nimport type { Api, Model } from '@earendil-works/pi-ai';\n\nimport type { Config } from '../../config/schema.js';\nimport type { MessageBus } from '../../infra/bus/index.js';\nimport { createLogger } from '../../utils/logger.js';\n\nimport type { BuildChildToolsOptions } from '../child-agent-factory.js';\nimport {\n  DelegateSubagentRunner,\n  getLastWorkflowMemory,\n  parseWorkflowScript,\n  previewValue,\n  recomputeCounts,\n  renderWorkflowText,\n  runWorkflow,\n  type WorkflowAgentSnapshot,\n  type WorkflowCatalog,\n  type WorkflowMeta,\n  type WorkflowSnapshot,\n} from '../workflow/index.js';\nimport type { ToolExecutorConfig } from './executor.js';\n\nconst log = createLogger('workflow-tool');\n\nconst DEFAULT_TIMEOUT_SEC = 30 * 60;\nconst MAX_TIMEOUT_SEC = 4 * 60 * 60;\nconst DEFAULT_MAX_CONCURRENCY = 16;\nconst DEFAULT_MAX_SUBAGENTS = 1000;\n\nconst WorkflowToolSchema = Type.Object({\n  name: Type.Optional(\n    Type.String({\n      description:\n        'Name of a saved workflow to run. Either `name` or `script` is required. ' +\n        'Use `name` whenever the user references a known workflow (built-in or in ~/.xopc/workflows/).',\n    }),\n  ),\n  script: Type.Optional(\n    Type.String({\n      description: [\n        'Raw JavaScript workflow script (no Markdown fences, no TypeScript syntax). Ignored when `name` is set.',\n        \"First statement: export const meta = { name: 'snake_case', description: 'short, human-readable' }.\",\n        'Use phase(title), agent(prompt, opts), parallel(arrayOfFunctions), pipeline(items, ...stages), log(message), args, and budget.',\n        'The script must call agent() at least once.',\n        'parallel() requires functions: await parallel(items.map(item => () => agent(...))).',\n      ].join(' '),\n    }),\n  ),\n  args: Type.Optional(\n    Type.Any({\n      description: 'Optional JSON value exposed to the workflow script as the global `args`.',\n    }),\n  ),\n});\n\nexport type WorkflowToolInput = {\n  name?: string;\n  script?: string;\n  args?: unknown;\n};\n\nexport interface WorkflowToolDeps {\n  workspace: string;\n  bus: MessageBus;\n  /** Returns the parent agent's primary model — subagents default to this. */\n  getSubagentModel: () => Model<Api>;\n  getConfig: () => Config | undefined;\n  /** Same injection point delegate-tool uses; supplied by AgentToolsFactory. */\n  buildChildTools: (opts: BuildChildToolsOptions) => AgentTool<any, any>[];\n  toolExecutorConfig?: Partial<ToolExecutorConfig>;\n  /** Catalog for `name` lookups (built-in + ~/.xopc/workflows/). */\n  catalog: WorkflowCatalog;\n  /** Per-call sessionKey lookup — used to record \"last successful workflow\" for /workflow save. */\n  getCurrentSessionKey?: () => string | undefined;\n}\n\nexport function createWorkflowTool(deps: WorkflowToolDeps): AgentTool {\n  return {\n    name: 'workflow',\n    label: '◆ Workflow',\n    description: [\n      'Run a deterministic JavaScript workflow that orchestrates multiple isolated subagents through agent(), parallel(), and pipeline().',\n      'Two ways to invoke:',\n      '  1. `name`: run a saved workflow from the catalog (built-in or ~/.xopc/workflows/). Prefer this when the user references a known name.',\n      '  2. `script`: provide a raw JS workflow inline. Use when no saved workflow fits. Header is required: export const meta = { name, description }.',\n      'Named-workflow triggers — call this tool with `{ name: \"<name>\" }` IMMEDIATELY when the user message is any of:',\n      '  • a bare workflow name like \"/audit_repo\", \"/research\", or \"audit_repo\"',\n      '  • \"run the audit_repo workflow\", \"kick off research\", \"do a multi_perspective_review on X\" (extract args.target when natural)',\n      '  • after /workflows lists saved workflows and the user picks one',\n      'Use phase(title) at runtime to mark progress groups. Each agent() returns a string, or a schema-validated object when opts.schema is set.',\n      'Prefer for decomposable work: repo audits, multi-perspective review, fan-out research, large refactors. Do not use for a single quick read/edit.',\n      'parallel() takes thunks, not promises: parallel(items.map(item => () => agent(...))).',\n      'pipeline(items, ...stages) interleaves items across stages — fastest path by default; only use parallel() when you genuinely need a cross-item barrier.',\n      'Failed agent()/parallel()/pipeline() entries resolve to null; check before synthesizing.',\n      'Do not use Date.now(), Math.random(), new Date(), require, import, fs, or network APIs — they are unavailable for determinism.',\n      'Always end with a synthesis agent() that consolidates findings, especially when you fan out for review or research.',\n    ].join('\\n\\n'),\n    parameters: WorkflowToolSchema,\n\n    async execute(\n      _toolCallId: string,\n      params: WorkflowToolInput,\n      signal?: AbortSignal,\n      onUpdate?: (update: AgentToolResult<WorkflowSnapshot | undefined>) => void,\n    ): Promise<AgentToolResult<WorkflowSnapshot | { error: string }>> {\n      let script: string;\n      let resolvedSource: 'name' | 'script' = 'script';\n      try {\n        const resolved = resolveScript(params, deps.catalog);\n        script = resolved.script;\n        resolvedSource = resolved.source;\n      } catch (e) {\n        const message = e instanceof Error ? e.message : String(e);\n        return {\n          content: [{ type: 'text', text: `workflow: ${message}` }],\n          details: { error: message },\n        };\n      }\n\n      const cfg = deps.getConfig();\n      const wfCfg = cfg?.agents?.defaults?.workflow;\n      const concurrency = wfCfg?.maxConcurrency ?? DEFAULT_MAX_CONCURRENCY;\n      const maxSubagents = wfCfg?.maxSubagents ?? DEFAULT_MAX_SUBAGENTS;\n      const timeoutSec = clampTimeout(wfCfg?.defaultTimeoutSec);\n\n      // Parse early so a bad script returns an error result instead of throwing\n      // through the agent loop. The runtime parses again, but that's cheap.\n      let meta: WorkflowMeta;\n      try {\n        meta = parseWorkflowScript(script).meta;\n      } catch (e) {\n        const message = e instanceof Error ? e.message : String(e);\n        return {\n          content: [\n            {\n              type: 'text',\n              text:\n                resolvedSource === 'name'\n                  ? `workflow \"${params.name}\" failed to parse: ${message}`\n                  : `workflow parse error: ${message}`,\n            },\n          ],\n          details: { error: message },\n        };\n      }\n\n      const snapshot: WorkflowSnapshot = {\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      const pushUpdate = (completed = false) => {\n        recomputeCounts(snapshot);\n        onUpdate?.({\n          content: [\n            {\n              type: 'text',\n              text: renderWorkflowText(snapshot, completed, { showResultPreviews: false }),\n            },\n          ],\n          details: snapshot,\n        });\n      };\n\n      const runner = new DelegateSubagentRunner({\n        workspace: deps.workspace,\n        bus: deps.bus,\n        getDefaultModel: deps.getSubagentModel,\n        getConfig: deps.getConfig,\n        toolExecutorConfig: deps.toolExecutorConfig,\n        buildChildTools: deps.buildChildTools,\n      });\n\n      // Combined abort: parent signal + per-run timeout.\n      const controller = new AbortController();\n      const onParentAbort = () => controller.abort();\n      signal?.addEventListener('abort', onParentAbort, { once: true });\n      const timeoutHandle =\n        timeoutSec > 0\n          ? setTimeout(() => controller.abort(), timeoutSec * 1000)\n          : undefined;\n\n      pushUpdate();\n\n      try {\n        const result = await runWorkflow(script, { runner }, {\n          cwd: deps.workspace,\n          args: params.args,\n          signal: controller.signal,\n          concurrency,\n          maxSubagents,\n          onLog: (message) => {\n            snapshot.logs.push(message);\n            pushUpdate();\n          },\n          onPhase: (title) => {\n            snapshot.currentPhase = title;\n            if (!snapshot.phases.includes(title)) snapshot.phases.push(title);\n            pushUpdate();\n          },\n          onAgentStart: (event) => {\n            snapshot.agents.push({\n              id: event.id,\n              label: event.label,\n              phase: event.phase,\n              prompt: event.prompt,\n              status: 'running',\n            });\n            pushUpdate();\n          },\n          onAgentEnd: (event) => {\n            const agent = findAgentById(snapshot.agents, event.id);\n            if (agent) {\n              agent.status = event.status;\n              agent.resultPreview = previewValue(event.result);\n            }\n            pushUpdate();\n          },\n        });\n\n        if (result.agentCount === 0) {\n          const reason =\n            'workflow scripts must call agent() at least once; this workflow declared phases but never ran a subagent.';\n          snapshot.logs.push(reason);\n          pushUpdate(true);\n          return {\n            content: [{ type: 'text', text: reason }],\n            details: snapshot,\n          };\n        }\n\n        snapshot.result = result.result;\n        snapshot.durationMs = result.durationMs;\n        pushUpdate(true);\n\n        // Record for /workflow save — last successful run per session.\n        // Failures are intentionally skipped so users do not save broken scripts.\n        try {\n          getLastWorkflowMemory().record(deps.getCurrentSessionKey?.(), {\n            script,\n            metaName: result.meta.name,\n            source: resolvedSource,\n            recordedAt: Date.now(),\n          });\n        } catch {\n          // Memory recording is best-effort; never break a successful run on it.\n        }\n\n        return {\n          content: [\n            {\n              type: 'text',\n              text: `workflow ${result.meta.name} completed: ${result.agentCount} subagent(s), ${snapshot.errorCount} error(s).\\n\\nResult:\\n${safeStringify(result.result)}`,\n            },\n          ],\n          details: snapshot,\n        };\n      } catch (e) {\n        if (controller.signal.aborted) {\n          for (const a of snapshot.agents) {\n            if (a.status === 'running') {\n              a.status = 'skipped';\n              a.error = 'aborted';\n            }\n          }\n          pushUpdate(true);\n          const reason = signal?.aborted ? 'workflow aborted' : `workflow timed out after ${timeoutSec}s`;\n          return {\n            content: [{ type: 'text', text: reason }],\n            details: snapshot,\n          };\n        }\n        const message = e instanceof Error ? e.message : String(e);\n        log.warn({ err: e, errorMessage: message, workflow: meta.name }, `workflow failed: ${message}`);\n        snapshot.logs.push(`workflow failed: ${message}`);\n        pushUpdate(true);\n        return {\n          content: [{ type: 'text', text: `workflow failed: ${message}` }],\n          details: snapshot,\n        };\n      } finally {\n        if (timeoutHandle) clearTimeout(timeoutHandle);\n        signal?.removeEventListener('abort', onParentAbort);\n      }\n    },\n  } as unknown as AgentTool;\n}\n\n// ---------------------------------------------------------------------------\n\nfunction normalizeScript(script: string): string {\n  let text = script.trim();\n  const fence = text.match(/^```(?:js|javascript)?\\s*\\n([\\s\\S]*?)\\n```$/i);\n  if (fence) text = fence[1].trim();\n  return text;\n}\n\nfunction resolveScript(\n  params: WorkflowToolInput,\n  catalog: WorkflowCatalog,\n): { script: string; source: 'name' | 'script' } {\n  const name = params.name?.trim();\n  if (name) {\n    const loaded = catalog.load(name);\n    return { script: loaded.script, source: 'name' };\n  }\n  if (!params.script || !params.script.trim()) {\n    throw new Error('either `name` or `script` is required.');\n  }\n  return { script: normalizeScript(params.script), source: 'script' };\n}\n\nfunction clampTimeout(requested: number | undefined): number {\n  const v = typeof requested === 'number' && Number.isFinite(requested) ? requested : DEFAULT_TIMEOUT_SEC;\n  if (v <= 0) return 0;\n  return Math.min(MAX_TIMEOUT_SEC, Math.max(1, Math.floor(v)));\n}\n\nfunction findAgentById(agents: WorkflowAgentSnapshot[], id: number): WorkflowAgentSnapshot | undefined {\n  // Linear scan — agent lists are small in practice (capped at maxSubagents).\n  for (let i = agents.length - 1; i >= 0; i--) {\n    if (agents[i].id === id) return agents[i];\n  }\n  return undefined;\n}\n\nfunction safeStringify(value: unknown): string {\n  try {\n    return JSON.stringify(value, null, 2);\n  } catch {\n    return String(value);\n  }\n}\n"],"mappings":"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"}

package/dist/src/agent/tools/write.js

@@ -1,8 +1,8 @@
 import { checkFileSafety } from "../prompt/safety.js";
 import { resolvePathUnderWorkspace } from "./tool-paths.js";
 import { evaluateFilePolicy } from "../sandbox/exec-policy.js";
-import { mkdir, writeFile } from "fs/promises";
 import { dirname } from "path";
+import { mkdir, writeFile } from "fs/promises";
 import { Type } from "@sinclair/typebox";
 //#region src/agent/tools/write.ts
 const MAX_FILE_SIZE = 10 * 1024 * 1024;

package/dist/src/agent/workflow/builtins/audit-repo.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Built-in workflow: `audit_repo`
+ *
+ * Fan-out repo audit. Phase 1 inventories the repo; phase 2 spawns N reviewers
+ * in parallel, one per dimension (bugs / perf / security / tests / style);
+ * phase 3 synthesises into a structured report. The script is kept readable so
+ * users can copy it into `~/.xopc/workflows/` as a starting point.
+ */
+export declare const AUDIT_REPO_SCRIPT = "export const meta = {\n  name: 'audit_repo',\n  description: 'Fan-out repository audit across multiple dimensions, then synthesize a structured report.',\n  whenToUse: 'User asks for a thorough / multi-dimension code review of the whole repo or a major subsystem.',\n  phases: [\n    { title: 'Inventory' },\n    { title: 'Review' },\n    { title: 'Synthesize' },\n  ],\n}\n\nconst DIMENSIONS = [\n  { key: 'bugs', focus: 'Correctness bugs, null-safety, error handling, race conditions, off-by-one, dead code.' },\n  { key: 'perf', focus: 'Performance issues, hot paths, N+1 patterns, accidental quadratic loops, sync I/O, missing caching.' },\n  { key: 'security', focus: 'Auth/authz, input validation, secret handling, injection sinks, unsafe deserialization, SSRF.' },\n  { key: 'tests', focus: 'Test coverage gaps, brittle tests, integration vs unit gaps, missing regression cases.' },\n  { key: 'style', focus: 'Inconsistent conventions, naming, unused exports, duplication, layering violations.' },\n]\n\nphase('Inventory')\nconst inventory = await agent(\n  'Produce a compact map of this repository: top-level layout, main modules, the 5\u201310 most important files, and any obvious entry points. Be terse and structured.',\n  { label: 'repo inventory' },\n)\n\nphase('Review')\nconst findings = await parallel(\n  DIMENSIONS.map((d) => () =>\n    agent(\n      'Review the repository through the ' + d.key + ' lens.\\n' +\n        'Focus: ' + d.focus + '\\n\\n' +\n        'Inventory for orientation:\\n' + inventory + '\\n\\n' +\n        'Return findings: file paths, line numbers when known, severity (low/med/high), a one-sentence why, a one-sentence fix.',\n      {\n        label: d.key + ' review',\n        schema: {\n          type: 'object',\n          properties: {\n            findings: {\n              type: 'array',\n              items: {\n                type: 'object',\n                properties: {\n                  file: { type: 'string' },\n                  line: { type: ['number', 'string'] },\n                  severity: { type: 'string', enum: ['low', 'med', 'high'] },\n                  title: { type: 'string' },\n                  fix: { type: 'string' },\n                },\n                required: ['file', 'severity', 'title', 'fix'],\n              },\n            },\n          },\n          required: ['findings'],\n        },\n      },\n    ),\n  ),\n)\n\nphase('Synthesize')\nconst live = findings.filter(Boolean)\nif (!live.length) {\n  return { ok: true, summary: 'No findings.', byDimension: {} }\n}\nconst byDimension = {}\nfor (let i = 0; i < DIMENSIONS.length; i++) {\n  byDimension[DIMENSIONS[i].key] = live[i]?.findings ?? []\n}\n\nconst summary = await agent(\n  'Synthesize a compact report from these per-dimension findings. Deduplicate near-identical items. ' +\n    'Order by severity (high \u2192 low). Cap at 20 entries. Return JSON.\\n\\n' +\n    JSON.stringify(byDimension, null, 2),\n  {\n    label: 'report synthesis',\n    schema: {\n      type: 'object',\n      properties: {\n        topFindings: {\n          type: 'array',\n          items: {\n            type: 'object',\n            properties: {\n              dimension: { type: 'string' },\n              file: { type: 'string' },\n              severity: { type: 'string' },\n              title: { type: 'string' },\n              fix: { type: 'string' },\n            },\n            required: ['dimension', 'file', 'severity', 'title'],\n          },\n        },\n        summary: { type: 'string' },\n      },\n      required: ['topFindings', 'summary'],\n    },\n  },\n)\n\nreturn { ok: true, ...(summary ?? { topFindings: [], summary: 'synthesis failed' }), byDimension }\n";

package/dist/src/agent/workflow/builtins/audit-repo.js

@@ -0,0 +1,115 @@
+//#region src/agent/workflow/builtins/audit-repo.ts
+/**
+* Built-in workflow: `audit_repo`
+*
+* Fan-out repo audit. Phase 1 inventories the repo; phase 2 spawns N reviewers
+* in parallel, one per dimension (bugs / perf / security / tests / style);
+* phase 3 synthesises into a structured report. The script is kept readable so
+* users can copy it into `~/.xopc/workflows/` as a starting point.
+*/
+const AUDIT_REPO_SCRIPT = `export const meta = {
+  name: 'audit_repo',
+  description: 'Fan-out repository audit across multiple dimensions, then synthesize a structured report.',
+  whenToUse: 'User asks for a thorough / multi-dimension code review of the whole repo or a major subsystem.',
+  phases: [
+    { title: 'Inventory' },
+    { title: 'Review' },
+    { title: 'Synthesize' },
+  ],
+}
+
+const DIMENSIONS = [
+  { key: 'bugs', focus: 'Correctness bugs, null-safety, error handling, race conditions, off-by-one, dead code.' },
+  { key: 'perf', focus: 'Performance issues, hot paths, N+1 patterns, accidental quadratic loops, sync I/O, missing caching.' },
+  { key: 'security', focus: 'Auth/authz, input validation, secret handling, injection sinks, unsafe deserialization, SSRF.' },
+  { key: 'tests', focus: 'Test coverage gaps, brittle tests, integration vs unit gaps, missing regression cases.' },
+  { key: 'style', focus: 'Inconsistent conventions, naming, unused exports, duplication, layering violations.' },
+]
+
+phase('Inventory')
+const inventory = await agent(
+  'Produce a compact map of this repository: top-level layout, main modules, the 5–10 most important files, and any obvious entry points. Be terse and structured.',
+  { label: 'repo inventory' },
+)
+
+phase('Review')
+const findings = await parallel(
+  DIMENSIONS.map((d) => () =>
+    agent(
+      'Review the repository through the ' + d.key + ' lens.\\n' +
+        'Focus: ' + d.focus + '\\n\\n' +
+        'Inventory for orientation:\\n' + inventory + '\\n\\n' +
+        'Return findings: file paths, line numbers when known, severity (low/med/high), a one-sentence why, a one-sentence fix.',
+      {
+        label: d.key + ' review',
+        schema: {
+          type: 'object',
+          properties: {
+            findings: {
+              type: 'array',
+              items: {
+                type: 'object',
+                properties: {
+                  file: { type: 'string' },
+                  line: { type: ['number', 'string'] },
+                  severity: { type: 'string', enum: ['low', 'med', 'high'] },
+                  title: { type: 'string' },
+                  fix: { type: 'string' },
+                },
+                required: ['file', 'severity', 'title', 'fix'],
+              },
+            },
+          },
+          required: ['findings'],
+        },
+      },
+    ),
+  ),
+)
+
+phase('Synthesize')
+const live = findings.filter(Boolean)
+if (!live.length) {
+  return { ok: true, summary: 'No findings.', byDimension: {} }
+}
+const byDimension = {}
+for (let i = 0; i < DIMENSIONS.length; i++) {
+  byDimension[DIMENSIONS[i].key] = live[i]?.findings ?? []
+}
+
+const summary = await agent(
+  'Synthesize a compact report from these per-dimension findings. Deduplicate near-identical items. ' +
+    'Order by severity (high → low). Cap at 20 entries. Return JSON.\\n\\n' +
+    JSON.stringify(byDimension, null, 2),
+  {
+    label: 'report synthesis',
+    schema: {
+      type: 'object',
+      properties: {
+        topFindings: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              dimension: { type: 'string' },
+              file: { type: 'string' },
+              severity: { type: 'string' },
+              title: { type: 'string' },
+              fix: { type: 'string' },
+            },
+            required: ['dimension', 'file', 'severity', 'title'],
+          },
+        },
+        summary: { type: 'string' },
+      },
+      required: ['topFindings', 'summary'],
+    },
+  },
+)
+
+return { ok: true, ...(summary ?? { topFindings: [], summary: 'synthesis failed' }), byDimension }
+`;
+//#endregion
+export { AUDIT_REPO_SCRIPT };
+
+//# sourceMappingURL=audit-repo.js.map

package/dist/src/agent/workflow/builtins/audit-repo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-repo.js","names":[],"sources":["../../../../../src/agent/workflow/builtins/audit-repo.ts"],"sourcesContent":["/**\n * Built-in workflow: `audit_repo`\n *\n * Fan-out repo audit. Phase 1 inventories the repo; phase 2 spawns N reviewers\n * in parallel, one per dimension (bugs / perf / security / tests / style);\n * phase 3 synthesises into a structured report. The script is kept readable so\n * users can copy it into `~/.xopc/workflows/` as a starting point.\n */\n\nexport const AUDIT_REPO_SCRIPT = `export const meta = {\n  name: 'audit_repo',\n  description: 'Fan-out repository audit across multiple dimensions, then synthesize a structured report.',\n  whenToUse: 'User asks for a thorough / multi-dimension code review of the whole repo or a major subsystem.',\n  phases: [\n    { title: 'Inventory' },\n    { title: 'Review' },\n    { title: 'Synthesize' },\n  ],\n}\n\nconst DIMENSIONS = [\n  { key: 'bugs', focus: 'Correctness bugs, null-safety, error handling, race conditions, off-by-one, dead code.' },\n  { key: 'perf', focus: 'Performance issues, hot paths, N+1 patterns, accidental quadratic loops, sync I/O, missing caching.' },\n  { key: 'security', focus: 'Auth/authz, input validation, secret handling, injection sinks, unsafe deserialization, SSRF.' },\n  { key: 'tests', focus: 'Test coverage gaps, brittle tests, integration vs unit gaps, missing regression cases.' },\n  { key: 'style', focus: 'Inconsistent conventions, naming, unused exports, duplication, layering violations.' },\n]\n\nphase('Inventory')\nconst inventory = await agent(\n  'Produce a compact map of this repository: top-level layout, main modules, the 5–10 most important files, and any obvious entry points. Be terse and structured.',\n  { label: 'repo inventory' },\n)\n\nphase('Review')\nconst findings = await parallel(\n  DIMENSIONS.map((d) => () =>\n    agent(\n      'Review the repository through the ' + d.key + ' lens.\\\\n' +\n        'Focus: ' + d.focus + '\\\\n\\\\n' +\n        'Inventory for orientation:\\\\n' + inventory + '\\\\n\\\\n' +\n        'Return findings: file paths, line numbers when known, severity (low/med/high), a one-sentence why, a one-sentence fix.',\n      {\n        label: d.key + ' review',\n        schema: {\n          type: 'object',\n          properties: {\n            findings: {\n              type: 'array',\n              items: {\n                type: 'object',\n                properties: {\n                  file: { type: 'string' },\n                  line: { type: ['number', 'string'] },\n                  severity: { type: 'string', enum: ['low', 'med', 'high'] },\n                  title: { type: 'string' },\n                  fix: { type: 'string' },\n                },\n                required: ['file', 'severity', 'title', 'fix'],\n              },\n            },\n          },\n          required: ['findings'],\n        },\n      },\n    ),\n  ),\n)\n\nphase('Synthesize')\nconst live = findings.filter(Boolean)\nif (!live.length) {\n  return { ok: true, summary: 'No findings.', byDimension: {} }\n}\nconst byDimension = {}\nfor (let i = 0; i < DIMENSIONS.length; i++) {\n  byDimension[DIMENSIONS[i].key] = live[i]?.findings ?? []\n}\n\nconst summary = await agent(\n  'Synthesize a compact report from these per-dimension findings. Deduplicate near-identical items. ' +\n    'Order by severity (high → low). Cap at 20 entries. Return JSON.\\\\n\\\\n' +\n    JSON.stringify(byDimension, null, 2),\n  {\n    label: 'report synthesis',\n    schema: {\n      type: 'object',\n      properties: {\n        topFindings: {\n          type: 'array',\n          items: {\n            type: 'object',\n            properties: {\n              dimension: { type: 'string' },\n              file: { type: 'string' },\n              severity: { type: 'string' },\n              title: { type: 'string' },\n              fix: { type: 'string' },\n            },\n            required: ['dimension', 'file', 'severity', 'title'],\n          },\n        },\n        summary: { type: 'string' },\n      },\n      required: ['topFindings', 'summary'],\n    },\n  },\n)\n\nreturn { ok: true, ...(summary ?? { topFindings: [], summary: 'synthesis failed' }), byDimension }\n`\n"],"mappings":";;;;;;;;;AASA,MAAa,oBAAoB"}

package/dist/src/agent/workflow/builtins/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Bundled workflow templates. These are shipped with xopc and discoverable
+ * via the catalog alongside user workflows in `~/.xopc/workflows/`. A user
+ * workflow with the same `name` always wins — built-ins are starting points,
+ * not authority.
+ */
+import { AUDIT_REPO_SCRIPT } from './audit-repo.js';
+import { MULTI_PERSPECTIVE_REVIEW_SCRIPT } from './multi-perspective-review.js';
+import { RESEARCH_SCRIPT } from './research.js';
+export interface BuiltinWorkflow {
+    name: string;
+    script: string;
+}
+export declare const BUILTIN_WORKFLOWS: readonly BuiltinWorkflow[];
+export { AUDIT_REPO_SCRIPT, MULTI_PERSPECTIVE_REVIEW_SCRIPT, RESEARCH_SCRIPT };

package/dist/src/agent/workflow/builtins/index.js

@@ -0,0 +1,28 @@
+import { AUDIT_REPO_SCRIPT } from "./audit-repo.js";
+import { MULTI_PERSPECTIVE_REVIEW_SCRIPT } from "./multi-perspective-review.js";
+import { RESEARCH_SCRIPT } from "./research.js";
+//#region src/agent/workflow/builtins/index.ts
+/**
+* Bundled workflow templates. These are shipped with xopc and discoverable
+* via the catalog alongside user workflows in `~/.xopc/workflows/`. A user
+* workflow with the same `name` always wins — built-ins are starting points,
+* not authority.
+*/
+const BUILTIN_WORKFLOWS = Object.freeze([
+	{
+		name: "audit_repo",
+		script: AUDIT_REPO_SCRIPT
+	},
+	{
+		name: "multi_perspective_review",
+		script: MULTI_PERSPECTIVE_REVIEW_SCRIPT
+	},
+	{
+		name: "research",
+		script: RESEARCH_SCRIPT
+	}
+]);
+//#endregion
+export { AUDIT_REPO_SCRIPT, BUILTIN_WORKFLOWS, MULTI_PERSPECTIVE_REVIEW_SCRIPT, RESEARCH_SCRIPT };
+
+//# sourceMappingURL=index.js.map

package/dist/src/agent/workflow/builtins/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../../../../src/agent/workflow/builtins/index.ts"],"sourcesContent":["/**\n * Bundled workflow templates. These are shipped with xopc and discoverable\n * via the catalog alongside user workflows in `~/.xopc/workflows/`. A user\n * workflow with the same `name` always wins — built-ins are starting points,\n * not authority.\n */\n\nimport { AUDIT_REPO_SCRIPT } from './audit-repo.js';\nimport { MULTI_PERSPECTIVE_REVIEW_SCRIPT } from './multi-perspective-review.js';\nimport { RESEARCH_SCRIPT } from './research.js';\n\nexport interface BuiltinWorkflow {\n  name: string;\n  script: string;\n}\n\nexport const BUILTIN_WORKFLOWS: readonly BuiltinWorkflow[] = Object.freeze([\n  { name: 'audit_repo', script: AUDIT_REPO_SCRIPT },\n  { name: 'multi_perspective_review', script: MULTI_PERSPECTIVE_REVIEW_SCRIPT },\n  { name: 'research', script: RESEARCH_SCRIPT },\n]);\n\nexport { AUDIT_REPO_SCRIPT, MULTI_PERSPECTIVE_REVIEW_SCRIPT, RESEARCH_SCRIPT };\n"],"mappings":";;;;;;;;;;AAgBA,MAAa,oBAAgD,OAAO,OAAO;CACzE;EAAE,MAAM;EAAc,QAAQ;EAAmB;CACjD;EAAE,MAAM;EAA4B,QAAQ;EAAiC;CAC7E;EAAE,MAAM;EAAY,QAAQ;EAAiB;CAC9C,CAAC"}

package/dist/src/agent/workflow/builtins/multi-perspective-review.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Built-in workflow: `multi_perspective_review`
+ *
+ * Reviews a target (file, PR, design doc, plan — passed via args.target) from
+ * several independent perspectives, then asks an adversarial judge to decide
+ * what would actually break in practice. Useful for sanity-checking decisions
+ * before they ship.
+ */
+export declare const MULTI_PERSPECTIVE_REVIEW_SCRIPT = "export const meta = {\n  name: 'multi_perspective_review',\n  description: 'Review a target from N independent perspectives, then adversarially judge what would actually break.',\n  whenToUse: 'User wants a stress-test of a design, plan, PR, or proposal before committing to it.',\n  phases: [\n    { title: 'Lenses' },\n    { title: 'Adversarial' },\n    { title: 'Synthesize' },\n  ],\n}\n\nconst target = args && typeof args === 'object' && args.target\n  ? String(args.target)\n  : 'No explicit target was provided. Treat the currently focused file or recent context as the target.'\n\nconst LENSES = [\n  { name: 'User',         angle: 'How a real user experiences this. Friction, confusion, surprise paths, accessibility.' },\n  { name: 'Operator',     angle: 'How an on-call engineer experiences this in production. Failure modes, observability, rollback.' },\n  { name: 'Skeptic',      angle: 'Hidden assumptions. What is being implied but not stated. What would break under load or weird input.' },\n  { name: 'Maintainer',   angle: 'Six-month-later view. Clarity, naming, layering, ease of changing nearby code.' },\n]\n\nphase('Lenses')\nconst lensViews = await parallel(\n  LENSES.map((l) => () =>\n    agent(\n      'Review the following target through the ' + l.name + ' lens.\\n' +\n        'Lens focus: ' + l.angle + '\\n\\n' +\n        'TARGET:\\n' + target + '\\n\\n' +\n        'Return 3\u20137 concrete observations. Each entry: title (5\u201310 words), why-it-matters (1 sentence), risk (low/med/high).',\n      {\n        label: l.name + ' lens',\n        schema: {\n          type: 'object',\n          properties: {\n            observations: {\n              type: 'array',\n              items: {\n                type: 'object',\n                properties: {\n                  title: { type: 'string' },\n                  why: { type: 'string' },\n                  risk: { type: 'string', enum: ['low', 'med', 'high'] },\n                },\n                required: ['title', 'why', 'risk'],\n              },\n            },\n          },\n          required: ['observations'],\n        },\n      },\n    ),\n  ),\n)\n\nphase('Adversarial')\nconst valid = lensViews.filter(Boolean)\nconst allObs = valid.flatMap((v, i) =>\n  (v?.observations ?? []).map((o) => ({ lens: LENSES[i].name, ...o })),\n)\n\nconst verdict = await agent(\n  'You are an adversarial judge. Given these multi-lens observations of a target, decide which would actually cause real harm if shipped as-is. ' +\n    'Default to refuted=true unless an observation has clear, mechanism-level evidence.\\n\\n' +\n    JSON.stringify(allObs, null, 2),\n  {\n    label: 'adversarial verdict',\n    schema: {\n      type: 'object',\n      properties: {\n        verdicts: {\n          type: 'array',\n          items: {\n            type: 'object',\n            properties: {\n              title: { type: 'string' },\n              lens: { type: 'string' },\n              realRisk: { type: 'boolean' },\n              reason: { type: 'string' },\n            },\n            required: ['title', 'lens', 'realRisk', 'reason'],\n          },\n        },\n      },\n      required: ['verdicts'],\n    },\n  },\n)\n\nphase('Synthesize')\nconst confirmed = (verdict?.verdicts ?? []).filter((v) => v.realRisk)\nreturn {\n  ok: true,\n  target,\n  observationCount: allObs.length,\n  confirmedRiskCount: confirmed.length,\n  topRisks: confirmed.slice(0, 10),\n  allVerdicts: verdict?.verdicts ?? [],\n}\n";

package/dist/src/agent/workflow/builtins/multi-perspective-review.js

@@ -0,0 +1,113 @@
+//#region src/agent/workflow/builtins/multi-perspective-review.ts
+/**
+* Built-in workflow: `multi_perspective_review`
+*
+* Reviews a target (file, PR, design doc, plan — passed via args.target) from
+* several independent perspectives, then asks an adversarial judge to decide
+* what would actually break in practice. Useful for sanity-checking decisions
+* before they ship.
+*/
+const MULTI_PERSPECTIVE_REVIEW_SCRIPT = `export const meta = {
+  name: 'multi_perspective_review',
+  description: 'Review a target from N independent perspectives, then adversarially judge what would actually break.',
+  whenToUse: 'User wants a stress-test of a design, plan, PR, or proposal before committing to it.',
+  phases: [
+    { title: 'Lenses' },
+    { title: 'Adversarial' },
+    { title: 'Synthesize' },
+  ],
+}
+
+const target = args && typeof args === 'object' && args.target
+  ? String(args.target)
+  : 'No explicit target was provided. Treat the currently focused file or recent context as the target.'
+
+const LENSES = [
+  { name: 'User',         angle: 'How a real user experiences this. Friction, confusion, surprise paths, accessibility.' },
+  { name: 'Operator',     angle: 'How an on-call engineer experiences this in production. Failure modes, observability, rollback.' },
+  { name: 'Skeptic',      angle: 'Hidden assumptions. What is being implied but not stated. What would break under load or weird input.' },
+  { name: 'Maintainer',   angle: 'Six-month-later view. Clarity, naming, layering, ease of changing nearby code.' },
+]
+
+phase('Lenses')
+const lensViews = await parallel(
+  LENSES.map((l) => () =>
+    agent(
+      'Review the following target through the ' + l.name + ' lens.\\n' +
+        'Lens focus: ' + l.angle + '\\n\\n' +
+        'TARGET:\\n' + target + '\\n\\n' +
+        'Return 3–7 concrete observations. Each entry: title (5–10 words), why-it-matters (1 sentence), risk (low/med/high).',
+      {
+        label: l.name + ' lens',
+        schema: {
+          type: 'object',
+          properties: {
+            observations: {
+              type: 'array',
+              items: {
+                type: 'object',
+                properties: {
+                  title: { type: 'string' },
+                  why: { type: 'string' },
+                  risk: { type: 'string', enum: ['low', 'med', 'high'] },
+                },
+                required: ['title', 'why', 'risk'],
+              },
+            },
+          },
+          required: ['observations'],
+        },
+      },
+    ),
+  ),
+)
+
+phase('Adversarial')
+const valid = lensViews.filter(Boolean)
+const allObs = valid.flatMap((v, i) =>
+  (v?.observations ?? []).map((o) => ({ lens: LENSES[i].name, ...o })),
+)
+
+const verdict = await agent(
+  'You are an adversarial judge. Given these multi-lens observations of a target, decide which would actually cause real harm if shipped as-is. ' +
+    'Default to refuted=true unless an observation has clear, mechanism-level evidence.\\n\\n' +
+    JSON.stringify(allObs, null, 2),
+  {
+    label: 'adversarial verdict',
+    schema: {
+      type: 'object',
+      properties: {
+        verdicts: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              title: { type: 'string' },
+              lens: { type: 'string' },
+              realRisk: { type: 'boolean' },
+              reason: { type: 'string' },
+            },
+            required: ['title', 'lens', 'realRisk', 'reason'],
+          },
+        },
+      },
+      required: ['verdicts'],
+    },
+  },
+)
+
+phase('Synthesize')
+const confirmed = (verdict?.verdicts ?? []).filter((v) => v.realRisk)
+return {
+  ok: true,
+  target,
+  observationCount: allObs.length,
+  confirmedRiskCount: confirmed.length,
+  topRisks: confirmed.slice(0, 10),
+  allVerdicts: verdict?.verdicts ?? [],
+}
+`;
+//#endregion
+export { MULTI_PERSPECTIVE_REVIEW_SCRIPT };
+
+//# sourceMappingURL=multi-perspective-review.js.map