@xopcai/xopc 0.0.102 → 0.0.104

package/dist/src/agent/tools/send-media.js.map

@@ -1 +1 @@
-{"version":3,"file":"send-media.js","names":[],"sources":["../../../../src/agent/tools/send-media.ts"],"sourcesContent":["// Send media tool - allows sending local files as media\nimport { Type } from '@sinclair/typebox';\nimport { readFile } from 'fs/promises';\nimport { basename } from 'node:path';\nimport { AgentTool, type AgentToolResult } from '@earendil-works/pi-agent-core';\nimport { checkFileSafety } from '../prompt/safety.js';\nimport { resolvePathUnderWorkspace } from './tool-paths.js';\nimport type { MessageBus, OutboundMessage } from '../../infra/bus/index.js';\n\nconst SendMediaSchema = Type.Object({\n  filePath: Type.String({\n    description:\n      'File to send. Relative paths are under the current agent workspace; absolute paths are used as given.',\n  }),\n  mediaType: Type.Optional(Type.Enum({\n    photo: 'photo',\n    video: 'video',\n    audio: 'audio',\n    document: 'document',\n  }, { description: 'Type of media to send (auto-detected if not specified)' })),\n  caption: Type.Optional(Type.String({ description: 'Caption for the media' })),\n});\n\ninterface MessageContext {\n  channel: string;\n  chatId: string;\n}\n\ntype SendMediaParams = {\n  filePath: string;\n  mediaType?: 'photo' | 'video' | 'audio' | 'document';\n  caption?: string;\n};\n\n// Detect media type from file extension\nfunction detectMediaType(filePath: string): 'photo' | 'video' | 'audio' | 'document' {\n  const ext = filePath.split('.').pop()?.toLowerCase();\n  const imageExts = ['jpg', 'jpeg', 'png', 'gif', 'webp', 'bmp', 'svg'];\n  const videoExts = ['mp4', 'mov', 'avi', 'webm', 'mkv'];\n  const audioExts = ['mp3', 'wav', 'ogg', 'm4a', 'flac'];\n\n  if (imageExts.includes(ext || '')) return 'photo';\n  if (videoExts.includes(ext || '')) return 'video';\n  if (audioExts.includes(ext || '')) return 'audio';\n  return 'document';\n}\n\n// Detect MIME type from file extension\nfunction detectMimeType(filePath: string): string {\n  const ext = filePath.split('.').pop()?.toLowerCase();\n  const mimeMap: Record<string, string> = {\n    jpg: 'image/jpeg',\n    jpeg: 'image/jpeg',\n    png: 'image/png',\n    gif: 'image/gif',\n    webp: 'image/webp',\n    bmp: 'image/bmp',\n    svg: 'image/svg+xml',\n    mp4: 'video/mp4',\n    mov: 'video/quicktime',\n    avi: 'video/x-msvideo',\n    webm: 'video/webm',\n    mp3: 'audio/mpeg',\n    wav: 'audio/wav',\n    ogg: 'audio/ogg',\n    m4a: 'audio/mp4',\n    flac: 'audio/flac',\n    pdf: 'application/pdf',\n    doc: 'application/msword',\n    docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',\n    txt: 'text/plain',\n    zip: 'application/zip',\n    rar: 'application/x-rar-compressed',\n  };\n  return mimeMap[ext || ''] || 'application/octet-stream';\n}\n\nexport function createSendMediaTool(\n  workspace: string,\n  bus: MessageBus,\n  getContext: () => MessageContext | null,\n): AgentTool {\n  return {\n    name: 'send_media',\n    description:\n      'Send a media file (photo, video, audio, document) to the current conversation. Relative paths resolve to the current agent workspace (same as read_file).',\n    parameters: SendMediaSchema,\n    label: '📎 Send Media',\n\n    async execute(\n      _toolCallId: string,\n      params: any,\n      _signal?: AbortSignal,\n    ): Promise<AgentToolResult<{}>> {\n      const p = params as SendMediaParams;\n      const ctx = getContext();\n      if (!ctx) {\n        return {\n          content: [{ type: 'text', text: 'Error: No active conversation context' }],\n          details: {},\n        };\n      }\n\n      const resolved = resolvePathUnderWorkspace(p.filePath, workspace);\n      const safety = checkFileSafety('read', resolved);\n      if (!safety.allowed) {\n        return {\n          content: [{ type: 'text', text: `🚫 ${safety.message}` }],\n          details: {},\n        };\n      }\n\n      try {\n        const fileBuffer = await readFile(resolved);\n        const base64 = fileBuffer.toString('base64');\n        const mimeType = detectMimeType(resolved);\n        const mediaType = p.mediaType || detectMediaType(resolved);\n\n        // Create data URL\n        const dataUrl = `data:${mimeType};base64,${base64}`;\n\n        const msg: OutboundMessage = {\n          channel: ctx.channel,\n          chat_id: ctx.chatId,\n          content: p.caption || '',\n          mediaUrl: dataUrl,\n          mediaType,\n        };\n\n        await bus.publishOutbound(msg);\n\n        const fileName = basename(resolved);\n        return {\n          content: [{ type: 'text', text: `✅ Media sent: ${fileName} (${mediaType})` }],\n          details: { filePath: resolved, mediaType },\n        };\n      } catch (error) {\n        const errorMessage = error instanceof Error ? error.message : String(error);\n        return {\n          content: [{ type: 'text', text: `Error sending media: ${errorMessage}` }],\n          details: { error: errorMessage },\n        };\n      }\n    },\n  } as any;\n}\n"],"mappings":";;;;;;AASA,MAAM,kBAAkB,KAAK,OAAO;CAClC,UAAU,KAAK,OAAO,EACpB,aACE,yGACH,CAAC;CACF,WAAW,KAAK,SAAS,KAAK,KAAK;EACjC,OAAO;EACP,OAAO;EACP,OAAO;EACP,UAAU;EACX,EAAE,EAAE,aAAa,0DAA0D,CAAC,CAAC;CAC9E,SAAS,KAAK,SAAS,KAAK,OAAO,EAAE,aAAa,yBAAyB,CAAC,CAAC;CAC9E,CAAC;AAcF,SAAS,gBAAgB,UAA4D;CACnF,MAAM,MAAM,SAAS,MAAM,IAAI,CAAC,KAAK,EAAE,aAAa;CACpD,MAAM,YAAY;EAAC;EAAO;EAAQ;EAAO;EAAO;EAAQ;EAAO;EAAM;CACrE,MAAM,YAAY;EAAC;EAAO;EAAO;EAAO;EAAQ;EAAM;CACtD,MAAM,YAAY;EAAC;EAAO;EAAO;EAAO;EAAO;EAAO;AAEtD,KAAI,UAAU,SAAS,OAAO,GAAG,CAAE,QAAO;AAC1C,KAAI,UAAU,SAAS,OAAO,GAAG,CAAE,QAAO;AAC1C,KAAI,UAAU,SAAS,OAAO,GAAG,CAAE,QAAO;AAC1C,QAAO;;AAIT,SAAS,eAAe,UAA0B;AA0BhD,QAAO;EAvBL,KAAK;EACL,MAAM;EACN,KAAK;EACL,KAAK;EACL,MAAM;EACN,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,MAAM;EACN,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,MAAM;EACN,KAAK;EACL,KAAK;EACL,MAAM;EACN,KAAK;EACL,KAAK;EACL,KAAK;EAEO,CAzBF,SAAS,MAAM,IAAI,CAAC,KAAK,EAAE,aAAa,IAyB9B,OAAO;;AAG/B,SAAgB,oBACd,WACA,KACA,YACW;AACX,QAAO;EACL,MAAM;EACN,aACE;EACF,YAAY;EACZ,OAAO;EAEP,MAAM,QACJ,aACA,QACA,SAC8B;GAC9B,MAAM,IAAI;GACV,MAAM,MAAM,YAAY;AACxB,OAAI,CAAC,IACH,QAAO;IACL,SAAS,CAAC;KAAE,MAAM;KAAQ,MAAM;KAAyC,CAAC;IAC1E,SAAS,EAAE;IACZ;GAGH,MAAM,WAAW,0BAA0B,EAAE,UAAU,UAAU;GACjE,MAAM,SAAS,gBAAgB,QAAQ,SAAS;AAChD,OAAI,CAAC,OAAO,QACV,QAAO;IACL,SAAS,CAAC;KAAE,MAAM;KAAQ,MAAM,MAAM,OAAO;KAAW,CAAC;IACzD,SAAS,EAAE;IACZ;AAGH,OAAI;IAEF,MAAM,UAAS,MADU,SAAS,SAAS,EACjB,SAAS,SAAS;IAC5C,MAAM,WAAW,eAAe,SAAS;IACzC,MAAM,YAAY,EAAE,aAAa,gBAAgB,SAAS;IAG1D,MAAM,UAAU,QAAQ,SAAS,UAAU;IAE3C,MAAM,MAAuB;KAC3B,SAAS,IAAI;KACb,SAAS,IAAI;KACb,SAAS,EAAE,WAAW;KACtB,UAAU;KACV;KACD;AAED,UAAM,IAAI,gBAAgB,IAAI;AAG9B,WAAO;KACL,SAAS,CAAC;MAAE,MAAM;MAAQ,MAAM,iBAFjB,SAAS,SAEiC,CAAC,IAAI,UAAU;MAAI,CAAC;KAC7E,SAAS;MAAE,UAAU;MAAU;MAAW;KAC3C;YACM,OAAO;IACd,MAAM,eAAe,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;AAC3E,WAAO;KACL,SAAS,CAAC;MAAE,MAAM;MAAQ,MAAM,wBAAwB;MAAgB,CAAC;KACzE,SAAS,EAAE,OAAO,cAAc;KACjC;;;EAGN"}
+{"version":3,"file":"send-media.js","names":[],"sources":["../../../../src/agent/tools/send-media.ts"],"sourcesContent":["// Send media tool - allows sending local files as media\nimport { Type } from '@sinclair/typebox';\nimport { readFile } from 'fs/promises';\nimport { basename } from 'node:path';\nimport { AgentTool, type AgentToolResult } from '@earendil-works/pi-agent-core';\nimport { checkFileSafety } from '../prompt/safety.js';\nimport { resolvePathUnderWorkspace } from './tool-paths.js';\nimport type { MessageBus, OutboundMessage } from '../../infra/bus/index.js';\n\nconst SendMediaSchema = Type.Object({\n  filePath: Type.String({\n    description:\n      'File to send. Relative paths are under the current agent workspace; absolute paths are used as given.',\n  }),\n  mediaType: Type.Optional(Type.Enum({\n    photo: 'photo',\n    video: 'video',\n    audio: 'audio',\n    document: 'document',\n  }, { description: 'Type of media to send (auto-detected if not specified)' })),\n  caption: Type.Optional(Type.String({ description: 'Caption for the media' })),\n});\n\ninterface MessageContext {\n  channel: string;\n  chatId: string;\n}\n\ntype SendMediaParams = {\n  filePath: string;\n  mediaType?: 'photo' | 'video' | 'audio' | 'document';\n  caption?: string;\n};\n\n// Detect media type from file extension\nfunction detectMediaType(filePath: string): 'photo' | 'video' | 'audio' | 'document' {\n  const ext = filePath.split('.').pop()?.toLowerCase();\n  const imageExts = ['jpg', 'jpeg', 'png', 'gif', 'webp', 'bmp'];\n  const videoExts = ['mp4', 'mov', 'avi', 'webm', 'mkv'];\n  const audioExts = ['mp3', 'wav', 'ogg', 'm4a', 'flac'];\n\n  if (imageExts.includes(ext || '')) return 'photo';\n  if (videoExts.includes(ext || '')) return 'video';\n  if (audioExts.includes(ext || '')) return 'audio';\n  return 'document';\n}\n\n// Detect MIME type from file extension\nfunction detectMimeType(filePath: string): string {\n  const ext = filePath.split('.').pop()?.toLowerCase();\n  const mimeMap: Record<string, string> = {\n    jpg: 'image/jpeg',\n    jpeg: 'image/jpeg',\n    png: 'image/png',\n    gif: 'image/gif',\n    webp: 'image/webp',\n    bmp: 'image/bmp',\n    svg: 'image/svg+xml',\n    mp4: 'video/mp4',\n    mov: 'video/quicktime',\n    avi: 'video/x-msvideo',\n    webm: 'video/webm',\n    mp3: 'audio/mpeg',\n    wav: 'audio/wav',\n    ogg: 'audio/ogg',\n    m4a: 'audio/mp4',\n    flac: 'audio/flac',\n    pdf: 'application/pdf',\n    doc: 'application/msword',\n    docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',\n    txt: 'text/plain',\n    zip: 'application/zip',\n    rar: 'application/x-rar-compressed',\n  };\n  return mimeMap[ext || ''] || 'application/octet-stream';\n}\n\nexport function createSendMediaTool(\n  workspace: string,\n  bus: MessageBus,\n  getContext: () => MessageContext | null,\n): AgentTool {\n  return {\n    name: 'send_media',\n    description:\n      'Send a media file (photo, video, audio, document) to the current conversation. Relative paths resolve to the current agent workspace (same as read_file).',\n    parameters: SendMediaSchema,\n    label: '📎 Send Media',\n\n    async execute(\n      _toolCallId: string,\n      params: any,\n      _signal?: AbortSignal,\n    ): Promise<AgentToolResult<{}>> {\n      const p = params as SendMediaParams;\n      const ctx = getContext();\n      if (!ctx) {\n        return {\n          content: [{ type: 'text', text: 'Error: No active conversation context' }],\n          details: {},\n        };\n      }\n\n      const resolved = resolvePathUnderWorkspace(p.filePath, workspace);\n      const safety = checkFileSafety('read', resolved);\n      if (!safety.allowed) {\n        return {\n          content: [{ type: 'text', text: `🚫 ${safety.message}` }],\n          details: {},\n        };\n      }\n\n      try {\n        const fileBuffer = await readFile(resolved);\n        const base64 = fileBuffer.toString('base64');\n        const mimeType = detectMimeType(resolved);\n        const mediaType = p.mediaType || detectMediaType(resolved);\n\n        // Create data URL\n        const dataUrl = `data:${mimeType};base64,${base64}`;\n\n        const msg: OutboundMessage = {\n          channel: ctx.channel,\n          chat_id: ctx.chatId,\n          content: p.caption || '',\n          mediaUrl: dataUrl,\n          mediaType,\n        };\n\n        await bus.publishOutbound(msg);\n\n        const fileName = basename(resolved);\n        return {\n          content: [{ type: 'text', text: `✅ Media sent: ${fileName} (${mediaType})` }],\n          details: { filePath: resolved, mediaType },\n        };\n      } catch (error) {\n        const errorMessage = error instanceof Error ? error.message : String(error);\n        return {\n          content: [{ type: 'text', text: `Error sending media: ${errorMessage}` }],\n          details: { error: errorMessage },\n        };\n      }\n    },\n  } as any;\n}\n"],"mappings":";;;;;;AASA,MAAM,kBAAkB,KAAK,OAAO;CAClC,UAAU,KAAK,OAAO,EACpB,aACE,yGACH,CAAC;CACF,WAAW,KAAK,SAAS,KAAK,KAAK;EACjC,OAAO;EACP,OAAO;EACP,OAAO;EACP,UAAU;EACX,EAAE,EAAE,aAAa,0DAA0D,CAAC,CAAC;CAC9E,SAAS,KAAK,SAAS,KAAK,OAAO,EAAE,aAAa,yBAAyB,CAAC,CAAC;CAC9E,CAAC;AAcF,SAAS,gBAAgB,UAA4D;CACnF,MAAM,MAAM,SAAS,MAAM,IAAI,CAAC,KAAK,EAAE,aAAa;CACpD,MAAM,YAAY;EAAC;EAAO;EAAQ;EAAO;EAAO;EAAQ;EAAM;CAC9D,MAAM,YAAY;EAAC;EAAO;EAAO;EAAO;EAAQ;EAAM;CACtD,MAAM,YAAY;EAAC;EAAO;EAAO;EAAO;EAAO;EAAO;AAEtD,KAAI,UAAU,SAAS,OAAO,GAAG,CAAE,QAAO;AAC1C,KAAI,UAAU,SAAS,OAAO,GAAG,CAAE,QAAO;AAC1C,KAAI,UAAU,SAAS,OAAO,GAAG,CAAE,QAAO;AAC1C,QAAO;;AAIT,SAAS,eAAe,UAA0B;AA0BhD,QAAO;EAvBL,KAAK;EACL,MAAM;EACN,KAAK;EACL,KAAK;EACL,MAAM;EACN,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,MAAM;EACN,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,MAAM;EACN,KAAK;EACL,KAAK;EACL,MAAM;EACN,KAAK;EACL,KAAK;EACL,KAAK;EAEO,CAzBF,SAAS,MAAM,IAAI,CAAC,KAAK,EAAE,aAAa,IAyB9B,OAAO;;AAG/B,SAAgB,oBACd,WACA,KACA,YACW;AACX,QAAO;EACL,MAAM;EACN,aACE;EACF,YAAY;EACZ,OAAO;EAEP,MAAM,QACJ,aACA,QACA,SAC8B;GAC9B,MAAM,IAAI;GACV,MAAM,MAAM,YAAY;AACxB,OAAI,CAAC,IACH,QAAO;IACL,SAAS,CAAC;KAAE,MAAM;KAAQ,MAAM;KAAyC,CAAC;IAC1E,SAAS,EAAE;IACZ;GAGH,MAAM,WAAW,0BAA0B,EAAE,UAAU,UAAU;GACjE,MAAM,SAAS,gBAAgB,QAAQ,SAAS;AAChD,OAAI,CAAC,OAAO,QACV,QAAO;IACL,SAAS,CAAC;KAAE,MAAM;KAAQ,MAAM,MAAM,OAAO;KAAW,CAAC;IACzD,SAAS,EAAE;IACZ;AAGH,OAAI;IAEF,MAAM,UAAS,MADU,SAAS,SAAS,EACjB,SAAS,SAAS;IAC5C,MAAM,WAAW,eAAe,SAAS;IACzC,MAAM,YAAY,EAAE,aAAa,gBAAgB,SAAS;IAG1D,MAAM,UAAU,QAAQ,SAAS,UAAU;IAE3C,MAAM,MAAuB;KAC3B,SAAS,IAAI;KACb,SAAS,IAAI;KACb,SAAS,EAAE,WAAW;KACtB,UAAU;KACV;KACD;AAED,UAAM,IAAI,gBAAgB,IAAI;AAG9B,WAAO;KACL,SAAS,CAAC;MAAE,MAAM;MAAQ,MAAM,iBAFjB,SAAS,SAEiC,CAAC,IAAI,UAAU;MAAI,CAAC;KAC7E,SAAS;MAAE,UAAU;MAAU;MAAW;KAC3C;YACM,OAAO;IACd,MAAM,eAAe,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;AAC3E,WAAO;KACL,SAAS,CAAC;MAAE,MAAM;MAAQ,MAAM,wBAAwB;MAAgB,CAAC;KACzE,SAAS,EAAE,OAAO,cAAc;KACjC;;;EAGN"}

