@pikku/core 0.12.8 → 0.12.10

package/src/wirings/ai-agent/agent-dynamic-workflow.ts

@@ -13,92 +13,222 @@ import {
   computeEntryNodeIds,
 } from '../workflow/graph/graph-validation.js'
 
-export function buildDynamicWorkflowInstructions(tools: string[], mode: 'read' | 'always' | 'ask'): string {
-  if (mode === 'read') {
-    return (
-      '\n\n## Existing Workflows\n\n' +
-      'You can list and execute previously saved workflows using listAgentWorkflows and executeAgentWorkflow.\n' +
-      'Use listAgentWorkflows to discover what\'s available, then executeAgentWorkflow to run them.'
-    )
+function formatSchemaType(schema: any, depth = 0): string {
+  if (!schema) return 'any'
+  if (schema.enum)
+    return schema.enum.map((v: any) => JSON.stringify(v)).join(' | ')
+  if (schema.type === 'array') {
+    const itemType = schema.items
+      ? formatSchemaType(schema.items, depth + 1)
+      : 'any'
+    return `${itemType}[]`
   }
+  if (schema.type === 'object' && schema.properties) {
+    if (depth > 1) return 'object'
+    const fields = Object.entries(schema.properties)
+      .map(([k, v]: [string, any]) => `${k}: ${formatSchemaType(v, depth + 1)}`)
+      .join(', ')
+    return `{${fields}}`
+  }
+  return schema.type || 'any'
+}
 
-  const modeGuidance = mode === 'always'
-    ? 'When a user requests a complex multi-step task, prefer creating a workflow over making sequential tool calls.\n' +
-      'Check if a suitable workflow already exists with listAgentWorkflows first.\n' +
-      'If none exists, create one with createAgentWorkflow, save with saveAgentWorkflow, then execute.\n\n'
-    : 'When you receive a request that would benefit from a reusable multi-step workflow,\n' +
-      'suggest creating one to the user. Explain the benefits (reusability, reliability,\n' +
-      'can run in background) and wait for confirmation before creating.\n' +
-      'Do NOT create workflows automatically — always propose and get user approval first.\n' +
-      'For one-off tasks, just use the tools directly.\n\n'
-
-  const toolSchemaLines: string[] = []
-
-  for (const toolName of tools) {
-    let fnMeta: any
-    let schemas: Map<string, any>
+function resolveToolMetaForWorkflow(toolName: string): {
+  fnMeta: any
+  inputSchema: any
+  outputSchema: any
+  schemas: Map<string, any>
+} | null {
+  const resolved = toolName.includes(':') ? resolveNamespace(toolName) : null
+  let fnMeta: any
+  let schemas: Map<string, any>
+
+  if (resolved) {
+    fnMeta = pikkuState(resolved.package, 'function', 'meta')[resolved.function]
+    schemas = pikkuState(resolved.package, 'misc', 'schemas')
+  } else {
+    const rpcMeta = pikkuState(null, 'rpc', 'meta')
+    const pikkuFuncId = rpcMeta[toolName]
+    if (!pikkuFuncId) return null
+    fnMeta = pikkuState(null, 'function', 'meta')[pikkuFuncId]
+    schemas = pikkuState(null, 'misc', 'schemas')
+  }
 
-    const resolved = toolName.includes(':') ? resolveNamespace(toolName) : null
+  if (!fnMeta) return null
 
-    if (resolved) {
-      fnMeta = pikkuState(resolved.package, 'function', 'meta')[
-        resolved.function
-      ]
-      schemas = pikkuState(resolved.package, 'misc', 'schemas')
-    } else {
-      const rpcMeta = pikkuState(null, 'rpc', 'meta')
-      const pikkuFuncId = rpcMeta[toolName]
-      if (!pikkuFuncId) continue
-      fnMeta = pikkuState(null, 'function', 'meta')[pikkuFuncId]
-      schemas = pikkuState(null, 'misc', 'schemas')
-    }
+  const inputSchema = fnMeta.inputSchemaName
+    ? schemas.get(fnMeta.inputSchemaName)
+    : null
+  const outputSchema = fnMeta.outputSchemaName
+    ? schemas.get(fnMeta.outputSchemaName)
+    : null
 
-    if (!fnMeta) continue
+  return { fnMeta, inputSchema, outputSchema, schemas }
+}
 
-    const inputSchema = fnMeta.inputSchemaName
-      ? schemas.get(fnMeta.inputSchemaName)
-      : null
-    const outputSchema = fnMeta.outputSchemaName
-      ? schemas.get(fnMeta.outputSchemaName)
-      : null
+function buildDetailedToolSchemas(toolNames: string[]): string {
+  const lines: string[] = []
+  for (const toolName of toolNames) {
+    const meta = resolveToolMetaForWorkflow(toolName)
+    if (!meta) continue
+    const { inputSchema, outputSchema } = meta
 
-    const toolDescription = fnMeta.description || fnMeta.title || ''
     const inputProps = inputSchema?.properties
       ? Object.entries(inputSchema.properties)
           .map(
             ([k, v]: [string, any]) =>
-              `${k}${inputSchema.required?.includes(k) ? '' : '?'}: ${v.type || 'any'}`
+              `${k}${inputSchema.required?.includes(k) ? '' : '?'}: ${formatSchemaType(v)}`
           )
           .join(', ')
       : ''
-    const outputProps = outputSchema?.properties
-      ? Object.entries(outputSchema.properties)
-          .map(([k, v]: [string, any]) => `${k}: ${v.type || 'any'}`)
-          .join(', ')
-      : 'any'
+    const outputPaths = outputSchema ? collectOutputPaths(outputSchema) : []
+
+    lines.push(
+      `**${toolName}**\n` +
+        `  input: {${inputProps}}\n` +
+        (outputPaths.length > 0
+          ? `  output paths: ${outputPaths.join(', ')}`
+          : `  output: void`)
+    )
+  }
+  return lines.join('\n')
+}
+
+function collectOutputPaths(schema: any, prefix = ''): string[] {
+  if (!schema?.properties) return []
+  const paths: string[] = []
+  for (const [key, prop] of Object.entries(schema.properties) as [
+    string,
+    any,
+  ][]) {
+    const path = prefix ? `${prefix}.${key}` : key
+    const type = prop.type || 'any'
+    if (prop.type === 'object' && prop.properties) {
+      paths.push(...collectOutputPaths(prop, path))
+    } else {
+      paths.push(`${path}: ${type}`)
+    }
+  }
+  return paths
+}
+
+export function buildDynamicWorkflowInstructions(
+  tools: string[],
+  mode: 'read' | 'always' | 'ask'
+): string {
+  if (mode === 'read') {
+    return (
+      '\n\n## Existing Workflows\n\n' +
+      'You can list and execute previously saved workflows using listAgentWorkflows and executeAgentWorkflow.\n' +
+      "Use listAgentWorkflows to discover what's available, then executeAgentWorkflow to run them."
+    )
+  }
+
+  const modeGuidance =
+    mode === 'always'
+      ? 'When a user requests a complex multi-step task, prefer creating a workflow over making sequential tool calls.\n' +
+        'Check if a suitable workflow already exists with listAgentWorkflows first.\n' +
+        'If none exists, create one with createAgentWorkflow, save with saveAgentWorkflow, then execute.\n\n'
+      : 'When you receive a request that would benefit from a reusable multi-step workflow,\n' +
+        'suggest creating one to the user. Explain the benefits (reusability, reliability,\n' +
+        'can run in background) and wait for confirmation before creating.\n' +
+        'Do NOT create workflows automatically — always propose and get user approval first.\n' +
+        'For one-off tasks, just use the tools directly.\n\n'
+
+  const toolSummaryLines: string[] = []
+
+  for (const toolName of tools) {
+    const meta = resolveToolMetaForWorkflow(toolName)
+    if (!meta) continue
+    const { fnMeta, inputSchema, outputSchema } = meta
 
-    toolSchemaLines.push(
-      `- ${toolName}(input: {${inputProps}}) → {${outputProps}}${toolDescription ? ` — ${toolDescription}` : ''}`
+    const desc = fnMeta.description || fnMeta.title || ''
+    const inputFields = inputSchema?.properties
+      ? Object.keys(inputSchema.properties).join(', ')
+      : ''
+    const outputFields = outputSchema?.properties
+      ? Object.keys(outputSchema.properties).join(', ')
+      : ''
+
+    toolSummaryLines.push(
+      `| \`${toolName}\` | ${desc || '-'} | ${inputFields || '-'} | ${outputFields || '-'} |`
     )
   }
 
-  return (
-    '\n\n## Workflow Creation\n\n' +
-    modeGuidance +
-    'You can create workflows that chain your tools together. Use createAgentWorkflow to validate and preview a workflow, then saveAgentWorkflow to save it, then executeAgentWorkflow to run it.\n\n' +
-    '### Tool Schemas:\n' +
-    toolSchemaLines.join('\n') +
-    '\n\n### Workflow Format:\n' +
-    '- Each node has: rpcName (tool name), input (with $ref to wire outputs), next (flow control), onError\n' +
-    '- Use {"$ref": "nodeId", "path": "fieldName"} to wire a previous node\'s output field to this node\'s input\n' +
-    '- Use {"$ref": "trigger", "path": "fieldName"} to extract a field from the workflow\'s trigger input. IMPORTANT: Always include "path" — never pass {"$ref": "trigger"} without "path", or the entire trigger object will be used as the value.\n' +
-    '- Use {"$ref": "nodeId", "path": "fieldName"} to extract a field from a previous node\'s output. Always include "path" to select the specific field.\n' +
-    '- next can be a string (single next node), array (parallel), or object {branchKey: nextNode} for branching\n' +
-    '\n### Example (add todo from trigger title, then list):\n' +
-    '{"add":{"rpcName":"todos:addTodo","input":{"title":{"$ref":"trigger","path":"title"}},"next":"list"},"list":{"rpcName":"todos:listTodos","input":{}}}\n' +
-    '\n### Example (add todo, sleep, complete using addTodo result id):\n' +
-    '{"add":{"rpcName":"todos:addTodo","input":{"title":{"$ref":"trigger","path":"title"}},"next":"wait"},"wait":{"rpcName":"sleep","input":{"seconds":5},"next":"complete"},"complete":{"rpcName":"todos:completeTodo","input":{"id":{"$ref":"add","path":"id"}}}}'
-  )
+  const sections: string[] = [
+    '\n\n## Workflow Creation\n',
+    modeGuidance,
+
+    '### When to Create a Workflow\n' +
+      'Create a workflow when:\n' +
+      '- The task has 2+ steps with data dependencies between them\n' +
+      '- The task will be repeated (workflows are reusable)\n' +
+      '- Steps can fail independently and need error handling\n' +
+      '- Steps can run in parallel for better performance\n' +
+      'Do NOT create a workflow for single tool calls — just call the tool directly.\n',
+
+    '### Process\n' +
+      '1. Check if a suitable workflow exists: `listAgentWorkflows`\n' +
+      '2. If the request is too vague to build a reliable workflow, ask the user to be more specific. For example, if a user says "make a workflow that does stuff with my data" — ask them what steps they need and what data flows between them.\n' +
+      '3. Plan the graph: identify steps, dependencies, parallel paths, and failure modes\n' +
+      '4. Create and validate: `createAgentWorkflow` — if validation fails, fix the errors and retry\n' +
+      '5. Present the workflow to the user and get approval\n' +
+      '6. Activate: `saveAgentWorkflow`\n' +
+      '7. Run: `executeAgentWorkflow`\n',
+
+    '### Available Tools\n' +
+      '| Tool | Description | Input fields | Output fields |\n' +
+      '|------|-------------|-------------|---------------|\n' +
+      toolSummaryLines.join('\n') +
+      '\n\n' +
+      'Full schemas (input types, output paths) are returned by `createAgentWorkflow` after validation.\n',
+
+    '### Graph Format Reference\n\n' +
+      '**Node:** `{ rpcName, input?, next?, onError? }`\n\n' +
+      '**Data wiring (input field values):**\n' +
+      '- `{"$ref": "trigger", "path": "fieldName"}` — extract field from trigger input (ALWAYS include `path`)\n' +
+      '- `{"$ref": "nodeId", "path": "fieldName"}` — extract field from a previous node\'s output (ALWAYS include `path`)\n' +
+      '- `path` supports dot notation for nested fields — use the "output paths" listed above to find the correct path\n' +
+      '- Example: if a tool\'s output paths show `todo.id: string`, use `{"$ref": "nodeId", "path": "todo.id"}`\n' +
+      '- `{"$template": {"parts": ["Hello ", "!"], "expressions": [{"$ref": "trigger", "path": "name"}]}}` — string interpolation\n' +
+      '- Static values passed directly: `{"count": 10}`\n\n' +
+      '**Flow control (`next`):**\n' +
+      '- `"next": "b"` — sequential\n' +
+      '- `"next": ["b", "c"]` — parallel fan-out\n' +
+      '- `"next": {"ok": "b", "fail": "c"}` — conditional branch (node calls `graph.branch("ok")` at runtime)\n' +
+      '- Omit `next` for terminal nodes. Entry nodes are auto-detected.\n\n' +
+      '**Error handling:**\n' +
+      '- `"onError": "handler"` — route to error handler on failure\n' +
+      '- Error handler receives `{ error: { message: string } }` as input\n' +
+      '- Without `onError`, a node failure fails the entire workflow\n\n' +
+      '**Sub-workflows:** if `rpcName` matches an existing workflow name, it runs as a child workflow with its own execution context.\n\n' +
+      '**Trigger input:** the workflow receives input when executed. Entry nodes extract fields via `$ref: "trigger"`. Document what fields your workflow expects in the `description`.\n',
+
+    '### Design Principles\n' +
+      '1. **Map dependencies first** — before writing nodes, identify which steps depend on which outputs\n' +
+      '2. **Parallelize independent work** — steps with no data dependency should fan out via array `next`\n' +
+      '3. **Add error handlers for external calls** — any node calling an external service should have `onError`\n' +
+      "4. **Minimize blast radius** — isolate risky nodes so their failure doesn't cascade\n" +
+      '5. **Name nodes by intent** — `fetchUsers`, `sendAlert` not `step1`, `step2`\n' +
+      '6. **Keep graphs shallow** — prefer wide parallel graphs over deep sequential chains when possible\n',
+
+    '### Common Mistakes\n' +
+      '- `{"$ref": "trigger"}` without `path` — passes entire object, use `{"$ref": "trigger", "path": "field"}`\n' +
+      '- Wrong path depth: if output paths show `todo.id`, use `"path": "todo.id"` not `"path": "id"`\n' +
+      '- Type mismatch: wiring a string output to a number input\n' +
+      '- Dangling `onError`/`next` references to nodes not in the graph\n' +
+      '- Cycles: if A→B→A, there are no entry nodes\n',
+
+    '### Examples\n\n' +
+      '**Sequential with nested output path (if addTodo output paths show `todo.id`):**\n' +
+      '```json\n{"add":{"rpcName":"addTodo","input":{"title":{"$ref":"trigger","path":"title"}},"next":"complete"},"complete":{"rpcName":"completeTodo","input":{"id":{"$ref":"add","path":"todo.id"}}}}\n```\n\n' +
+      '**Error handling:**\n' +
+      '```json\n{"deploy":{"rpcName":"deploy","input":{"env":{"$ref":"trigger","path":"env"}},"next":"notify","onError":"rollback"},"notify":{"rpcName":"alert","input":{"message":"Deployed"}},"rollback":{"rpcName":"rollback","input":{},"next":"alertFail"},"alertFail":{"rpcName":"alert","input":{"message":"Rolled back"}}}\n```\n\n' +
+      '**Parallel fan-out:**\n' +
+      '```json\n{"fetchA":{"rpcName":"getA","input":{},"next":"combine"},"fetchB":{"rpcName":"getB","input":{},"next":"combine"},"combine":{"rpcName":"graph:merge","input":{"items":[{"$ref":"fetchA","path":"data"},{"$ref":"fetchB","path":"data"}]}}}\n```',
+  ]
+
+  return sections.join('\n')
 }
 
 export function buildWorkflowTools(
@@ -112,200 +242,211 @@ export function buildWorkflowTools(
   const tools: AIAgentToolDef[] = []
 
   if (mode !== 'read') {
-  tools.push({
-    name: 'createAgentWorkflow',
-    description:
-      'Validate and create a draft workflow graph that chains tools together. Call saveAgentWorkflow to activate it after the user approves.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        name: {
-          type: 'string',
-          description:
-            'Short name for the workflow (will be prefixed with ai:{agentName}:)',
-        },
-        description: {
-          type: 'string',
-          description: 'What this workflow does',
-        },
-        nodes: {
-          type: 'string',
-          description:
-            'JSON string of a map of nodeId to node config. Each node has: rpcName (tool name), input (with $ref to wire outputs), next (string|string[]|{branchKey: string}), onError (string|string[]). Example: {"list":{"rpcName":"todos:listTodos","input":{}}}',
+    tools.push({
+      name: 'createAgentWorkflow',
+      description:
+        'Validate and create a draft workflow DAG that chains tools together. The graph is validated for wiring correctness and type compatibility. Call saveAgentWorkflow to activate it after the user approves.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          name: {
+            type: 'string',
+            description:
+              'Short name for the workflow (will be prefixed with ai:{agentName}:)',
+          },
+          description: {
+            type: 'string',
+            description: 'What this workflow does',
+          },
+          nodes: {
+            type: 'string',
+            description:
+              'JSON string of nodeId→node map. Node fields: rpcName (tool name), input (use $ref+path to wire data), next (flow control), onError (error routing). Must have 2+ nodes.',
+          },
         },
+        required: ['name', 'nodes'],
       },
-      required: ['name', 'nodes'],
-    },
-    execute: async (input: unknown) => {
-      const raw = input as {
-        name: string
-        description?: string
-        nodes: string | Record<string, any>
-      }
-      const name = raw.name.replace(/[^a-zA-Z0-9_-]/g, '-')
-      let nodes: Record<string, any>
-      if (typeof raw.nodes === 'string') {
-        try {
-          nodes = JSON.parse(raw.nodes)
-        } catch {
-          return { error: 'Invalid JSON in nodes field' }
+      execute: async (input: unknown) => {
+        const raw = input as {
+          name: string
+          description?: string
+          nodes: string | Record<string, any>
         }
-      } else {
-        nodes = raw.nodes
-      }
-
-      if (Object.keys(nodes).length < 2) {
-        return {
-          error:
-            'A workflow must have at least 2 nodes. A single node is just a tool call — use the tool directly instead.',
+        const name = raw.name.replace(/[^a-zA-Z0-9_-]/g, '-')
+        let nodes: Record<string, any>
+        if (typeof raw.nodes === 'string') {
+          try {
+            nodes = JSON.parse(raw.nodes)
+          } catch {
+            return { error: 'Invalid JSON in nodes field' }
+          }
+        } else {
+          nodes = raw.nodes
         }
-      }
 
-      const validationErrors = validateWorkflowWiring(nodes, toolNames)
-      if (validationErrors.length > 0) {
-        return {
-          error: 'Workflow validation failed',
-          errors: validationErrors,
+        if (Object.keys(nodes).length < 2) {
+          return {
+            error:
+              'A workflow must have at least 2 nodes. A single node is just a tool call — use the tool directly instead.',
+          }
         }
-      }
 
-      const entryNodeIds = computeEntryNodeIds(nodes)
-      if (entryNodeIds.length === 0) {
-        return {
-          error:
-            'No entry nodes found. Every node is referenced by another node, creating a cycle.',
+        const usedTools = [
+          ...new Set(
+            Object.values(nodes)
+              .map((n: any) => n.rpcName)
+              .filter(Boolean)
+          ),
+        ]
+        const toolSchemas = buildDetailedToolSchemas(usedTools)
+
+        const validationErrors = validateWorkflowWiring(nodes, toolNames)
+        if (validationErrors.length > 0) {
+          return {
+            error: 'Workflow validation failed',
+            errors: validationErrors,
+            toolSchemas,
+          }
         }
-      }
 
-      const fullName = `ai:${agentName}:${name}`
-
-      const graphHash = hashString(canonicalJSON({ nodes, entryNodeIds }))
-      const graph: WorkflowRuntimeMeta = {
-        name: fullName,
-        pikkuFuncId: fullName,
-        source: 'ai-agent',
-        description: raw.description,
-        nodes,
-        entryNodeIds,
-        graphHash,
-      }
+        const entryNodeIds = computeEntryNodeIds(nodes)
+        if (entryNodeIds.length === 0) {
+          return {
+            error:
+              'No entry nodes found. Every node is referenced by another node, creating a cycle.',
+          }
+        }
 
-      const singletonServices = getSingletonServices()
-      if (!singletonServices?.workflowService) {
-        return { error: 'Workflow service not available' }
-      }
+        const fullName = `ai:${agentName}:${name}`
+
+        const graphHash = hashString(canonicalJSON({ nodes, entryNodeIds }))
+        const graph: WorkflowRuntimeMeta = {
+          name: fullName,
+          pikkuFuncId: fullName,
+          source: 'ai-agent',
+          description: raw.description,
+          nodes,
+          entryNodeIds,
+          graphHash,
+        }
 
-      await singletonServices.workflowService.upsertWorkflowVersion(
-        fullName,
-        graphHash,
-        graph,
-        'ai-agent',
-        'draft'
-      )
+        const singletonServices = getSingletonServices()
+        if (!singletonServices?.workflowService) {
+          return { error: 'Workflow service not available' }
+        }
 
-      return {
-        valid: true,
-        workflowName: fullName,
-        graphHash,
-        entryNodes: entryNodeIds,
-        nodeCount: Object.keys(nodes).length,
-        message: `Workflow '${fullName}' validated and saved as draft. Present this to the user and call saveAgentWorkflow to activate it.`,
-      }
-    },
-  })
+        await singletonServices.workflowService.upsertWorkflowVersion(
+          fullName,
+          graphHash,
+          graph,
+          'ai-agent',
+          'draft'
+        )
 
-  tools.push({
-    name: 'saveAgentWorkflow',
-    description:
-      'Activate a previously created draft workflow so it can be executed. Requires user approval.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        name: {
-          type: 'string',
-          description:
-            'Full workflow name returned by createAgentWorkflow (e.g. ai:agentName:myWorkflow)',
-        },
-        graphHash: {
-          type: 'string',
-          description: 'Graph hash returned by createAgentWorkflow',
+        return {
+          valid: true,
+          workflowName: fullName,
+          graphHash,
+          entryNodes: entryNodeIds,
+          nodeCount: Object.keys(nodes).length,
+          toolSchemas,
+          message: `Workflow '${fullName}' validated and saved as draft. Check the toolSchemas to verify your $ref paths match the output paths. Then present this to the user and call saveAgentWorkflow to activate it.`,
+        }
+      },
+    })
+
+    tools.push({
+      name: 'saveAgentWorkflow',
+      description:
+        'Activate a previously created draft workflow so it can be executed. Requires user approval.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          name: {
+            type: 'string',
+            description:
+              'Full workflow name returned by createAgentWorkflow (e.g. ai:agentName:myWorkflow)',
+          },
+          graphHash: {
+            type: 'string',
+            description: 'Graph hash returned by createAgentWorkflow',
+          },
         },
+        required: ['name', 'graphHash'],
       },
-      required: ['name', 'graphHash'],
-    },
-    needsApproval: true,
-    approvalDescriptionFn: async (input: unknown) => {
-      const raw = input as { name: string; graphHash: string }
-      const fullName = raw.name.startsWith(`ai:${agentName}:`)
-        ? raw.name
-        : `ai:${agentName}:${raw.name}`
+      needsApproval: true,
+      approvalDescriptionFn: async (input: unknown) => {
+        const raw = input as { name: string; graphHash: string }
+        const fullName = raw.name.startsWith(`ai:${agentName}:`)
+          ? raw.name
+          : `ai:${agentName}:${raw.name}`
+
+        const singletonServices = getSingletonServices()
+        if (!singletonServices?.workflowService) {
+          return `Activate workflow '${fullName}'`
+        }
 
-      const singletonServices = getSingletonServices()
-      if (!singletonServices?.workflowService) {
+        const version =
+          await singletonServices.workflowService.getWorkflowVersion(
+            fullName,
+            raw.graphHash
+          )
+        if (version) {
+          const graph = version.graph as WorkflowRuntimeMeta
+          if (graph.nodes) {
+            const desc = graph.description ? `\n${graph.description}` : ''
+            return `Activate workflow '${fullName}' (${Object.keys(graph.nodes).length} nodes)${desc}`
+          }
+        }
         return `Activate workflow '${fullName}'`
-      }
-
-      const version =
-        await singletonServices.workflowService.getWorkflowVersion(
-          fullName,
-          raw.graphHash
-        )
-      if (version) {
-        const graph = version.graph as WorkflowRuntimeMeta
-        if (graph.nodes) {
-          const desc = graph.description ? `\n${graph.description}` : ''
-          return `Activate workflow '${fullName}' (${Object.keys(graph.nodes).length} nodes)${desc}`
+      },
+      execute: async (input: unknown) => {
+        const raw = input as { name: string; graphHash: string }
+        const fullName = raw.name.startsWith(`ai:${agentName}:`)
+          ? raw.name
+          : `ai:${agentName}:${raw.name}`
+
+        const singletonServices = getSingletonServices()
+        if (!singletonServices?.workflowService) {
+          return { error: 'Workflow service not available' }
         }
-      }
-      return `Activate workflow '${fullName}'`
-    },
-    execute: async (input: unknown) => {
-      const raw = input as { name: string; graphHash: string }
-      const fullName = raw.name.startsWith(`ai:${agentName}:`)
-        ? raw.name
-        : `ai:${agentName}:${raw.name}`
 
-      const singletonServices = getSingletonServices()
-      if (!singletonServices?.workflowService) {
-        return { error: 'Workflow service not available' }
-      }
+        const version =
+          await singletonServices.workflowService.getWorkflowVersion(
+            fullName,
+            raw.graphHash
+          )
+        if (!version) {
+          return {
+            error: `Workflow '${fullName}' with hash '${raw.graphHash}' not found. Use createAgentWorkflow first.`,
+          }
+        }
 
-      const version =
-        await singletonServices.workflowService.getWorkflowVersion(
+        await singletonServices.workflowService.updateWorkflowVersionStatus(
           fullName,
-          raw.graphHash
+          raw.graphHash,
+          'active'
         )
-      if (!version) {
-        return {
-          error: `Workflow '${fullName}' with hash '${raw.graphHash}' not found. Use createAgentWorkflow first.`,
-        }
-      }
 
-      await singletonServices.workflowService.updateWorkflowVersionStatus(
-        fullName,
-        raw.graphHash,
-        'active'
-      )
-
-      const graph = version.graph as WorkflowRuntimeMeta
-      const allMeta = pikkuState(null, 'workflows', 'meta')
-      allMeta[fullName] = graph
+        const graph = version.graph as WorkflowRuntimeMeta
+        const allMeta = pikkuState(null, 'workflows', 'meta')
+        allMeta[fullName] = graph
+
+        if (streamContext) {
+          streamContext.channel.send({
+            type: 'workflow-created',
+            workflowName: fullName,
+            graph,
+          })
+        }
 
-      if (streamContext) {
-        streamContext.channel.send({
-          type: 'workflow-created',
+        return {
+          success: true,
           workflowName: fullName,
-          graph,
-        })
-      }
-
-      return {
-        success: true,
-        workflowName: fullName,
-        message: `Workflow '${fullName}' activated and ready to execute.`,
-      }
-    },
-  })
+          message: `Workflow '${fullName}' activated and ready to execute.`,
+        }
+      },
+    })
   } // end if (mode !== 'read')
 
   tools.push({