@xopcai/xopc 0.0.84 → 0.0.85

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

@@ -0,0 +1 @@
+{"version":3,"file":"multi-perspective-review.js","names":[],"sources":["../../../../../src/agent/workflow/builtins/multi-perspective-review.ts"],"sourcesContent":["/**\n * Built-in workflow: `multi_perspective_review`\n *\n * Reviews a target (file, PR, design doc, plan — passed via args.target) from\n * several independent perspectives, then asks an adversarial judge to decide\n * what would actually break in practice. Useful for sanity-checking decisions\n * before they ship.\n */\n\nexport 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–7 concrete observations. Each entry: title (5–10 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`\n"],"mappings":";;;;;;;;;AASA,MAAa,kCAAkC"}

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

@@ -0,0 +1,9 @@
+/**
+ * Built-in workflow: `research`
+ *
+ * Multi-modal research sweep on a question (args.question). Fans out search /
+ * exploration / source-reading angles in parallel, then synthesises a cited
+ * report. Each angle is its own subagent so source reading does not pollute the
+ * parent context.
+ */
+export declare const RESEARCH_SCRIPT = "export const meta = {\n  name: 'research',\n  description: 'Multi-angle research on a question with parallel exploration and a cited synthesis.',\n  whenToUse: 'User asks a non-trivial research question that benefits from multiple search angles or source reads.',\n  phases: [\n    { title: 'Frame' },\n    { title: 'Sweep' },\n    { title: 'Synthesize' },\n  ],\n}\n\nconst question = args && typeof args === 'object' && args.question\n  ? String(args.question)\n  : 'No explicit question supplied; infer from the most recent user turn.'\n\nphase('Frame')\nconst frame = await agent(\n  'Frame this research question. Return 3\u20135 distinct angles worth investigating, plus the single most decisive sub-question for each. Be concrete.\\n\\nQUESTION:\\n' +\n    question,\n  {\n    label: 'framing',\n    schema: {\n      type: 'object',\n      properties: {\n        angles: {\n          type: 'array',\n          items: {\n            type: 'object',\n            properties: {\n              title: { type: 'string' },\n              key_question: { type: 'string' },\n            },\n            required: ['title', 'key_question'],\n          },\n        },\n      },\n      required: ['angles'],\n    },\n  },\n)\n\nif (!frame || !frame.angles?.length) {\n  return { ok: false, reason: 'framing failed', question }\n}\n\nphase('Sweep')\nconst angleReports = await parallel(\n  frame.angles.map((a) => () =>\n    agent(\n      'Investigate this angle. Use search and source-read tools liberally. Distinguish what you can confirm from what is conjecture.\\n\\n' +\n        'ANGLE: ' + a.title + '\\n' +\n        'KEY QUESTION: ' + a.key_question + '\\n\\n' +\n        'Return: 3\u20136 grounded findings (each with a 1-line claim and a source URL or file path), plus the strongest counter-evidence.',\n      {\n        label: a.title,\n        schema: {\n          type: 'object',\n          properties: {\n            findings: {\n              type: 'array',\n              items: {\n                type: 'object',\n                properties: {\n                  claim: { type: 'string' },\n                  source: { type: 'string' },\n                  confidence: { type: 'string', enum: ['low', 'med', 'high'] },\n                },\n                required: ['claim', 'source', 'confidence'],\n              },\n            },\n            counterEvidence: { type: 'string' },\n          },\n          required: ['findings'],\n        },\n      },\n    ),\n  ),\n)\n\nphase('Synthesize')\nconst live = angleReports.filter(Boolean)\nconst synthesis = await agent(\n  'Synthesize a cited research report from these angle-level findings. Drop unsupported or duplicate claims. Use the highest-confidence source per claim. ' +\n    'Return: an executive summary (max 5 sentences), a bullet list of top findings with inline source URLs, and one section listing open questions.\\n\\n' +\n    'QUESTION:\\n' + question + '\\n\\n' +\n    JSON.stringify({ angles: frame.angles, reports: live }, null, 2),\n  {\n    label: 'synthesis',\n    schema: {\n      type: 'object',\n      properties: {\n        executiveSummary: { type: 'string' },\n        topFindings: {\n          type: 'array',\n          items: {\n            type: 'object',\n            properties: {\n              claim: { type: 'string' },\n              source: { type: 'string' },\n            },\n            required: ['claim', 'source'],\n          },\n        },\n        openQuestions: { type: 'array', items: { type: 'string' } },\n      },\n      required: ['executiveSummary', 'topFindings'],\n    },\n  },\n)\n\nreturn {\n  ok: true,\n  question,\n  ...(synthesis ?? { executiveSummary: 'synthesis failed', topFindings: [] }),\n}\n";

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