package/dist/src/agent/tools/session-search-tool.js

@@ -2,8 +2,8 @@ import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
 import { getDefaultModelSync, init_providers, resolveModel } from "../../providers/index.js";
 import { readAgentMessageContent } from "../memory/agent-message-access.js";
-import { complete } from "@earendil-works/pi-ai";
 import { Type } from "@sinclair/typebox";
+import { complete } from "@earendil-works/pi-ai";
 //#region src/agent/tools/session-search-tool.ts
 init_providers();
 init_logger();

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

@@ -1,6 +1,6 @@
 import { evaluateExecPolicy } from "../sandbox/exec-policy.js";
-import { spawn } from "child_process";
 import { Type } from "@sinclair/typebox";
+import { spawn } from "child_process";
 //#region src/agent/tools/shell.ts
 const MAX_SHELL_TIMEOUT = 300;
 const DEFAULT_MAX_BYTES = 50 * 1024;

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

@@ -1,7 +1,7 @@
 import { resolveStateDir } from "../../config/paths-state.js";
 import { init_paths } from "../../config/paths.js";
 import { DEFAULT_MAX_BYTES, formatSize, truncateHead } from "./truncate.js";
-import { createSkillConfigManager, isSkillEnabled } from "../skills/config.js";
+import { createSkillConfigManager, isSkillEnabled, resolveSkillConfig } from "../skills/config.js";
 import { resolveSkillReadablePath } from "../skills/skill-view-path.js";
 import { readFileSync, statSync } from "fs";
 import { Type } from "@sinclair/typebox";
