@xopcai/xopc 0.0.103 → 0.0.105

package/dist/src/agent/tools/skills-tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"skills-tools.js","names":[],"sources":["../../../../src/agent/tools/skills-tools.ts"],"sourcesContent":["import { readFileSync, statSync } from 'fs';\nimport { Type } from '@sinclair/typebox';\nimport type { AgentTool, AgentToolResult } from '@earendil-works/pi-agent-core';\n\nimport { resolveStateDir } from '../../config/paths.js';\nimport { createSkillConfigManager, isSkillEnabled } from '../skills/config.js';\nimport { resolveSkillReadablePath } from '../skills/skill-view-path.js';\nimport type { SkillManager } from '../skills/skill-manager.js';\nimport { truncateHead, formatSize, DEFAULT_MAX_BYTES } from './truncate.js';\n\nconst DEFAULT_MAX_LINES = 500;\nconst DEFAULT_MAX_SKILL_FILE_BYTES = 1_048_576;\n\nconst SkillsListSchema = Type.Object({\n  query: Type.Optional(\n    Type.String({\n      description: 'Optional case-insensitive substring filter on skill name and description',\n    }),\n  ),\n});\n\nconst SkillViewSchema = Type.Object({\n  name: Type.String({ description: 'Skill name (as in <available_skills> / skills_list)' }),\n  path: Type.Optional(\n    Type.String({\n      description:\n        'Relative path inside the skill dir: omit for SKILL.md, or e.g. references/doc.md (only references/, templates/, scripts/, assets/)',\n    }),\n  ),\n  limit: Type.Optional(\n    Type.Number({ description: 'Max lines to return (default 500, like read_file)' }),\n  ),\n});\n\nexport interface SkillsToolsDeps {\n  getSkillManager: () => SkillManager | undefined;\n  getSkillIndexingContext?: () =>\n    | { registeredToolNames: string[]; skillAllowlist?: string[] }\n    | undefined;\n  /** Register declared env var names for shell / tool passthrough (values never exposed). */\n  registerSkillEnvPassthrough?: (names: string[]) => void;\n}\n\nfunction maxSkillBytes(): number {\n  const lim = createSkillConfigManager(resolveStateDir()).load().limits?.maxSkillFileBytes;\n  return typeof lim === 'number' && lim > 0 ? lim : DEFAULT_MAX_SKILL_FILE_BYTES;\n}\n\nexport function createSkillsListTool(deps: SkillsToolsDeps): AgentTool {\n  return {\n    name: 'skills_list',\n    label: '📚 Skills',\n    description:\n      'List available skills (name and description only). Use skill_view(name) to load SKILL.md or a file under references/, templates/, scripts/, or assets/.',\n    parameters: SkillsListSchema,\n    async execute(\n      _toolCallId: string,\n      params: any,\n    ): Promise<AgentToolResult<{}>> {\n      const mgr = deps.getSkillManager();\n      if (!mgr) {\n        return {\n          content: [{ type: 'text', text: 'Skills are not available in this runtime context.' }],\n          details: {},\n        };\n      }\n\n      const idx = deps.getSkillIndexingContext?.();\n      let skills = mgr.getEnabledSkillsForAgentSession({\n        skillAllowlist: idx?.skillAllowlist,\n        registeredToolNames: idx?.registeredToolNames,\n      });\n      const q = (params as { query?: string }).query?.trim().toLowerCase();\n      if (q) {\n        skills = skills.filter(\n          (s) =>\n            s.name.toLowerCase().includes(q) || s.description.toLowerCase().includes(q),\n        );\n      }\n\n      const payload = {\n        skills: skills.map((s) => ({\n          name: s.name,\n          description: s.description,\n          source: s.source,\n        })),\n      };\n\n      return {\n        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],\n        details: {},\n      };\n    },\n  } as any;\n}\n\nexport function createSkillViewTool(deps: SkillsToolsDeps): AgentTool {\n  return {\n    name: 'skill_view',\n    label: '📖 Skill',\n    description:\n      'Load a skill\\'s SKILL.md (default) or a supporting file under references/, templates/, scripts/, or assets/.',\n    parameters: SkillViewSchema,\n    async execute(\n      _toolCallId: string,\n      params: any,\n    ): Promise<AgentToolResult<{}>> {\n      const p = params as { name: string; path?: string; limit?: number };\n      const mgr = deps.getSkillManager();\n      if (!mgr) {\n        return {\n          content: [{ type: 'text', text: 'Skills are not available in this runtime context.' }],\n          details: {},\n        };\n      }\n\n      const skill = mgr.findSkill(p.name.trim());\n      if (!skill) {\n        return {\n          content: [\n            {\n              type: 'text',\n              text: `Skill not found: \"${p.name}\". Use skills_list to see available names.`,\n            },\n          ],\n          details: {},\n        };\n      }\n\n      const skillsConfig = createSkillConfigManager(resolveStateDir()).load();\n      if (skill.disableModelInvocation || !isSkillEnabled(skill, skillsConfig)) {\n        return {\n          content: [{ type: 'text', text: `Skill \"${skill.name}\" is disabled or requirements are not met.` }],\n          details: {},\n        };\n      }\n\n      const idx = deps.getSkillIndexingContext?.();\n      const visible = mgr.getEnabledSkillsForAgentSession({\n        skillAllowlist: idx?.skillAllowlist,\n        registeredToolNames: idx?.registeredToolNames,\n      });\n      if (!visible.some((s) => s.name === skill.name)) {\n        return {\n          content: [\n            {\n              type: 'text',\n              text: `Skill \"${skill.name}\" is not available in this session (tool gating or allowlist).`,\n            },\n          ],\n          details: {},\n        };\n      }\n\n      const resolved = resolveSkillReadablePath(skill, p.path);\n      if (resolved.ok === false) {\n        return { content: [{ type: 'text', text: resolved.error }], details: {} };\n      }\n\n      const maxBytes = maxSkillBytes();\n      try {\n        const st = statSync(resolved.absolutePath);\n        if (st.size > maxBytes) {\n          return {\n            content: [\n              {\n                type: 'text',\n                text: `File too large: ${formatSize(st.size)} (limit ${formatSize(maxBytes)})`,\n              },\n            ],\n            details: {},\n          };\n        }\n\n        const raw = readFileSync(resolved.absolutePath, 'utf-8');\n        const truncation = truncateHead(raw, {\n          maxLines: p.limit ?? DEFAULT_MAX_LINES,\n          maxBytes: DEFAULT_MAX_BYTES,\n        });\n\n        let outputText = truncation.content;\n        if (truncation.truncated) {\n          if (truncation.firstLineExceedsLimit) {\n            outputText = `(Line exceeds ${formatSize(DEFAULT_MAX_BYTES)})`;\n          } else {\n            outputText += `\\n\\n[${truncation.outputLines}/${truncation.totalLines} lines]`;\n          }\n        }\n\n        const envNames = skill.requiredEnvVarNames;\n        if (envNames?.length && deps.registerSkillEnvPassthrough) {\n          deps.registerSkillEnvPassthrough(envNames);\n          const setNow = envNames.filter((k) => process.env[k] !== undefined).length;\n          outputText += `\\n\\n[skill env passthrough] Registered ${envNames.length} declared variable name(s) for this session; ${setNow} are currently defined in the process (values are never shown).`;\n        }\n\n        return { content: [{ type: 'text', text: outputText }], details: {} };\n      } catch (e) {\n        return {\n          content: [{ type: 'text', text: `Error: ${e instanceof Error ? e.message : String(e)}` }],\n          details: {},\n        };\n      }\n    },\n  } as any;\n}\n"],"mappings":"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"}
+{"version":3,"file":"skills-tools.js","names":[],"sources":["../../../../src/agent/tools/skills-tools.ts"],"sourcesContent":["import { readFileSync, statSync } from 'fs';\nimport { Type } from '@sinclair/typebox';\nimport type { AgentTool, AgentToolResult } from '@earendil-works/pi-agent-core';\n\nimport { resolveStateDir } from '../../config/paths.js';\nimport { createSkillConfigManager, isSkillEnabled, resolveSkillConfig } from '../skills/config.js';\nimport { resolveSkillReadablePath } from '../skills/skill-view-path.js';\nimport type { SkillManager } from '../skills/skill-manager.js';\nimport { truncateHead, formatSize, DEFAULT_MAX_BYTES } from './truncate.js';\n\nconst DEFAULT_MAX_LINES = 500;\nconst DEFAULT_MAX_SKILL_FILE_BYTES = 1_048_576;\n\nconst SkillsListSchema = Type.Object({\n  query: Type.Optional(\n    Type.String({\n      description: 'Optional case-insensitive substring filter on skill name and description',\n    }),\n  ),\n});\n\nconst SkillViewSchema = Type.Object({\n  name: Type.String({ description: 'Skill name (as in <available_skills> / skills_list)' }),\n  path: Type.Optional(\n    Type.String({\n      description:\n        'Relative path inside the skill dir: omit for SKILL.md, or e.g. references/doc.md (only references/, templates/, scripts/, assets/)',\n    }),\n  ),\n  limit: Type.Optional(\n    Type.Number({ description: 'Max lines to return (default 500, like read_file)' }),\n  ),\n});\n\nexport interface SkillsToolsDeps {\n  getSkillManager: () => SkillManager | undefined;\n  getSkillIndexingContext?: () =>\n    | { registeredToolNames: string[]; skillAllowlist?: string[] }\n    | undefined;\n  /** Register declared env var names for shell / tool passthrough (values never exposed). */\n  registerSkillEnvPassthrough?: (names: string[]) => void;\n}\n\nfunction maxSkillBytes(): number {\n  const lim = createSkillConfigManager(resolveStateDir()).load().limits?.maxSkillFileBytes;\n  return typeof lim === 'number' && lim > 0 ? lim : DEFAULT_MAX_SKILL_FILE_BYTES;\n}\n\nexport function createSkillsListTool(deps: SkillsToolsDeps): AgentTool {\n  return {\n    name: 'skills_list',\n    label: '📚 Skills',\n    description:\n      'List available skills (name and description only). Use skill_view(name) to load SKILL.md or a file under references/, templates/, scripts/, or assets/.',\n    parameters: SkillsListSchema,\n    async execute(\n      _toolCallId: string,\n      params: any,\n    ): Promise<AgentToolResult<{}>> {\n      const mgr = deps.getSkillManager();\n      if (!mgr) {\n        return {\n          content: [{ type: 'text', text: 'Skills are not available in this runtime context.' }],\n          details: {},\n        };\n      }\n\n      const idx = deps.getSkillIndexingContext?.();\n      let skills = mgr.getEnabledSkillsForAgentSession({\n        skillAllowlist: idx?.skillAllowlist,\n        registeredToolNames: idx?.registeredToolNames,\n      });\n      const q = (params as { query?: string }).query?.trim().toLowerCase();\n      if (q) {\n        skills = skills.filter(\n          (s) =>\n            s.name.toLowerCase().includes(q) || s.description.toLowerCase().includes(q),\n        );\n      }\n\n      const payload = {\n        skills: skills.map((s) => ({\n          name: s.name,\n          description: s.description,\n          source: s.source,\n        })),\n      };\n\n      return {\n        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],\n        details: {},\n      };\n    },\n  } as any;\n}\n\nexport function createSkillViewTool(deps: SkillsToolsDeps): AgentTool {\n  return {\n    name: 'skill_view',\n    label: '📖 Skill',\n    description:\n      'Load a skill\\'s SKILL.md (default) or a supporting file under references/, templates/, scripts/, or assets/.',\n    parameters: SkillViewSchema,\n    async execute(\n      _toolCallId: string,\n      params: any,\n    ): Promise<AgentToolResult<{}>> {\n      const p = params as { name: string; path?: string; limit?: number };\n      const mgr = deps.getSkillManager();\n      if (!mgr) {\n        return {\n          content: [{ type: 'text', text: 'Skills are not available in this runtime context.' }],\n          details: {},\n        };\n      }\n\n      const skill = mgr.findSkill(p.name.trim());\n      if (!skill) {\n        return {\n          content: [\n            {\n              type: 'text',\n              text: `Skill \"${p.name}\" was not found. It may not be installed. Open the Skills library to install it, or use skills_list to see available names.`,\n            },\n          ],\n          details: { errorCode: 'skill_not_found', skillName: p.name },\n        };\n      }\n\n      const skillsConfig = createSkillConfigManager(resolveStateDir()).load();\n      const skillConfig = resolveSkillConfig(skill, skillsConfig);\n      if (skillConfig.enabled === false) {\n        return {\n          content: [\n            {\n              type: 'text',\n              text: `Skill \"${skill.name}\" is installed but disabled. Enable it in Skills settings before using it.`,\n            },\n          ],\n          details: { errorCode: 'skill_disabled', skillName: skill.name },\n        };\n      }\n      if (skill.disableModelInvocation) {\n        return {\n          content: [{ type: 'text', text: `Skill \"${skill.name}\" is installed, but it is not available for model invocation.` }],\n          details: { errorCode: 'skill_model_invocation_disabled', skillName: skill.name },\n        };\n      }\n      if (!isSkillEnabled(skill, skillsConfig)) {\n        return {\n          content: [{ type: 'text', text: `Skill \"${skill.name}\" is installed, but its requirements are not met.` }],\n          details: { errorCode: 'skill_requirements_unmet', skillName: skill.name },\n        };\n      }\n\n      const idx = deps.getSkillIndexingContext?.();\n      const visible = mgr.getEnabledSkillsForAgentSession({\n        skillAllowlist: idx?.skillAllowlist,\n        registeredToolNames: idx?.registeredToolNames,\n      });\n      if (!visible.some((s) => s.name === skill.name)) {\n        return {\n          content: [\n            {\n              type: 'text',\n              text: `The current agent cannot use skill \"${skill.name}\". It is installed, but it is not in this agent's skill allowlist or is hidden by tool gating. Enable it in Agent settings → Skills before using it.`,\n            },\n          ],\n          details: { errorCode: 'skill_agent_denied', skillName: skill.name },\n        };\n      }\n\n      const resolved = resolveSkillReadablePath(skill, p.path);\n      if (resolved.ok === false) {\n        return { content: [{ type: 'text', text: resolved.error }], details: {} };\n      }\n\n      const maxBytes = maxSkillBytes();\n      try {\n        const st = statSync(resolved.absolutePath);\n        if (st.size > maxBytes) {\n          return {\n            content: [\n              {\n                type: 'text',\n                text: `File too large: ${formatSize(st.size)} (limit ${formatSize(maxBytes)})`,\n              },\n            ],\n            details: {},\n          };\n        }\n\n        const raw = readFileSync(resolved.absolutePath, 'utf-8');\n        const truncation = truncateHead(raw, {\n          maxLines: p.limit ?? DEFAULT_MAX_LINES,\n          maxBytes: DEFAULT_MAX_BYTES,\n        });\n\n        let outputText = truncation.content;\n        if (truncation.truncated) {\n          if (truncation.firstLineExceedsLimit) {\n            outputText = `(Line exceeds ${formatSize(DEFAULT_MAX_BYTES)})`;\n          } else {\n            outputText += `\\n\\n[${truncation.outputLines}/${truncation.totalLines} lines]`;\n          }\n        }\n\n        const envNames = skill.requiredEnvVarNames;\n        if (envNames?.length && deps.registerSkillEnvPassthrough) {\n          deps.registerSkillEnvPassthrough(envNames);\n          const setNow = envNames.filter((k) => process.env[k] !== undefined).length;\n          outputText += `\\n\\n[skill env passthrough] Registered ${envNames.length} declared variable name(s) for this session; ${setNow} are currently defined in the process (values are never shown).`;\n        }\n\n        return { content: [{ type: 'text', text: outputText }], details: {} };\n      } catch (e) {\n        return {\n          content: [{ type: 'text', text: `Error: ${e instanceof Error ? e.message : String(e)}` }],\n          details: {},\n        };\n      }\n    },\n  } as any;\n}\n"],"mappings":"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"}