@@ -0,0 +1,129 @@
+//#region src/agent/workflow/builtins/research.ts
+/**
+* Built-in workflow: `research`
+*
+* Multi-modal research sweep on a question (args.question). Fans out search /
+* exploration / source-reading angles in parallel, then synthesises a cited
+* report. Each angle is its own subagent so source reading does not pollute the
+* parent context.
+*/
+const RESEARCH_SCRIPT = `export const meta = {
+  name: 'research',
+  description: 'Multi-angle research on a question with parallel exploration and a cited synthesis.',
+  whenToUse: 'User asks a non-trivial research question that benefits from multiple search angles or source reads.',
+  phases: [
+    { title: 'Frame' },
+    { title: 'Sweep' },
+    { title: 'Synthesize' },
+  ],
+}
+
+const question = args && typeof args === 'object' && args.question
+  ? String(args.question)
+  : 'No explicit question supplied; infer from the most recent user turn.'
+
+phase('Frame')
+const frame = await agent(
+  'Frame this research question. Return 3–5 distinct angles worth investigating, plus the single most decisive sub-question for each. Be concrete.\\n\\nQUESTION:\\n' +
+    question,
+  {
+    label: 'framing',
+    schema: {
+      type: 'object',
+      properties: {
+        angles: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              title: { type: 'string' },
+              key_question: { type: 'string' },
+            },
+            required: ['title', 'key_question'],
+          },
+        },
+      },
+      required: ['angles'],
+    },
+  },
+)
+
+if (!frame || !frame.angles?.length) {
+  return { ok: false, reason: 'framing failed', question }
+}
+
+phase('Sweep')
+const angleReports = await parallel(
+  frame.angles.map((a) => () =>
+    agent(
+      'Investigate this angle. Use search and source-read tools liberally. Distinguish what you can confirm from what is conjecture.\\n\\n' +
+        'ANGLE: ' + a.title + '\\n' +
+        'KEY QUESTION: ' + a.key_question + '\\n\\n' +
+        'Return: 3–6 grounded findings (each with a 1-line claim and a source URL or file path), plus the strongest counter-evidence.',
+      {
+        label: a.title,
+        schema: {
+          type: 'object',
+          properties: {
+            findings: {
+              type: 'array',
+              items: {
+                type: 'object',
+                properties: {
+                  claim: { type: 'string' },
+                  source: { type: 'string' },
+                  confidence: { type: 'string', enum: ['low', 'med', 'high'] },
+                },
+                required: ['claim', 'source', 'confidence'],
+              },
+            },
+            counterEvidence: { type: 'string' },
+          },
+          required: ['findings'],
+        },
+      },
+    ),
+  ),
+)
+
+phase('Synthesize')
+const live = angleReports.filter(Boolean)
+const synthesis = await agent(
+  'Synthesize a cited research report from these angle-level findings. Drop unsupported or duplicate claims. Use the highest-confidence source per claim. ' +
+    'Return: an executive summary (max 5 sentences), a bullet list of top findings with inline source URLs, and one section listing open questions.\\n\\n' +
+    'QUESTION:\\n' + question + '\\n\\n' +
+    JSON.stringify({ angles: frame.angles, reports: live }, null, 2),
+  {
+    label: 'synthesis',
+    schema: {
+      type: 'object',
+      properties: {
+        executiveSummary: { type: 'string' },
+        topFindings: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              claim: { type: 'string' },
+              source: { type: 'string' },
+            },
+            required: ['claim', 'source'],
+          },
+        },
+        openQuestions: { type: 'array', items: { type: 'string' } },
+      },
+      required: ['executiveSummary', 'topFindings'],
+    },
+  },
+)
+
+return {
+  ok: true,
+  question,
+  ...(synthesis ?? { executiveSummary: 'synthesis failed', topFindings: [] }),
+}
+`;
+//#endregion
+export { RESEARCH_SCRIPT };
+
+//# sourceMappingURL=research.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"research.js","names":[],"sources":["../../../../../src/agent/workflow/builtins/research.ts"],"sourcesContent":["/**\n * Built-in workflow: `research`\n *\n * Multi-modal research sweep on a question (args.question). Fans out search /\n * exploration / source-reading angles in parallel, then synthesises a cited\n * report. Each angle is its own subagent so source reading does not pollute the\n * parent context.\n */\n\nexport const RESEARCH_SCRIPT = `export const meta = {\n  name: 'research',\n  description: 'Multi-angle research on a question with parallel exploration and a cited synthesis.',\n  whenToUse: 'User asks a non-trivial research question that benefits from multiple search angles or source reads.',\n  phases: [\n    { title: 'Frame' },\n    { title: 'Sweep' },\n    { title: 'Synthesize' },\n  ],\n}\n\nconst question = args && typeof args === 'object' && args.question\n  ? String(args.question)\n  : 'No explicit question supplied; infer from the most recent user turn.'\n\nphase('Frame')\nconst frame = await agent(\n  'Frame this research question. Return 3–5 distinct angles worth investigating, plus the single most decisive sub-question for each. Be concrete.\\\\n\\\\nQUESTION:\\\\n' +\n    question,\n  {\n    label: 'framing',\n    schema: {\n      type: 'object',\n      properties: {\n        angles: {\n          type: 'array',\n          items: {\n            type: 'object',\n            properties: {\n              title: { type: 'string' },\n              key_question: { type: 'string' },\n            },\n            required: ['title', 'key_question'],\n          },\n        },\n      },\n      required: ['angles'],\n    },\n  },\n)\n\nif (!frame || !frame.angles?.length) {\n  return { ok: false, reason: 'framing failed', question }\n}\n\nphase('Sweep')\nconst angleReports = await parallel(\n  frame.angles.map((a) => () =>\n    agent(\n      'Investigate this angle. Use search and source-read tools liberally. Distinguish what you can confirm from what is conjecture.\\\\n\\\\n' +\n        'ANGLE: ' + a.title + '\\\\n' +\n        'KEY QUESTION: ' + a.key_question + '\\\\n\\\\n' +\n        'Return: 3–6 grounded findings (each with a 1-line claim and a source URL or file path), plus the strongest counter-evidence.',\n      {\n        label: a.title,\n        schema: {\n          type: 'object',\n          properties: {\n            findings: {\n              type: 'array',\n              items: {\n                type: 'object',\n                properties: {\n                  claim: { type: 'string' },\n                  source: { type: 'string' },\n                  confidence: { type: 'string', enum: ['low', 'med', 'high'] },\n                },\n                required: ['claim', 'source', 'confidence'],\n              },\n            },\n            counterEvidence: { type: 'string' },\n          },\n          required: ['findings'],\n        },\n      },\n    ),\n  ),\n)\n\nphase('Synthesize')\nconst live = angleReports.filter(Boolean)\nconst synthesis = await agent(\n  'Synthesize a cited research report from these angle-level findings. Drop unsupported or duplicate claims. Use the highest-confidence source per claim. ' +\n    'Return: an executive summary (max 5 sentences), a bullet list of top findings with inline source URLs, and one section listing open questions.\\\\n\\\\n' +\n    'QUESTION:\\\\n' + question + '\\\\n\\\\n' +\n    JSON.stringify({ angles: frame.angles, reports: live }, null, 2),\n  {\n    label: 'synthesis',\n    schema: {\n      type: 'object',\n      properties: {\n        executiveSummary: { type: 'string' },\n        topFindings: {\n          type: 'array',\n          items: {\n            type: 'object',\n            properties: {\n              claim: { type: 'string' },\n              source: { type: 'string' },\n            },\n            required: ['claim', 'source'],\n          },\n        },\n        openQuestions: { type: 'array', items: { type: 'string' } },\n      },\n      required: ['executiveSummary', 'topFindings'],\n    },\n  },\n)\n\nreturn {\n  ok: true,\n  question,\n  ...(synthesis ?? { executiveSummary: 'synthesis failed', topFindings: [] }),\n}\n`\n"],"mappings":";;;;;;;;;AASA,MAAa,kBAAkB"}

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