@@ -76,17 +76,43 @@ function createSkillViewTool(deps) {
 			if (!skill) return {
 				content: [{
 					type: "text",
-					text: `Skill not found: "${p.name}". Use skills_list to see available names.`
+					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.`
 				}],
-				details: {}
+				details: {
+					errorCode: "skill_not_found",
+					skillName: p.name
+				}
 			};
 			const skillsConfig = createSkillConfigManager(resolveStateDir()).load();
-			if (skill.disableModelInvocation || !isSkillEnabled(skill, skillsConfig)) return {
+			if (resolveSkillConfig(skill, skillsConfig).enabled === false) return {
 				content: [{
 					type: "text",
-					text: `Skill "${skill.name}" is disabled or requirements are not met.`
+					text: `Skill "${skill.name}" is installed but disabled. Enable it in Skills settings before using it.`
 				}],
-				details: {}
+				details: {
+					errorCode: "skill_disabled",
+					skillName: skill.name
+				}
+			};
+			if (skill.disableModelInvocation) return {
+				content: [{
+					type: "text",
+					text: `Skill "${skill.name}" is installed, but it is not available for model invocation.`
+				}],
+				details: {
+					errorCode: "skill_model_invocation_disabled",
+					skillName: skill.name
+				}
+			};
+			if (!isSkillEnabled(skill, skillsConfig)) return {
+				content: [{
+					type: "text",
+					text: `Skill "${skill.name}" is installed, but its requirements are not met.`
+				}],
+				details: {
+					errorCode: "skill_requirements_unmet",
+					skillName: skill.name
+				}
 			};
 			const idx = deps.getSkillIndexingContext?.();
 			if (!mgr.getEnabledSkillsForAgentSession({
@@ -95,9 +121,12 @@ function createSkillViewTool(deps) {
 			}).some((s) => s.name === skill.name)) return {
 				content: [{
 					type: "text",
-					text: `Skill "${skill.name}" is not available in this session (tool gating or allowlist).`
+					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.`
 				}],
-				details: {}
+				details: {
+					errorCode: "skill_agent_denied",
+					skillName: skill.name
+				}
 			};
 			const resolved = resolveSkillReadablePath(skill, p.path);
 			if (resolved.ok === false) return {

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/tools/web-extract.js

@@ -1,9 +1,9 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
-import { getDefaultModelSync, init_providers, resolveModel } from "../../providers/index.js";
 import { checkUrlSafety, checkWebsiteBlocklist, cleanBase64Images } from "./url-safety.js";
-import { complete } from "@earendil-works/pi-ai";
+import { getDefaultModelSync, init_providers, resolveModel } from "../../providers/index.js";
 import { Type } from "@sinclair/typebox";
+import { complete } from "@earendil-works/pi-ai";
 //#region src/agent/tools/web-extract.ts
 init_providers();
 init_logger();

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

@@ -1,6 +1,6 @@
+import { checkUrlSafety, checkWebsiteBlocklist } from "./url-safety.js";
 import { SearchProviderRegistry } from "./search/registry.js";
 import { resolveWebSearchConfig } from "./search/resolve-config.js";
-import { checkUrlSafety, checkWebsiteBlocklist } from "./url-safety.js";
 import { Type } from "@sinclair/typebox";
 //#region src/agent/tools/web.ts
 const WebSearchSchema = Type.Object({

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);