package/dist/src/agent/tools/tool-manual-tool.d.ts

@@ -0,0 +1,6 @@
+import type { AgentTool } from '@earendil-works/pi-agent-core';
+declare const ToolManualSchema: import("@sinclair/typebox/build/cjs/index.js").TObject<{
+    tool: import("@sinclair/typebox/build/cjs/index.js").TString;
+}>;
+export declare function createToolManualTool(): AgentTool<typeof ToolManualSchema, {}>;
+export {};

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

@@ -0,0 +1,34 @@
+import { getToolManual, listToolManuals } from "../tool-manuals/index.js";
+import { Type } from "@sinclair/typebox";
+//#region src/agent/tools/tool-manual-tool.ts
+const ToolManualSchema = Type.Object({ tool: Type.String({ description: "Built-in tool name, e.g. browser_use" }) });
+function createToolManualTool() {
+	return {
+		name: "tool_manual",
+		label: "📘 Tool Manual",
+		description: "Load built-in usage manuals for complex tools. Use before non-trivial use of tools such as browser_use.",
+		parameters: ToolManualSchema,
+		async execute(_toolCallId, params) {
+			const toolName = params.tool.trim();
+			const manual = getToolManual(toolName);
+			if (!manual) return {
+				content: [{
+					type: "text",
+					text: `No built-in manual found for tool: ${toolName}. Available manuals: ${listToolManuals().map((m) => m.toolName).join(", ") || "none"}.`
+				}],
+				details: {}
+			};
+			return {
+				content: [{
+					type: "text",
+					text: manual.content
+				}],
+				details: {}
+			};
+		}
+	};
+}
+//#endregion
+export { createToolManualTool };
+
+//# sourceMappingURL=tool-manual-tool.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tool-manual-tool.js","names":[],"sources":["../../../../src/agent/tools/tool-manual-tool.ts"],"sourcesContent":["import { Type } from '@sinclair/typebox';\nimport type { AgentTool, AgentToolResult } from '@earendil-works/pi-agent-core';\n\nimport { getToolManual, listToolManuals } from '../tool-manuals/index.js';\n\nconst ToolManualSchema = Type.Object({\n  tool: Type.String({ description: 'Built-in tool name, e.g. browser_use' }),\n});\n\nexport function createToolManualTool(): AgentTool<typeof ToolManualSchema, {}> {\n  return {\n    name: 'tool_manual',\n    label: '📘 Tool Manual',\n    description:\n      'Load built-in usage manuals for complex tools. Use before non-trivial use of tools such as browser_use.',\n    parameters: ToolManualSchema,\n    async execute(_toolCallId, params): Promise<AgentToolResult<{}>> {\n      const toolName = params.tool.trim();\n      const manual = getToolManual(toolName);\n      if (!manual) {\n        const available = listToolManuals().map((m) => m.toolName);\n        return {\n          content: [\n            {\n              type: 'text',\n              text: `No built-in manual found for tool: ${toolName}. Available manuals: ${available.join(', ') || 'none'}.`,\n            },\n          ],\n          details: {},\n        };\n      }\n\n      return {\n        content: [{ type: 'text', text: manual.content }],\n        details: {},\n      };\n    },\n  };\n}\n"],"mappings":";;;AAKA,MAAM,mBAAmB,KAAK,OAAO,EACnC,MAAM,KAAK,OAAO,EAAE,aAAa,wCAAwC,CAAC,EAC3E,CAAC;AAEF,SAAgB,uBAA+D;AAC7E,QAAO;EACL,MAAM;EACN,OAAO;EACP,aACE;EACF,YAAY;EACZ,MAAM,QAAQ,aAAa,QAAsC;GAC/D,MAAM,WAAW,OAAO,KAAK,MAAM;GACnC,MAAM,SAAS,cAAc,SAAS;AACtC,OAAI,CAAC,OAEH,QAAO;IACL,SAAS,CACP;KACE,MAAM;KACN,MAAM,sCAAsC,SAAS,uBALzC,iBAAiB,CAAC,KAAK,MAAM,EAAE,SAK0C,CAAC,KAAK,KAAK,IAAI,OAAO;KAC5G,CACF;IACD,SAAS,EAAE;IACZ;AAGH,UAAO;IACL,SAAS,CAAC;KAAE,MAAM;KAAQ,MAAM,OAAO;KAAS,CAAC;IACjD,SAAS,EAAE;IACZ;;EAEJ"}

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