@@ -0,0 +1,51 @@
+/**
+ * Catalog for named workflows.
+ *
+ * Resolution order (built-ins are starting points, user workflows win):
+ *   1. `~/.xopc/workflows/<name>.js` (or `<name>.workflow.js`)
+ *   2. {@link BUILTIN_WORKFLOWS}
+ *
+ * The user dir is discovered via {@link resolveStateDir}, so `XOPC_STATE_DIR`
+ * overrides apply automatically (matches how skills / extensions are wired).
+ *
+ * Listing is filesystem-cheap (single `readdir`) and runs synchronously — the
+ * `/workflows` slash command is interactive and should return immediately.
+ *
+ * Validation: on load we re-parse the script to make sure `meta.name` matches
+ * the filename. This prevents copy-pasted scripts from being silently
+ * mis-addressed when invoked by name.
+ */
+import type { WorkflowMeta } from './types.js';
+export type WorkflowSource = 'user' | 'builtin';
+export interface CatalogEntry {
+    name: string;
+    source: WorkflowSource;
+    /** Absolute path for user entries; null for built-ins (in-memory). */
+    path: string | null;
+    description: string;
+    whenToUse?: string;
+}
+export interface LoadedWorkflow {
+    name: string;
+    source: WorkflowSource;
+    script: string;
+    meta: WorkflowMeta;
+    path: string | null;
+}
+export interface WorkflowCatalog {
+    list(): CatalogEntry[];
+    /** Load a named workflow. Throws if missing or meta.name disagrees with filename. */
+    load(name: string): LoadedWorkflow;
+    /** Save a script as a user workflow. Throws if the script fails to parse. */
+    save(name: string, script: string): {
+        path: string;
+    };
+    /** Remove a user workflow. No-op if absent. Built-ins are never removed. */
+    remove(name: string): boolean;
+    /** Absolute path to the user workflows directory (created lazily on save). */
+    userDir: string;
+}
+export declare function createWorkflowCatalog(opts?: {
+    userDir?: string;
+}): WorkflowCatalog;
+export declare function defaultUserDir(): string;

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

@@ -0,0 +1,155 @@
+import { init_paths_state, resolveStateDir } from "../../config/paths-state.js";
+import { BUILTIN_WORKFLOWS } from "./builtins/index.js";
+import { parseWorkflowScript } from "./parser.js";
+import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+//#region src/agent/workflow/catalog.ts
+/**
+* Catalog for named workflows.
+*
+* Resolution order (built-ins are starting points, user workflows win):
+*   1. `~/.xopc/workflows/<name>.js` (or `<name>.workflow.js`)
+*   2. {@link BUILTIN_WORKFLOWS}
+*
+* The user dir is discovered via {@link resolveStateDir}, so `XOPC_STATE_DIR`
+* overrides apply automatically (matches how skills / extensions are wired).
+*
+* Listing is filesystem-cheap (single `readdir`) and runs synchronously — the
+* `/workflows` slash command is interactive and should return immediately.
+*
+* Validation: on load we re-parse the script to make sure `meta.name` matches
+* the filename. This prevents copy-pasted scripts from being silently
+* mis-addressed when invoked by name.
+*/
+init_paths_state();
+const NAME_RE = /^[a-z][a-z0-9_-]*$/;
+function createWorkflowCatalog(opts = {}) {
+	const userDir = opts.userDir ?? defaultUserDir();
+	const list = () => {
+		const entries = /* @__PURE__ */ new Map();
+		for (const b of BUILTIN_WORKFLOWS) {
+			const meta = safeMeta(b.script);
+			entries.set(b.name, {
+				name: b.name,
+				source: "builtin",
+				path: null,
+				description: meta?.description ?? "(unparseable)",
+				whenToUse: meta?.whenToUse
+			});
+		}
+		for (const file of safeListUserFiles(userDir)) {
+			const name = stripExt(file);
+			if (!isValidName(name)) continue;
+			const full = join(userDir, file);
+			const meta = safeMeta(readScript(full));
+			entries.set(name, {
+				name,
+				source: "user",
+				path: full,
+				description: meta?.description ?? "(unparseable)",
+				whenToUse: meta?.whenToUse
+			});
+		}
+		return [...entries.values()].sort((a, b) => a.name.localeCompare(b.name));
+	};
+	const load = (name) => {
+		requireValidName(name);
+		const userPath = findUserPath(userDir, name);
+		if (userPath) {
+			const script = readScript(userPath);
+			const { meta } = parseWorkflowScript(script);
+			ensureMetaNameMatches(meta, name, userPath);
+			return {
+				name,
+				source: "user",
+				script,
+				meta,
+				path: userPath
+			};
+		}
+		const builtin = BUILTIN_WORKFLOWS.find((b) => b.name === name);
+		if (builtin) {
+			const { meta } = parseWorkflowScript(builtin.script);
+			ensureMetaNameMatches(meta, name, "<builtin>");
+			return {
+				name,
+				source: "builtin",
+				script: builtin.script,
+				meta,
+				path: null
+			};
+		}
+		throw new Error(`workflow not found: ${name}. Drop a script at ${join(userDir, `${name}.js`)} or pick one of: ${list().map((e) => e.name).join(", ")}`);
+	};
+	const save = (name, script) => {
+		requireValidName(name);
+		const { meta } = parseWorkflowScript(script);
+		if (meta.name !== name) throw new Error(`meta.name "${meta.name}" does not match save name "${name}". Adjust one to match the other.`);
+		if (!existsSync(userDir)) mkdirSync(userDir, { recursive: true });
+		const path = join(userDir, `${name}.js`);
+		writeFileSync(path, normalizeNewlines(script), "utf-8");
+		return { path };
+	};
+	const remove = (name) => {
+		requireValidName(name);
+		const userPath = findUserPath(userDir, name);
+		if (!userPath) return false;
+		unlinkSync(userPath);
+		return true;
+	};
+	return {
+		list,
+		load,
+		save,
+		remove,
+		userDir
+	};
+}
+function defaultUserDir() {
+	return join(resolveStateDir(), "workflows");
+}
+function safeListUserFiles(dir) {
+	try {
+		if (!existsSync(dir)) return [];
+		if (!statSync(dir).isDirectory()) return [];
+		return readdirSync(dir).filter((f) => /\.(js|workflow\.js)$/i.test(f));
+	} catch {
+		return [];
+	}
+}
+function findUserPath(dir, name) {
+	for (const candidate of [`${name}.js`, `${name}.workflow.js`]) {
+		const full = join(dir, candidate);
+		if (existsSync(full)) return full;
+	}
+	return null;
+}
+function readScript(path) {
+	return readFileSync(path, "utf-8");
+}
+function safeMeta(script) {
+	try {
+		return parseWorkflowScript(script).meta;
+	} catch {
+		return null;
+	}
+}
+function stripExt(filename) {
+	return filename.replace(/\.workflow\.js$/i, "").replace(/\.js$/i, "");
+}
+function isValidName(name) {
+	return NAME_RE.test(name);
+}
+function requireValidName(name) {
+	if (!isValidName(name)) throw new Error(`invalid workflow name "${name}". Use lowercase snake_case, e.g. "audit_repo".`);
+}
+function ensureMetaNameMatches(meta, name, locator) {
+	if (meta.name !== name) throw new Error(`workflow ${locator}: meta.name "${meta.name}" disagrees with addressable name "${name}". Rename the file or the meta.name to match.`);
+}
+function normalizeNewlines(s) {
+	return s.endsWith("\n") ? s : `${s}\n`;
+}
+//#endregion
+export { createWorkflowCatalog, defaultUserDir };
+
+//# sourceMappingURL=catalog.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","names":[],"sources":["../../../../src/agent/workflow/catalog.ts"],"sourcesContent":["/**\n * Catalog for named workflows.\n *\n * Resolution order (built-ins are starting points, user workflows win):\n *   1. `~/.xopc/workflows/<name>.js` (or `<name>.workflow.js`)\n *   2. {@link BUILTIN_WORKFLOWS}\n *\n * The user dir is discovered via {@link resolveStateDir}, so `XOPC_STATE_DIR`\n * overrides apply automatically (matches how skills / extensions are wired).\n *\n * Listing is filesystem-cheap (single `readdir`) and runs synchronously — the\n * `/workflows` slash command is interactive and should return immediately.\n *\n * Validation: on load we re-parse the script to make sure `meta.name` matches\n * the filename. This prevents copy-pasted scripts from being silently\n * mis-addressed when invoked by name.\n */\n\nimport {\n  existsSync,\n  mkdirSync,\n  readdirSync,\n  readFileSync,\n  statSync,\n  unlinkSync,\n  writeFileSync,\n} from 'node:fs';\nimport { join } from 'node:path';\n\nimport { resolveStateDir } from '../../config/paths-state.js';\n\nimport { BUILTIN_WORKFLOWS } from './builtins/index.js';\nimport { parseWorkflowScript } from './parser.js';\nimport type { WorkflowMeta } from './types.js';\n\nexport type WorkflowSource = 'user' | 'builtin';\n\nexport interface CatalogEntry {\n  name: string;\n  source: WorkflowSource;\n  /** Absolute path for user entries; null for built-ins (in-memory). */\n  path: string | null;\n  description: string;\n  whenToUse?: string;\n}\n\nexport interface LoadedWorkflow {\n  name: string;\n  source: WorkflowSource;\n  script: string;\n  meta: WorkflowMeta;\n  path: string | null;\n}\n\nexport interface WorkflowCatalog {\n  list(): CatalogEntry[];\n  /** Load a named workflow. Throws if missing or meta.name disagrees with filename. */\n  load(name: string): LoadedWorkflow;\n  /** Save a script as a user workflow. Throws if the script fails to parse. */\n  save(name: string, script: string): { path: string };\n  /** Remove a user workflow. No-op if absent. Built-ins are never removed. */\n  remove(name: string): boolean;\n  /** Absolute path to the user workflows directory (created lazily on save). */\n  userDir: string;\n}\n\nconst NAME_RE = /^[a-z][a-z0-9_-]*$/;\n\nexport function createWorkflowCatalog(opts: { userDir?: string } = {}): WorkflowCatalog {\n  const userDir = opts.userDir ?? defaultUserDir();\n\n  const list = (): CatalogEntry[] => {\n    const entries = new Map<string, CatalogEntry>();\n    for (const b of BUILTIN_WORKFLOWS) {\n      const meta = safeMeta(b.script);\n      entries.set(b.name, {\n        name: b.name,\n        source: 'builtin',\n        path: null,\n        description: meta?.description ?? '(unparseable)',\n        whenToUse: meta?.whenToUse,\n      });\n    }\n    for (const file of safeListUserFiles(userDir)) {\n      const name = stripExt(file);\n      if (!isValidName(name)) continue;\n      const full = join(userDir, file);\n      const meta = safeMeta(readScript(full));\n      // User wins on collision.\n      entries.set(name, {\n        name,\n        source: 'user',\n        path: full,\n        description: meta?.description ?? '(unparseable)',\n        whenToUse: meta?.whenToUse,\n      });\n    }\n    return [...entries.values()].sort((a, b) => a.name.localeCompare(b.name));\n  };\n\n  const load = (name: string): LoadedWorkflow => {\n    requireValidName(name);\n    const userPath = findUserPath(userDir, name);\n    if (userPath) {\n      const script = readScript(userPath);\n      const { meta } = parseWorkflowScript(script);\n      ensureMetaNameMatches(meta, name, userPath);\n      return { name, source: 'user', script, meta, path: userPath };\n    }\n    const builtin = BUILTIN_WORKFLOWS.find((b) => b.name === name);\n    if (builtin) {\n      const { meta } = parseWorkflowScript(builtin.script);\n      ensureMetaNameMatches(meta, name, '<builtin>');\n      return { name, source: 'builtin', script: builtin.script, meta, path: null };\n    }\n    throw new Error(\n      `workflow not found: ${name}. Drop a script at ${join(userDir, `${name}.js`)} or pick one of: ${list()\n        .map((e) => e.name)\n        .join(', ')}`,\n    );\n  };\n\n  const save = (name: string, script: string): { path: string } => {\n    requireValidName(name);\n    const { meta } = parseWorkflowScript(script);\n    if (meta.name !== name) {\n      throw new Error(\n        `meta.name \"${meta.name}\" does not match save name \"${name}\". Adjust one to match the other.`,\n      );\n    }\n    if (!existsSync(userDir)) {\n      mkdirSync(userDir, { recursive: true });\n    }\n    const path = join(userDir, `${name}.js`);\n    writeFileSync(path, normalizeNewlines(script), 'utf-8');\n    return { path };\n  };\n\n  const remove = (name: string): boolean => {\n    requireValidName(name);\n    const userPath = findUserPath(userDir, name);\n    if (!userPath) return false;\n    unlinkSync(userPath);\n    return true;\n  };\n\n  return { list, load, save, remove, userDir };\n}\n\n// ---------------------------------------------------------------------------\n\nexport function defaultUserDir(): string {\n  return join(resolveStateDir(), 'workflows');\n}\n\nfunction safeListUserFiles(dir: string): string[] {\n  try {\n    if (!existsSync(dir)) return [];\n    const st = statSync(dir);\n    if (!st.isDirectory()) return [];\n    return readdirSync(dir).filter((f) => /\\.(js|workflow\\.js)$/i.test(f));\n  } catch {\n    return [];\n  }\n}\n\nfunction findUserPath(dir: string, name: string): string | null {\n  for (const candidate of [`${name}.js`, `${name}.workflow.js`]) {\n    const full = join(dir, candidate);\n    if (existsSync(full)) return full;\n  }\n  return null;\n}\n\nfunction readScript(path: string): string {\n  return readFileSync(path, 'utf-8');\n}\n\nfunction safeMeta(script: string): WorkflowMeta | null {\n  try {\n    return parseWorkflowScript(script).meta;\n  } catch {\n    return null;\n  }\n}\n\nfunction stripExt(filename: string): string {\n  return filename.replace(/\\.workflow\\.js$/i, '').replace(/\\.js$/i, '');\n}\n\nfunction isValidName(name: string): boolean {\n  return NAME_RE.test(name);\n}\n\nfunction requireValidName(name: string): void {\n  if (!isValidName(name)) {\n    throw new Error(`invalid workflow name \"${name}\". Use lowercase snake_case, e.g. \"audit_repo\".`);\n  }\n}\n\nfunction ensureMetaNameMatches(meta: WorkflowMeta, name: string, locator: string): void {\n  if (meta.name !== name) {\n    throw new Error(\n      `workflow ${locator}: meta.name \"${meta.name}\" disagrees with addressable name \"${name}\". ` +\n        'Rename the file or the meta.name to match.',\n    );\n  }\n}\n\nfunction normalizeNewlines(s: string): string {\n  return s.endsWith('\\n') ? s : `${s}\\n`;\n}\n"],"mappings":"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"}