@@ -2,8 +2,9 @@
  * 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}
+ *   1. `~/.xopc/workflows/<name>/workflow.js` (+ optional `manifest.json`)
+ *   2. `~/.xopc/workflows/<name>.js` (or `<name>.workflow.js`)
+ *   3. {@link BUILTIN_WORKFLOWS}
  *
  * The user dir is discovered via {@link resolveStateDir}, so `XOPC_STATE_DIR`
  * overrides apply automatically (matches how skills / extensions are wired).
@@ -15,6 +16,7 @@
  * the filename. This prevents copy-pasted scripts from being silently
  * mis-addressed when invoked by name.
  */
+import type { WorkflowDefinitionManifest } from '../../workflows/domain/definition.js';
 import type { WorkflowMeta } from './types.js';
 export type WorkflowSource = 'user' | 'builtin';
 export interface CatalogEntry {
@@ -23,6 +25,8 @@ export interface CatalogEntry {
     /** Absolute path for user entries; null for built-ins (in-memory). */
     path: string | null;
     description: string;
+    title?: string;
+    version?: string;
     whenToUse?: string;
     tags?: string[];
     estimatedAgents?: {
@@ -36,6 +40,7 @@ export interface LoadedWorkflow {
     script: string;
     meta: WorkflowMeta;
     path: string | null;
+    manifest?: WorkflowDefinitionManifest;
 }
 export interface WorkflowCatalog {
     list(): CatalogEntry[];

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

@@ -8,8 +8,9 @@ import { join } from "node:path";
 * 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}
+*   1. `~/.xopc/workflows/<name>/workflow.js` (+ optional `manifest.json`)
+*   2. `~/.xopc/workflows/<name>.js` (or `<name>.workflow.js`)
+*   3. {@link BUILTIN_WORKFLOWS}
 *
 * The user dir is discovered via {@link resolveStateDir}, so `XOPC_STATE_DIR`
 * overrides apply automatically (matches how skills / extensions are wired).
@@ -39,18 +40,18 @@ function createWorkflowCatalog(opts = {}) {
 				estimatedAgents: meta?.estimatedAgents
 			});
 		}
-		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,
+		for (const entry of safeListUserEntries(userDir)) {
+			const meta = safeMeta(readScript(entry.path));
+			const manifest = readManifest(entry.manifestPath);
+			entries.set(entry.name, {
+				name: entry.name,
 				source: "user",
-				path: full,
-				description: meta?.description ?? "(unparseable)",
-				whenToUse: meta?.whenToUse,
-				tags: meta?.tags,
+				path: entry.path,
+				description: manifest?.description ?? meta?.description ?? "(unparseable)",
+				title: manifest?.title,
+				version: manifest?.version,
+				whenToUse: manifest?.whenToUse ?? meta?.whenToUse,
+				tags: manifest?.tags ?? meta?.tags,
 				estimatedAgents: meta?.estimatedAgents
 			});
 		}
@@ -58,17 +59,18 @@ function createWorkflowCatalog(opts = {}) {
 	};
 	const load = (name) => {
 		requireValidName(name);
-		const userPath = findUserPath(userDir, name);
-		if (userPath) {
-			const script = readScript(userPath);
+		const userEntry = findUserEntry(userDir, name);
+		if (userEntry) {
+			const script = readScript(userEntry.path);
 			const { meta } = parseWorkflowScript(script);
-			ensureMetaNameMatches(meta, name, userPath);
+			ensureMetaNameMatches(meta, name, userEntry.path);
 			return {
 				name,
 				source: "user",
 				script,
 				meta,
-				path: userPath
+				path: userEntry.path,
+				manifest: readManifest(userEntry.manifestPath)
 			};
 		}
 		const builtin = BUILTIN_WORKFLOWS.find((b) => b.name === name);
@@ -96,9 +98,9 @@ function createWorkflowCatalog(opts = {}) {
 	};
 	const remove = (name) => {
 		requireValidName(name);
-		const userPath = findUserPath(userDir, name);
-		if (!userPath) return false;
-		unlinkSync(userPath);
+		const userEntry = findUserEntry(userDir, name);
+		if (!userEntry) return false;
+		unlinkSync(userEntry.path);
 		return true;
 	};
 	return {
@@ -112,25 +114,64 @@ function createWorkflowCatalog(opts = {}) {
 function defaultUserDir() {
 	return join(resolveStateDir(), "workflows");
 }
-function safeListUserFiles(dir) {
+function safeListUserEntries(dir) {
 	try {
 		if (!existsSync(dir)) return [];
 		if (!statSync(dir).isDirectory()) return [];
-		return readdirSync(dir).filter((f) => /\.(js|workflow\.js)$/i.test(f));
+		const entries = [];
+		for (const file of readdirSync(dir)) {
+			const full = join(dir, file);
+			if (statSync(full).isDirectory()) {
+				const workflowPath = join(full, "workflow.js");
+				if (existsSync(workflowPath) && isValidName(file)) entries.push({
+					name: file,
+					path: workflowPath,
+					manifestPath: join(full, "manifest.json")
+				});
+				continue;
+			}
+			if (!/\.(js|workflow\.js)$/i.test(file)) continue;
+			const name = stripExt(file);
+			if (!isValidName(name)) continue;
+			entries.push({
+				name,
+				path: full
+			});
+		}
+		return entries;
 	} catch {
 		return [];
 	}
 }
-function findUserPath(dir, name) {
+function findUserEntry(dir, name) {
+	const dirWorkflowPath = join(dir, name, "workflow.js");
+	if (existsSync(dirWorkflowPath)) return {
+		name,
+		path: dirWorkflowPath,
+		manifestPath: join(dir, name, "manifest.json")
+	};
 	for (const candidate of [`${name}.js`, `${name}.workflow.js`]) {
 		const full = join(dir, candidate);
-		if (existsSync(full)) return full;
+		if (existsSync(full)) return {
+			name,
+			path: full
+		};
 	}
 	return null;
 }
 function readScript(path) {
 	return readFileSync(path, "utf-8");
 }
+function readManifest(path) {
+	if (!path || !existsSync(path)) return void 0;
+	try {
+		const value = JSON.parse(readFileSync(path, "utf-8"));
+		if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+		return value;
+	} catch {
+		return;
+	}
+}
 function safeMeta(script) {
 	try {
 		return parseWorkflowScript(script).meta;

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

@@ -1 +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  tags?: string[];\n  estimatedAgents?: { min: number; max: number };\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        tags: meta?.tags,\n        estimatedAgents: meta?.estimatedAgents,\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        tags: meta?.tags,\n        estimatedAgents: meta?.estimatedAgents,\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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"}
+{"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>/workflow.js` (+ optional `manifest.json`)\n *   2. `~/.xopc/workflows/<name>.js` (or `<name>.workflow.js`)\n *   3. {@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 type { WorkflowDefinitionManifest } from '../../workflows/domain/definition.js';\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  title?: string;\n  version?: string;\n  whenToUse?: string;\n  tags?: string[];\n  estimatedAgents?: { min: number; max: number };\n}\n\nexport interface LoadedWorkflow {\n  name: string;\n  source: WorkflowSource;\n  script: string;\n  meta: WorkflowMeta;\n  path: string | null;\n  manifest?: WorkflowDefinitionManifest;\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        tags: meta?.tags,\n        estimatedAgents: meta?.estimatedAgents,\n      });\n    }\n    for (const entry of safeListUserEntries(userDir)) {\n      const meta = safeMeta(readScript(entry.path));\n      const manifest = readManifest(entry.manifestPath);\n      // User wins on collision.\n      entries.set(entry.name, {\n        name: entry.name,\n        source: 'user',\n        path: entry.path,\n        description: manifest?.description ?? meta?.description ?? '(unparseable)',\n        title: manifest?.title,\n        version: manifest?.version,\n        whenToUse: manifest?.whenToUse ?? meta?.whenToUse,\n        tags: manifest?.tags ?? meta?.tags,\n        estimatedAgents: meta?.estimatedAgents,\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 userEntry = findUserEntry(userDir, name);\n    if (userEntry) {\n      const script = readScript(userEntry.path);\n      const { meta } = parseWorkflowScript(script);\n      ensureMetaNameMatches(meta, name, userEntry.path);\n      return {\n        name,\n        source: 'user',\n        script,\n        meta,\n        path: userEntry.path,\n        manifest: readManifest(userEntry.manifestPath),\n      };\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 userEntry = findUserEntry(userDir, name);\n    if (!userEntry) return false;\n    unlinkSync(userEntry.path);\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\ninterface UserWorkflowEntry {\n  name: string;\n  path: string;\n  manifestPath?: string;\n}\n\nfunction safeListUserEntries(dir: string): UserWorkflowEntry[] {\n  try {\n    if (!existsSync(dir)) return [];\n    const st = statSync(dir);\n    if (!st.isDirectory()) return [];\n    const entries: UserWorkflowEntry[] = [];\n    for (const file of readdirSync(dir)) {\n      const full = join(dir, file);\n      const fileStat = statSync(full);\n      if (fileStat.isDirectory()) {\n        const workflowPath = join(full, 'workflow.js');\n        if (existsSync(workflowPath) && isValidName(file)) {\n          entries.push({ name: file, path: workflowPath, manifestPath: join(full, 'manifest.json') });\n        }\n        continue;\n      }\n      if (!/\\.(js|workflow\\.js)$/i.test(file)) continue;\n      const name = stripExt(file);\n      if (!isValidName(name)) continue;\n      entries.push({ name, path: full });\n    }\n    return entries;\n  } catch {\n    return [];\n  }\n}\n\nfunction findUserEntry(dir: string, name: string): UserWorkflowEntry | null {\n  const dirWorkflowPath = join(dir, name, 'workflow.js');\n  if (existsSync(dirWorkflowPath)) {\n    return { name, path: dirWorkflowPath, manifestPath: join(dir, name, 'manifest.json') };\n  }\n  for (const candidate of [`${name}.js`, `${name}.workflow.js`]) {\n    const full = join(dir, candidate);\n    if (existsSync(full)) return { name, path: full };\n  }\n  return null;\n}\n\nfunction readScript(path: string): string {\n  return readFileSync(path, 'utf-8');\n}\n\nfunction readManifest(path: string | undefined): WorkflowDefinitionManifest | undefined {\n  if (!path || !existsSync(path)) return undefined;\n  try {\n    const value = JSON.parse(readFileSync(path, 'utf-8')) as WorkflowDefinitionManifest;\n    if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;\n    return value;\n  } catch {\n    return undefined;\n  }\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/subagent-runner.d.ts

@@ -17,6 +17,7 @@ import type { AgentTool } from '@earendil-works/pi-agent-core';
 import type { Api, Model } from '@earendil-works/pi-ai';
 import type { Config } from '../../config/schema.js';
 import type { MessageBus } from '../../infra/bus/index.js';
+import type { SessionStore } from '../../session/store.js';
 import { type BuildChildToolsOptions } from '../child-agent-factory.js';
 import type { ToolExecutorConfig } from '../tools/executor.js';
 import type { SubagentRunOptions, SubagentRunner } from './types.js';
@@ -27,6 +28,7 @@ export interface DelegateSubagentRunnerDeps {
     getDefaultModel: () => Model<Api>;
     getConfig: () => Config | undefined;
     toolExecutorConfig?: Partial<ToolExecutorConfig>;
+    sessionStore?: SessionStore;
     /**
      * Provided by the workflow tool from `AgentToolsFactory` — mirrors how
      * `delegate-tool` is wired (avoids importing `tools/factory.ts` here and
@@ -39,4 +41,5 @@ export declare class DelegateSubagentRunner implements SubagentRunner {
     private readonly deps;
     constructor(deps: DelegateSubagentRunnerDeps);
     run<T = string>(prompt: string, opts: SubagentRunOptions<T>): Promise<T | null>;
+    private preparePersistentSubagentSession;
 }

package/dist/src/agent/workflow/subagent-runner.js

@@ -3,6 +3,7 @@ import { init_logger } from "../../utils/logger.js";
 import { createDelegateChildHandle } from "../child-agent-factory.js";
 import { DEFAULT_DELEGATE_TOOLS, DELEGATE_BLOCKED_TOOLS } from "../tools/delegate-tool.js";
 import { STRUCTURED_OUTPUT_TOOL_NAME, createStructuredOutputTool } from "./structured-output-tool.js";
+import { emitSessionTranscriptUpdate } from "../../session/transcript-events.js";
 //#region src/agent/workflow/subagent-runner.ts
 init_logger();
 const log = createLogger("Agent:WorkflowSubagent");
@@ -26,7 +27,25 @@ var DelegateSubagentRunner = class {
 		}
 		const fullPrompt = buildPrompt(prompt, opts, wantStructured);
 		const streamMode = resolveSubagentStreamMode(this.deps.getConfig);
-		const handle = createDelegateChildHandle({
+		let transcriptPersistQueue = Promise.resolve();
+		const persistTranscriptSnapshot = opts.sessionKey && this.deps.sessionStore ? (messages) => {
+			const store = this.deps.sessionStore;
+			const key = opts.sessionKey;
+			if (!store || !key) return;
+			const snapshot = cloneAgentMessages(messages);
+			transcriptPersistQueue = transcriptPersistQueue.then(async () => {
+				await store.saveMessages(key, snapshot);
+				emitSessionTranscriptUpdate({ sessionKey: key });
+			}).catch((err) => {
+				const msg = err instanceof Error ? err.message : String(err);
+				log.warn({
+					err,
+					sessionKey: key,
+					errorMessage: msg
+				}, `Failed to persist workflow subagent transcript snapshot: ${msg}`);
+			});
+		} : void 0;
+		const childOptions = {
 			workspace: this.deps.workspace,
 			goal: fullPrompt,
 			allowedToolNames: allowed,
@@ -48,12 +67,20 @@ var DelegateSubagentRunner = class {
 				onProgress: (event) => {
 					opts.onProgress?.(mapChildProgressEvent(event));
 				}
-			} : void 0
-		});
+			} : void 0,
+			onTranscriptSnapshot: persistTranscriptSnapshot
+		};
+		if (opts.sessionKey && opts.sessionMetadata && this.deps.sessionStore) await this.preparePersistentSubagentSession(opts.sessionKey, opts.sessionMetadata);
+		const handle = createDelegateChildHandle(childOptions);
 		const onAbort = () => handle.abort();
 		opts.signal?.addEventListener("abort", onAbort, { once: true });
 		try {
-			const { summary } = await handle.run();
+			const { summary, messages } = await handle.run();
+			await transcriptPersistQueue;
+			if (opts.sessionKey && this.deps.sessionStore) {
+				await this.deps.sessionStore.saveMessages(opts.sessionKey, messages);
+				emitSessionTranscriptUpdate({ sessionKey: opts.sessionKey });
+			}
 			if (opts.signal?.aborted) return null;
 			if (wantStructured) {
 				if (!capture.called) {
@@ -76,7 +103,26 @@ var DelegateSubagentRunner = class {
 			opts.signal?.removeEventListener("abort", onAbort);
 		}
 	}
+	async preparePersistentSubagentSession(sessionKey, metadata) {
+		const store = this.deps.sessionStore;
+		if (!store) return;
+		await store.resolveTranscriptPath(sessionKey);
+		await store.updateMetadata(sessionKey, {
+			sessionType: "workflow-subagent",
+			hiddenFromSessionList: true,
+			parentSessionKey: metadata.parentSessionKey,
+			workflowRunId: metadata.workflowRunId,
+			workflowDefinitionId: metadata.workflowDefinitionId,
+			workflowAgentId: metadata.workflowAgentId,
+			workflowAgentLabel: metadata.workflowAgentLabel,
+			name: metadata.workflowAgentLabel,
+			tags: ["workflow-subagent", metadata.workflowDefinitionId]
+		});
+	}
 };
+function cloneAgentMessages(messages) {
+	return messages.map((message) => structuredClone(message));
+}
 function resolveAllowedToolNames(requested, wantStructured) {
 	const filtered = (requested && requested.length > 0 ? requested : [...DEFAULT_DELEGATE_TOOLS]).map((s) => String(s).trim()).filter((s) => s.length > 0).filter((s) => !DELEGATE_BLOCKED_TOOLS.has(s));
 	if (wantStructured && !filtered.includes("structured_output")) filtered.push(STRUCTURED_OUTPUT_TOOL_NAME);

package/dist/src/agent/workflow/subagent-runner.js.map

@@ -1 +1 @@
-{"version":3,"file":"subagent-runner.js","names":[],"sources":["../../../../src/agent/workflow/subagent-runner.ts"],"sourcesContent":["/**\n * Adapter: spawns one isolated child agent per `agent()` call from a workflow.\n *\n * Wraps the existing `createDelegateChildHandle` so the workflow runtime stays\n * decoupled from the LLM stack (it sees only the `SubagentRunner` interface).\n *\n * Key behaviour:\n * - When `opts.schema` is provided, we inject `structured_output` into the child\n *   tool set and unwrap the captured value on success. If the subagent finishes\n *   without ever calling `structured_output`, we treat it as failure (`null`).\n * - Failures and aborts resolve to `null`. The workflow runtime continues — this\n *   matches the pi-dynamic-workflows contract and keeps fan-out pipelines robust.\n * - We do NOT mutate `createDelegateChildHandle` — we just leverage its\n *   `buildChildTools` injection point.\n */\n\nimport type { AgentTool } 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 {\n  type BuildChildToolsOptions,\n  createDelegateChildHandle,\n  type DelegateChildHandleOptions,\n} from '../child-agent-factory.js';\nimport {\n  DEFAULT_DELEGATE_TOOLS,\n  DELEGATE_BLOCKED_TOOLS,\n} from '../tools/delegate-tool.js';\nimport type { ToolExecutorConfig } from '../tools/executor.js';\n\nimport {\n  createStructuredOutputTool,\n  STRUCTURED_OUTPUT_TOOL_NAME,\n  type StructuredOutputCapture,\n} from './structured-output-tool.js';\nimport type { SubagentRunOptions, SubagentRunner, SubagentProgressEvent } from './types.js';\n\nconst log = createLogger('Agent:WorkflowSubagent');\n\nconst DEFAULT_MAX_ITERATIONS = 30;\n\nexport interface DelegateSubagentRunnerDeps {\n  workspace: string;\n  bus: MessageBus;\n  /** Resolves the default subagent model (typically the parent agent's primary model). */\n  getDefaultModel: () => Model<Api>;\n  getConfig: () => Config | undefined;\n  toolExecutorConfig?: Partial<ToolExecutorConfig>;\n  /**\n   * Provided by the workflow tool from `AgentToolsFactory` — mirrors how\n   * `delegate-tool` is wired (avoids importing `tools/factory.ts` here and\n   * breaking the existing factory ↔ delegate-tool ↔ child-agent-factory\n   * dependency contract).\n   */\n  buildChildTools: (opts: BuildChildToolsOptions) => AgentTool<any, any>[];\n}\n\nexport class DelegateSubagentRunner implements SubagentRunner {\n  constructor(private readonly deps: DelegateSubagentRunnerDeps) {}\n\n  async run<T = string>(prompt: string, opts: SubagentRunOptions<T>): Promise<T | null> {\n    if (opts.signal?.aborted) return null;\n\n    const capture: StructuredOutputCapture<T> = { called: false, value: undefined };\n    const wantStructured = Boolean(opts.schema);\n\n    const allowed = resolveAllowedToolNames(opts.allowedToolNames, wantStructured);\n    const model = opts.model ?? safeResolveDefaultModel(this.deps.getDefaultModel);\n    if (!model) {\n      log.warn({ label: opts.label }, 'subagent run skipped: no primary model resolved');\n      return null;\n    }\n\n    const fullPrompt = buildPrompt(prompt, opts, wantStructured);\n    const streamMode = resolveSubagentStreamMode(this.deps.getConfig);\n\n    const childOptions: DelegateChildHandleOptions = {\n      workspace: this.deps.workspace,\n      goal: fullPrompt,\n      allowedToolNames: allowed,\n      maxIterations: opts.maxIterations ?? DEFAULT_MAX_ITERATIONS,\n      model,\n      bus: this.deps.bus,\n      getConfig: this.deps.getConfig,\n      toolExecutorConfig: this.deps.toolExecutorConfig,\n      buildChildTools: (childOpts) => {\n        const base = this.deps.buildChildTools(childOpts);\n        if (!wantStructured || !opts.schema) return base;\n        // Replace any existing tool with the same name so the per-run capture wins.\n        const filtered = base.filter((t) => t.name !== STRUCTURED_OUTPUT_TOOL_NAME);\n        return [\n          ...filtered,\n          createStructuredOutputTool({ schema: opts.schema, capture }) as unknown as AgentTool<any, any>,\n        ];\n      },\n      progressHooks:\n        opts.onProgress && streamMode !== 'off'\n          ? {\n              mode: streamMode === 'full' ? 'full' : 'steps',\n              onProgress: (event) => {\n                opts.onProgress?.(mapChildProgressEvent(event));\n              },\n            }\n          : undefined,\n    };\n\n    const handle = createDelegateChildHandle(childOptions);\n    const onAbort = () => handle.abort();\n    opts.signal?.addEventListener('abort', onAbort, { once: true });\n\n    try {\n      const { summary } = await handle.run();\n      if (opts.signal?.aborted) return null;\n\n      if (wantStructured) {\n        if (!capture.called) {\n          log.warn({ label: opts.label }, 'subagent finished without calling structured_output');\n          return null;\n        }\n        return capture.value as T;\n      }\n      return summary as unknown as T;\n    } catch (e) {\n      if (opts.rethrow) throw e;\n      const msg = e instanceof Error ? e.message : String(e);\n      log.warn({ err: e, label: opts.label, errorMessage: msg }, `subagent run failed: ${msg}`);\n      return null;\n    } finally {\n      opts.signal?.removeEventListener('abort', onAbort);\n    }\n  }\n}\n\nfunction resolveAllowedToolNames(\n  requested: string[] | undefined,\n  wantStructured: boolean,\n): string[] {\n  const base = requested && requested.length > 0 ? requested : [...DEFAULT_DELEGATE_TOOLS];\n  const filtered = base\n    .map((s) => String(s).trim())\n    .filter((s) => s.length > 0)\n    .filter((s) => !DELEGATE_BLOCKED_TOOLS.has(s));\n  if (wantStructured && !filtered.includes(STRUCTURED_OUTPUT_TOOL_NAME)) {\n    filtered.push(STRUCTURED_OUTPUT_TOOL_NAME);\n  }\n  return [...new Set(filtered)];\n}\n\nfunction buildPrompt(prompt: string, opts: SubagentRunOptions<unknown>, structured: boolean): string {\n  const parts: string[] = [];\n  if (opts.instructions?.trim()) parts.push(opts.instructions.trim());\n  if (opts.label) parts.push(`Task label: ${opts.label}`);\n  if (opts.phase) parts.push(`Workflow phase: ${opts.phase}`);\n  parts.push(prompt);\n  if (structured) {\n    parts.push(\n      [\n        'Final output contract:',\n        '- Your final action MUST be a structured_output tool call.',\n        '- The structured_output arguments are the return value of this subagent.',\n        '- Do not emit a prose final answer instead of structured_output.',\n        '- If you need to inspect files or run commands first, do so, then call structured_output exactly once.',\n      ].join('\\n'),\n    );\n  }\n  return parts.join('\\n\\n');\n}\n\nfunction safeResolveDefaultModel(get: () => Model<Api>): Model<Api> | null {\n  try {\n    return get();\n  } catch (e) {\n    log.warn({ err: e }, 'failed to resolve default subagent model');\n    return null;\n  }\n}\n\nfunction resolveSubagentStreamMode(\n  getConfig: () => Config | undefined,\n): 'off' | 'steps' | 'full' {\n  const mode = getConfig()?.agents?.defaults?.workflow?.subagentStream;\n  if (mode === 'off' || mode === 'steps' || mode === 'full') return mode;\n  return 'steps';\n}\n\nfunction mapChildProgressEvent(event: {\n  type: 'tool_start' | 'tool_end' | 'iteration' | 'text_delta' | 'thinking_delta';\n  toolCallId?: string;\n  toolName?: string;\n  args?: Record<string, unknown>;\n  isError?: boolean;\n  resultPreview?: string;\n  error?: string;\n  count?: number;\n  max?: number;\n  delta?: string;\n}): SubagentProgressEvent {\n  switch (event.type) {\n    case 'tool_start':\n      return {\n        type: 'tool_start',\n        toolCallId: event.toolCallId ?? '',\n        toolName: event.toolName ?? 'tool',\n        args: event.args ?? {},\n      };\n    case 'tool_end':\n      return {\n        type: 'tool_end',\n        toolCallId: event.toolCallId ?? '',\n        toolName: event.toolName ?? 'tool',\n        isError: Boolean(event.isError),\n        resultPreview: event.resultPreview,\n        error: event.error,\n      };\n    case 'iteration':\n      return {\n        type: 'iteration',\n        count: event.count ?? 0,\n        max: event.max ?? 0,\n      };\n    case 'text_delta':\n      return { type: 'text_delta', delta: event.delta ?? '' };\n    case 'thinking_delta':\n      return { type: 'thinking_delta', delta: event.delta ?? '' };\n    default:\n      return { type: 'text_delta', delta: '' };\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"subagent-runner.js","names":[],"sources":["../../../../src/agent/workflow/subagent-runner.ts"],"sourcesContent":["/**\n * Adapter: spawns one isolated child agent per `agent()` call from a workflow.\n *\n * Wraps the existing `createDelegateChildHandle` so the workflow runtime stays\n * decoupled from the LLM stack (it sees only the `SubagentRunner` interface).\n *\n * Key behaviour:\n * - When `opts.schema` is provided, we inject `structured_output` into the child\n *   tool set and unwrap the captured value on success. If the subagent finishes\n *   without ever calling `structured_output`, we treat it as failure (`null`).\n * - Failures and aborts resolve to `null`. The workflow runtime continues — this\n *   matches the pi-dynamic-workflows contract and keeps fan-out pipelines robust.\n * - We do NOT mutate `createDelegateChildHandle` — we just leverage its\n *   `buildChildTools` injection point.\n */\n\nimport type { AgentTool } 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 type { SessionStore } from '../../session/store.js';\nimport { emitSessionTranscriptUpdate } from '../../session/transcript-events.js';\nimport { createLogger } from '../../utils/logger.js';\n\nimport {\n  type BuildChildToolsOptions,\n  createDelegateChildHandle,\n  type DelegateChildHandleOptions,\n} from '../child-agent-factory.js';\nimport {\n  DEFAULT_DELEGATE_TOOLS,\n  DELEGATE_BLOCKED_TOOLS,\n} from '../tools/delegate-tool.js';\nimport type { ToolExecutorConfig } from '../tools/executor.js';\n\nimport {\n  createStructuredOutputTool,\n  STRUCTURED_OUTPUT_TOOL_NAME,\n  type StructuredOutputCapture,\n} from './structured-output-tool.js';\nimport type { SubagentRunOptions, SubagentRunner, SubagentProgressEvent } from './types.js';\n\nconst log = createLogger('Agent:WorkflowSubagent');\n\nconst DEFAULT_MAX_ITERATIONS = 30;\n\nexport interface DelegateSubagentRunnerDeps {\n  workspace: string;\n  bus: MessageBus;\n  /** Resolves the default subagent model (typically the parent agent's primary model). */\n  getDefaultModel: () => Model<Api>;\n  getConfig: () => Config | undefined;\n  toolExecutorConfig?: Partial<ToolExecutorConfig>;\n  sessionStore?: SessionStore;\n  /**\n   * Provided by the workflow tool from `AgentToolsFactory` — mirrors how\n   * `delegate-tool` is wired (avoids importing `tools/factory.ts` here and\n   * breaking the existing factory ↔ delegate-tool ↔ child-agent-factory\n   * dependency contract).\n   */\n  buildChildTools: (opts: BuildChildToolsOptions) => AgentTool<any, any>[];\n}\n\nexport class DelegateSubagentRunner implements SubagentRunner {\n  constructor(private readonly deps: DelegateSubagentRunnerDeps) {}\n\n  async run<T = string>(prompt: string, opts: SubagentRunOptions<T>): Promise<T | null> {\n    if (opts.signal?.aborted) return null;\n\n    const capture: StructuredOutputCapture<T> = { called: false, value: undefined };\n    const wantStructured = Boolean(opts.schema);\n\n    const allowed = resolveAllowedToolNames(opts.allowedToolNames, wantStructured);\n    const model = opts.model ?? safeResolveDefaultModel(this.deps.getDefaultModel);\n    if (!model) {\n      log.warn({ label: opts.label }, 'subagent run skipped: no primary model resolved');\n      return null;\n    }\n\n    const fullPrompt = buildPrompt(prompt, opts, wantStructured);\n    const streamMode = resolveSubagentStreamMode(this.deps.getConfig);\n\n    let transcriptPersistQueue: Promise<void> = Promise.resolve();\n    const persistTranscriptSnapshot = opts.sessionKey && this.deps.sessionStore\n      ? (messages: Parameters<SessionStore['saveMessages']>[1]) => {\n          const store = this.deps.sessionStore;\n          const key = opts.sessionKey;\n          if (!store || !key) return;\n          const snapshot = cloneAgentMessages(messages);\n          transcriptPersistQueue = transcriptPersistQueue\n            .then(async () => {\n              await store.saveMessages(key, snapshot);\n              emitSessionTranscriptUpdate({ sessionKey: key });\n            })\n            .catch((err) => {\n              const msg = err instanceof Error ? err.message : String(err);\n              log.warn(\n                { err, sessionKey: key, errorMessage: msg },\n                `Failed to persist workflow subagent transcript snapshot: ${msg}`,\n              );\n            });\n        }\n      : undefined;\n\n    const childOptions: DelegateChildHandleOptions = {\n      workspace: this.deps.workspace,\n      goal: fullPrompt,\n      allowedToolNames: allowed,\n      maxIterations: opts.maxIterations ?? DEFAULT_MAX_ITERATIONS,\n      model,\n      bus: this.deps.bus,\n      getConfig: this.deps.getConfig,\n      toolExecutorConfig: this.deps.toolExecutorConfig,\n      buildChildTools: (childOpts) => {\n        const base = this.deps.buildChildTools(childOpts);\n        if (!wantStructured || !opts.schema) return base;\n        // Replace any existing tool with the same name so the per-run capture wins.\n        const filtered = base.filter((t) => t.name !== STRUCTURED_OUTPUT_TOOL_NAME);\n        return [\n          ...filtered,\n          createStructuredOutputTool({ schema: opts.schema, capture }) as unknown as AgentTool<any, any>,\n        ];\n      },\n      progressHooks:\n        opts.onProgress && streamMode !== 'off'\n          ? {\n              mode: streamMode === 'full' ? 'full' : 'steps',\n              onProgress: (event) => {\n                opts.onProgress?.(mapChildProgressEvent(event));\n              },\n            }\n          : undefined,\n      onTranscriptSnapshot: persistTranscriptSnapshot,\n    };\n\n    if (opts.sessionKey && opts.sessionMetadata && this.deps.sessionStore) {\n      await this.preparePersistentSubagentSession(opts.sessionKey, opts.sessionMetadata);\n    }\n\n    const handle = createDelegateChildHandle(childOptions);\n    const onAbort = () => handle.abort();\n    opts.signal?.addEventListener('abort', onAbort, { once: true });\n\n    try {\n      const { summary, messages } = await handle.run();\n      await transcriptPersistQueue;\n      if (opts.sessionKey && this.deps.sessionStore) {\n        await this.deps.sessionStore.saveMessages(opts.sessionKey, messages);\n        emitSessionTranscriptUpdate({ sessionKey: opts.sessionKey });\n      }\n      if (opts.signal?.aborted) return null;\n\n      if (wantStructured) {\n        if (!capture.called) {\n          log.warn({ label: opts.label }, 'subagent finished without calling structured_output');\n          return null;\n        }\n        return capture.value as T;\n      }\n      return summary as unknown as T;\n    } catch (e) {\n      if (opts.rethrow) throw e;\n      const msg = e instanceof Error ? e.message : String(e);\n      log.warn({ err: e, label: opts.label, errorMessage: msg }, `subagent run failed: ${msg}`);\n      return null;\n    } finally {\n      opts.signal?.removeEventListener('abort', onAbort);\n    }\n  }\n\n  private async preparePersistentSubagentSession(\n    sessionKey: string,\n    metadata: NonNullable<SubagentRunOptions['sessionMetadata']>,\n  ): Promise<void> {\n    const store = this.deps.sessionStore;\n    if (!store) return;\n    await store.resolveTranscriptPath(sessionKey);\n    await store.updateMetadata(sessionKey, {\n      sessionType: 'workflow-subagent',\n      hiddenFromSessionList: true,\n      parentSessionKey: metadata.parentSessionKey,\n      workflowRunId: metadata.workflowRunId,\n      workflowDefinitionId: metadata.workflowDefinitionId,\n      workflowAgentId: metadata.workflowAgentId,\n      workflowAgentLabel: metadata.workflowAgentLabel,\n      name: metadata.workflowAgentLabel,\n      tags: ['workflow-subagent', metadata.workflowDefinitionId],\n    });\n  }\n}\n\nfunction cloneAgentMessages(messages: Parameters<SessionStore['saveMessages']>[1]): Parameters<SessionStore['saveMessages']>[1] {\n  return messages.map((message) => structuredClone(message));\n}\n\nfunction resolveAllowedToolNames(\n  requested: string[] | undefined,\n  wantStructured: boolean,\n): string[] {\n  const base = requested && requested.length > 0 ? requested : [...DEFAULT_DELEGATE_TOOLS];\n  const filtered = base\n    .map((s) => String(s).trim())\n    .filter((s) => s.length > 0)\n    .filter((s) => !DELEGATE_BLOCKED_TOOLS.has(s));\n  if (wantStructured && !filtered.includes(STRUCTURED_OUTPUT_TOOL_NAME)) {\n    filtered.push(STRUCTURED_OUTPUT_TOOL_NAME);\n  }\n  return [...new Set(filtered)];\n}\n\nfunction buildPrompt(prompt: string, opts: SubagentRunOptions<unknown>, structured: boolean): string {\n  const parts: string[] = [];\n  if (opts.instructions?.trim()) parts.push(opts.instructions.trim());\n  if (opts.label) parts.push(`Task label: ${opts.label}`);\n  if (opts.phase) parts.push(`Workflow phase: ${opts.phase}`);\n  parts.push(prompt);\n  if (structured) {\n    parts.push(\n      [\n        'Final output contract:',\n        '- Your final action MUST be a structured_output tool call.',\n        '- The structured_output arguments are the return value of this subagent.',\n        '- Do not emit a prose final answer instead of structured_output.',\n        '- If you need to inspect files or run commands first, do so, then call structured_output exactly once.',\n      ].join('\\n'),\n    );\n  }\n  return parts.join('\\n\\n');\n}\n\nfunction safeResolveDefaultModel(get: () => Model<Api>): Model<Api> | null {\n  try {\n    return get();\n  } catch (e) {\n    log.warn({ err: e }, 'failed to resolve default subagent model');\n    return null;\n  }\n}\n\nfunction resolveSubagentStreamMode(\n  getConfig: () => Config | undefined,\n): 'off' | 'steps' | 'full' {\n  const mode = getConfig()?.agents?.defaults?.workflow?.subagentStream;\n  if (mode === 'off' || mode === 'steps' || mode === 'full') return mode;\n  return 'steps';\n}\n\nfunction mapChildProgressEvent(event: {\n  type: 'tool_start' | 'tool_end' | 'iteration' | 'text_delta' | 'thinking_delta';\n  toolCallId?: string;\n  toolName?: string;\n  args?: Record<string, unknown>;\n  isError?: boolean;\n  resultPreview?: string;\n  error?: string;\n  count?: number;\n  max?: number;\n  delta?: string;\n}): SubagentProgressEvent {\n  switch (event.type) {\n    case 'tool_start':\n      return {\n        type: 'tool_start',\n        toolCallId: event.toolCallId ?? '',\n        toolName: event.toolName ?? 'tool',\n        args: event.args ?? {},\n      };\n    case 'tool_end':\n      return {\n        type: 'tool_end',\n        toolCallId: event.toolCallId ?? '',\n        toolName: event.toolName ?? 'tool',\n        isError: Boolean(event.isError),\n        resultPreview: event.resultPreview,\n        error: event.error,\n      };\n    case 'iteration':\n      return {\n        type: 'iteration',\n        count: event.count ?? 0,\n        max: event.max ?? 0,\n      };\n    case 'text_delta':\n      return { type: 'text_delta', delta: event.delta ?? '' };\n    case 'thinking_delta':\n      return { type: 'thinking_delta', delta: event.delta ?? '' };\n    default:\n      return { type: 'text_delta', delta: '' };\n  }\n}\n"],"mappings":"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"}

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

@@ -88,6 +88,7 @@ export interface WorkflowAgentSnapshot {
     streamText?: string;
 }
 export interface WorkflowSnapshot {
+    runId?: string;
     name: string;
     description?: string;
     phases: string[];
@@ -118,6 +119,15 @@ export interface SubagentRunOptions<T = unknown> {
     rethrow?: boolean;
     /** Hint about which phase this agent belongs to (passed through for logging). */
     phase?: string;
+    /** Persistent hidden session for this workflow subagent. */
+    sessionKey?: string;
+    sessionMetadata?: {
+        parentSessionKey?: string;
+        workflowRunId: string;
+        workflowDefinitionId: string;
+        workflowAgentId: string;
+        workflowAgentLabel: string;
+    };
     /** Live progress from the child agent loop (workflow tool binds per agent id). */
     onProgress?: (event: SubagentProgressEvent) => void;
     /** Pre-bound capture for structured output (internal: created by the adapter when schema present). */

package/dist/src/auth/credentials.js

@@ -16,13 +16,14 @@ async function resolveApiKey(provider, options) {
 async function hasCredentials(provider, options) {
 	return getCredentialResolver(options).hasCredentials(provider);
 }
-var log, CredentialResolver;
+var log, warnedExpiredOAuthTokens, CredentialResolver;
 var init_credentials = __esmMin((() => {
 	init_write_file_atomic();
 	init_logger();
 	init_env_keys();
 	init_paths();
 	log = createLogger("Credentials");
+	warnedExpiredOAuthTokens = /* @__PURE__ */ new Set();
 	CredentialResolver = class {
 		credentialsDir;
 		agentId;
@@ -163,10 +164,14 @@ var init_credentials = __esmMin((() => {
 			const token = await this.loadOAuthTokenRecord(provider);
 			if (!token) return null;
 			if (token.expiresAt && token.expiresAt < Date.now()) {
-				log.warn({
-					provider,
-					expiresAt: token.expiresAt
-				}, "OAuth token is expired");
+				const warnKey = `${provider}:${token.expiresAt}`;
+				if (!warnedExpiredOAuthTokens.has(warnKey)) {
+					warnedExpiredOAuthTokens.add(warnKey);
+					log.warn({
+						provider,
+						expiresAt: token.expiresAt
+					}, "OAuth token is expired");
+				}
 				return null;
 			}
 			return token;