package/dist/src/agent/workflow/channel-capability.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Channel-side contract used by {@link WorkflowProgressBroker} to deliver
+ * workflow progress to a specific messaging surface (Telegram, Feishu, …).
+ *
+ * Why a capability instead of a hook on `ChannelPlugin`?
+ *   - Optional opt-in: channels register themselves at boot; no plugin
+ *     changes for surfaces that don't ship progress (e.g. SMS).
+ *   - Per-channel sane defaults baked in (throttle, mode) — the broker
+ *     reads these and lets `channels.<id>.workflowProgress` in config
+ *     override per deployment.
+ *   - Decouples the broker from the {@link ChannelPlugin} interface so
+ *     adding new channels never grows broker imports.
+ */
+export type WorkflowProgressMode = 
+/** Edit a single message in place (Telegram, Feishu). */
+'edit'
+/** Append a new message on each key event (WeChat — can't edit). */
+ | 'append'
+/** No mid-run updates; final-only message at completion. */
+ | 'final-only';
+export interface WorkflowProgressPostInput {
+    /** Routing key for the run — channel uses it to resolve the destination chat. */
+    sessionKey: string;
+    /** Pre-rendered progress text (already includes header / phases / logs). */
+    text: string;
+    /**
+     * Message id returned by the previous `postProgress` for the same run, when
+     * editing in place. `undefined` for the first message of a run, or always
+     * for `append` / `final-only` modes.
+     */
+    previousMessageId?: string;
+    /**
+     * `true` for the final completion message (sent right after `tool_end`).
+     * Useful for channels that want to bypass their own rate limiting for the
+     * last update (so users always see the conclusion).
+     */
+    isFinal: boolean;
+    /**
+     * The effective rendering mode for this dispatch — broker resolves it from
+     * the capability's `defaultMode` plus any `channels.<id>.workflowProgress.mode`
+     * override. Capabilities can use this to adjust message shape (e.g. WeChat
+     * prefixes mid-run `append` messages with "▾ progress" so the user can tell
+     * them apart from the final summary).
+     *
+     * Optional for backwards compatibility with hand-rolled callers and unit
+     * tests; the broker always provides it. Capabilities that consume the field
+     * should default to `'edit'` when missing.
+     */
+    mode?: WorkflowProgressMode;
+}
+export interface WorkflowProgressPostResult {
+    /** New / unchanged message id to use as `previousMessageId` next time. */
+    messageId: string;
+}
+export interface ChannelProgressCapability {
+    /** Stable channel id matching `channels.<id>` in config (e.g. `telegram`). */
+    readonly channelId: string;
+    /** True when the underlying platform exposes editMessage semantics. */
+    readonly supportsEdit: boolean;
+    /** Sane default throttle (ms) for this surface; respects platform limits. */
+    readonly defaultThrottleMs: number;
+    /** Sane default mode for this surface. */
+    readonly defaultMode: WorkflowProgressMode;
+    /**
+     * Deliver one progress update.
+     *
+     * Capability is responsible for:
+     * - Resolving `sessionKey` → platform chat/thread id (channel-specific).
+     * - Encoding the text payload (markdown / plain / HTML, line breaks).
+     * - Calling editMessageText vs sendMessage based on `previousMessageId`.
+     * - Honouring platform rate limits (429 retry-after, etc.).
+     *
+     * Throw on hard failure; the broker logs and drops the update.
+     */
+    postProgress(input: WorkflowProgressPostInput): Promise<WorkflowProgressPostResult>;
+}

package/dist/src/agent/workflow/channel-capability.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,11 @@
+export { BUILTIN_WORKFLOWS, type BuiltinWorkflow } from './builtins/index.js';
+export { createWorkflowCatalog, defaultUserDir, type CatalogEntry, type LoadedWorkflow, type WorkflowCatalog, type WorkflowSource, } from './catalog.js';
+export { getLastWorkflowMemory, _resetLastWorkflowMemoryForTests, type LastWorkflowEntry, type LastWorkflowMemory, } from './last-run-memory.js';
+export type { ChannelProgressCapability, WorkflowProgressMode, WorkflowProgressPostInput, WorkflowProgressPostResult, } from './channel-capability.js';
+export { parseWorkflowScript, type ParsedWorkflow } from './parser.js';
+export { WorkflowProgressBroker, getWorkflowProgressBroker, _resetWorkflowProgressBrokerForTests, type BrokerListenerHandle, type SessionBusLike, } from './progress-broker.js';
+export { emptySnapshotFor, runWorkflow, type RunWorkflowDeps, } from './runtime.js';
+export { createWorkflowSnapshot, previewValue, recomputeCounts, renderWorkflowText, type RenderOptions, } from './snapshot.js';
+export { createStructuredOutputTool, STRUCTURED_OUTPUT_TOOL_NAME, type CreateStructuredOutputToolOptions, type StructuredOutputCapture, } from './structured-output-tool.js';
+export { DelegateSubagentRunner, type DelegateSubagentRunnerDeps, } from './subagent-runner.js';
+export type { AgentScriptOptions, JsonSchema, SubagentRunner, SubagentRunOptions, WorkflowAgentSnapshot, WorkflowAgentStatus, WorkflowMeta, WorkflowMetaPhase, WorkflowRunOptions, WorkflowRunResult, WorkflowSnapshot, } from './types.js';

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

@@ -0,0 +1,10 @@
+import { BUILTIN_WORKFLOWS } from "./builtins/index.js";
+import { parseWorkflowScript } from "./parser.js";
+import { createWorkflowCatalog, defaultUserDir } from "./catalog.js";
+import { _resetLastWorkflowMemoryForTests, getLastWorkflowMemory } from "./last-run-memory.js";
+import { createWorkflowSnapshot, previewValue, recomputeCounts, renderWorkflowText } from "./snapshot.js";
+import { WorkflowProgressBroker, _resetWorkflowProgressBrokerForTests, getWorkflowProgressBroker } from "./progress-broker.js";
+import { emptySnapshotFor, runWorkflow } from "./runtime.js";
+import { STRUCTURED_OUTPUT_TOOL_NAME, createStructuredOutputTool } from "./structured-output-tool.js";
+import { DelegateSubagentRunner } from "./subagent-runner.js";
+export { BUILTIN_WORKFLOWS, DelegateSubagentRunner, STRUCTURED_OUTPUT_TOOL_NAME, WorkflowProgressBroker, _resetLastWorkflowMemoryForTests, _resetWorkflowProgressBrokerForTests, createStructuredOutputTool, createWorkflowCatalog, createWorkflowSnapshot, defaultUserDir, emptySnapshotFor, getLastWorkflowMemory, getWorkflowProgressBroker, parseWorkflowScript, previewValue, recomputeCounts, renderWorkflowText, runWorkflow };

package/dist/src/agent/workflow/last-run-memory.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Per-session memory of the most recent workflow script that ran successfully.
+ *
+ * Purpose: enable `/workflow save <name>` — the user sees a workflow run,
+ * likes it, types `/workflow save audit_repo_strict`, and the model-generated
+ * script lands in `~/.xopc/workflows/`.
+ *
+ * Scope decision (KISS):
+ * - In-memory only, keyed by sessionKey. Cleared on process restart. OPC is
+ *   long-lived per session, so the practical window is "from when the user
+ *   ran the workflow until they save it" — minutes, not days. Persisting
+ *   across restarts would require either session-store coupling or a separate
+ *   sidecar file, both bigger than the value.
+ * - Records on EVERY successful workflow tool execution, including runs by
+ *   name (so users can re-save a slightly modified built-in too).
+ * - Bounded by a small LRU so a runaway never grows the heap.
+ */
+export interface LastWorkflowEntry {
+    /** Raw workflow script as the runtime saw it (post-fence-strip, pre-parse). */
+    script: string;
+    /** meta.name from the script (used to default a save target). */
+    metaName: string;
+    /** Where the script came from on this run — for save-time UX hints. */
+    source: 'name' | 'script';
+    /** ms since epoch when recorded — UI uses this for "ran 2 min ago". */
+    recordedAt: number;
+}
+declare class LastWorkflowMemoryImpl {
+    private readonly maxEntries;
+    private readonly entries;
+    constructor(maxEntries?: number);
+    record(sessionKey: string | undefined, entry: LastWorkflowEntry): void;
+    get(sessionKey: string | undefined): LastWorkflowEntry | undefined;
+    clear(sessionKey?: string): void;
+    /** Visible for tests; do not consume from production code. */
+    _size(): number;
+}
+export type LastWorkflowMemory = LastWorkflowMemoryImpl;
+export declare function getLastWorkflowMemory(): LastWorkflowMemoryImpl;
+/** Reset the singleton (tests only). */
+export declare function _resetLastWorkflowMemoryForTests(): void;
+export {};

package/dist/src/agent/workflow/last-run-memory.js

@@ -0,0 +1,60 @@
+//#region src/agent/workflow/last-run-memory.ts
+/**
+* Per-session memory of the most recent workflow script that ran successfully.
+*
+* Purpose: enable `/workflow save <name>` — the user sees a workflow run,
+* likes it, types `/workflow save audit_repo_strict`, and the model-generated
+* script lands in `~/.xopc/workflows/`.
+*
+* Scope decision (KISS):
+* - In-memory only, keyed by sessionKey. Cleared on process restart. OPC is
+*   long-lived per session, so the practical window is "from when the user
+*   ran the workflow until they save it" — minutes, not days. Persisting
+*   across restarts would require either session-store coupling or a separate
+*   sidecar file, both bigger than the value.
+* - Records on EVERY successful workflow tool execution, including runs by
+*   name (so users can re-save a slightly modified built-in too).
+* - Bounded by a small LRU so a runaway never grows the heap.
+*/
+const DEFAULT_MAX_ENTRIES = 64;
+var LastWorkflowMemoryImpl = class {
+	entries = /* @__PURE__ */ new Map();
+	constructor(maxEntries = DEFAULT_MAX_ENTRIES) {
+		this.maxEntries = maxEntries;
+	}
+	record(sessionKey, entry) {
+		if (!sessionKey) return;
+		if (this.entries.has(sessionKey)) this.entries.delete(sessionKey);
+		this.entries.set(sessionKey, entry);
+		while (this.entries.size > this.maxEntries) {
+			const oldestKey = this.entries.keys().next().value;
+			if (oldestKey === void 0) break;
+			this.entries.delete(oldestKey);
+		}
+	}
+	get(sessionKey) {
+		if (!sessionKey) return void 0;
+		return this.entries.get(sessionKey);
+	}
+	clear(sessionKey) {
+		if (sessionKey === void 0) this.entries.clear();
+		else this.entries.delete(sessionKey);
+	}
+	/** Visible for tests; do not consume from production code. */
+	_size() {
+		return this.entries.size;
+	}
+};
+let singleton = null;
+function getLastWorkflowMemory() {
+	if (!singleton) singleton = new LastWorkflowMemoryImpl();
+	return singleton;
+}
+/** Reset the singleton (tests only). */
+function _resetLastWorkflowMemoryForTests() {
+	singleton = null;
+}
+//#endregion
+export { _resetLastWorkflowMemoryForTests, getLastWorkflowMemory };
+
+//# sourceMappingURL=last-run-memory.js.map

package/dist/src/agent/workflow/last-run-memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"last-run-memory.js","names":[],"sources":["../../../../src/agent/workflow/last-run-memory.ts"],"sourcesContent":["/**\n * Per-session memory of the most recent workflow script that ran successfully.\n *\n * Purpose: enable `/workflow save <name>` — the user sees a workflow run,\n * likes it, types `/workflow save audit_repo_strict`, and the model-generated\n * script lands in `~/.xopc/workflows/`.\n *\n * Scope decision (KISS):\n * - In-memory only, keyed by sessionKey. Cleared on process restart. OPC is\n *   long-lived per session, so the practical window is \"from when the user\n *   ran the workflow until they save it\" — minutes, not days. Persisting\n *   across restarts would require either session-store coupling or a separate\n *   sidecar file, both bigger than the value.\n * - Records on EVERY successful workflow tool execution, including runs by\n *   name (so users can re-save a slightly modified built-in too).\n * - Bounded by a small LRU so a runaway never grows the heap.\n */\n\nconst DEFAULT_MAX_ENTRIES = 64;\n\nexport interface LastWorkflowEntry {\n  /** Raw workflow script as the runtime saw it (post-fence-strip, pre-parse). */\n  script: string;\n  /** meta.name from the script (used to default a save target). */\n  metaName: string;\n  /** Where the script came from on this run — for save-time UX hints. */\n  source: 'name' | 'script';\n  /** ms since epoch when recorded — UI uses this for \"ran 2 min ago\". */\n  recordedAt: number;\n}\n\nclass LastWorkflowMemoryImpl {\n  private readonly entries = new Map<string, LastWorkflowEntry>();\n\n  constructor(private readonly maxEntries: number = DEFAULT_MAX_ENTRIES) {}\n\n  record(sessionKey: string | undefined, entry: LastWorkflowEntry): void {\n    if (!sessionKey) return;\n    // Move-to-end semantics: delete then set so iteration order = LRU.\n    if (this.entries.has(sessionKey)) this.entries.delete(sessionKey);\n    this.entries.set(sessionKey, entry);\n    while (this.entries.size > this.maxEntries) {\n      const oldestKey = this.entries.keys().next().value;\n      if (oldestKey === undefined) break;\n      this.entries.delete(oldestKey);\n    }\n  }\n\n  get(sessionKey: string | undefined): LastWorkflowEntry | undefined {\n    if (!sessionKey) return undefined;\n    return this.entries.get(sessionKey);\n  }\n\n  clear(sessionKey?: string): void {\n    if (sessionKey === undefined) this.entries.clear();\n    else this.entries.delete(sessionKey);\n  }\n\n  /** Visible for tests; do not consume from production code. */\n  _size(): number {\n    return this.entries.size;\n  }\n}\n\nexport type LastWorkflowMemory = LastWorkflowMemoryImpl;\n\nlet singleton: LastWorkflowMemoryImpl | null = null;\n\nexport function getLastWorkflowMemory(): LastWorkflowMemoryImpl {\n  if (!singleton) singleton = new LastWorkflowMemoryImpl();\n  return singleton;\n}\n\n/** Reset the singleton (tests only). */\nexport function _resetLastWorkflowMemoryForTests(): void {\n  singleton = null;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAkBA,MAAM,sBAAsB;AAa5B,IAAM,yBAAN,MAA6B;CAC3B,0BAA2B,IAAI,KAAgC;CAE/D,YAAY,aAAsC,qBAAqB;AAA1C,OAAA,aAAA;;CAE7B,OAAO,YAAgC,OAAgC;AACrE,MAAI,CAAC,WAAY;AAEjB,MAAI,KAAK,QAAQ,IAAI,WAAW,CAAE,MAAK,QAAQ,OAAO,WAAW;AACjE,OAAK,QAAQ,IAAI,YAAY,MAAM;AACnC,SAAO,KAAK,QAAQ,OAAO,KAAK,YAAY;GAC1C,MAAM,YAAY,KAAK,QAAQ,MAAM,CAAC,MAAM,CAAC;AAC7C,OAAI,cAAc,KAAA,EAAW;AAC7B,QAAK,QAAQ,OAAO,UAAU;;;CAIlC,IAAI,YAA+D;AACjE,MAAI,CAAC,WAAY,QAAO,KAAA;AACxB,SAAO,KAAK,QAAQ,IAAI,WAAW;;CAGrC,MAAM,YAA2B;AAC/B,MAAI,eAAe,KAAA,EAAW,MAAK,QAAQ,OAAO;MAC7C,MAAK,QAAQ,OAAO,WAAW;;;CAItC,QAAgB;AACd,SAAO,KAAK,QAAQ;;;AAMxB,IAAI,YAA2C;AAE/C,SAAgB,wBAAgD;AAC9D,KAAI,CAAC,UAAW,aAAY,IAAI,wBAAwB;AACxD,QAAO;;;AAIT,SAAgB,mCAAyC;AACvD,aAAY"}

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

@@ -0,0 +1,20 @@
+/**
+ * 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.
+ */
+import type { WorkflowMeta } from './types.js';
+export interface ParsedWorkflow {
+    meta: WorkflowMeta;
+    body: string;
+}
+export declare function parseWorkflowScript(script: string): ParsedWorkflow;