@pikku/core 0.12.2 → 0.12.3

package/dist/wirings/workflow/graph/graph-validation.js

@@ -0,0 +1,175 @@
+import { pikkuState } from '../../../pikku-state.js';
+import { resolveNamespace } from '../../rpc/rpc-runner.js';
+function normalizeTargets(value) {
+    if (!value)
+        return [];
+    if (typeof value === 'string')
+        return [value];
+    if (Array.isArray(value))
+        return value.filter((v) => typeof v === 'string');
+    if (typeof value === 'object') {
+        const targets = [];
+        for (const v of Object.values(value)) {
+            targets.push(...normalizeTargets(v));
+        }
+        return targets;
+    }
+    return [];
+}
+function collectRefs(value, refs) {
+    if (typeof value === 'object' &&
+        value !== null &&
+        '$ref' in value &&
+        typeof value.$ref === 'string') {
+        refs.add(value.$ref);
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value)
+            collectRefs(item, refs);
+        return;
+    }
+    if (typeof value === 'object' && value !== null) {
+        for (const v of Object.values(value))
+            collectRefs(v, refs);
+    }
+}
+function resolveToolMeta(toolName) {
+    const resolved = toolName.includes(':') ? resolveNamespace(toolName) : null;
+    if (resolved) {
+        const fnMeta = pikkuState(resolved.package, 'function', 'meta')[resolved.function];
+        const schemas = pikkuState(resolved.package, 'misc', 'schemas');
+        return fnMeta ? { fnMeta, schemas } : null;
+    }
+    const rpcMeta = pikkuState(null, 'rpc', 'meta');
+    const pikkuFuncId = rpcMeta[toolName];
+    if (!pikkuFuncId)
+        return null;
+    const fnMeta = pikkuState(null, 'function', 'meta')[pikkuFuncId];
+    const schemas = pikkuState(null, 'misc', 'schemas');
+    return fnMeta ? { fnMeta, schemas } : null;
+}
+export function computeEntryNodeIds(nodes) {
+    const referenced = new Set();
+    for (const node of Object.values(nodes)) {
+        if (node.next) {
+            for (const target of normalizeTargets(node.next)) {
+                referenced.add(target);
+            }
+        }
+        if (node.onError) {
+            for (const target of normalizeTargets(node.onError)) {
+                referenced.add(target);
+            }
+        }
+    }
+    return Object.keys(nodes).filter((id) => !referenced.has(id));
+}
+export function validateWorkflowWiring(nodes, toolNames) {
+    const errors = [];
+    const nodeIds = new Set(Object.keys(nodes));
+    const toolSet = new Set(toolNames);
+    for (const [nodeId, node] of Object.entries(nodes)) {
+        if (!node.rpcName) {
+            errors.push(`Node '${nodeId}' is missing 'rpcName'`);
+            continue;
+        }
+        if (!toolSet.has(node.rpcName)) {
+            errors.push(`Node '${nodeId}' references unknown tool '${node.rpcName}'. Available tools: ${toolNames.join(', ')}`);
+            continue;
+        }
+        const nextTargets = normalizeTargets(node.next);
+        for (const target of nextTargets) {
+            if (!nodeIds.has(target)) {
+                errors.push(`Node '${nodeId}' routes to unknown node '${target}' in 'next'`);
+            }
+        }
+        const errorTargets = normalizeTargets(node.onError);
+        for (const target of errorTargets) {
+            if (!nodeIds.has(target)) {
+                errors.push(`Node '${nodeId}' routes to unknown node '${target}' in 'onError'`);
+            }
+        }
+        if (!node.input)
+            continue;
+        const refs = new Set();
+        collectRefs(node.input, refs);
+        for (const ref of refs) {
+            if (ref === 'trigger' || ref === '$item') {
+                const targetMeta = resolveToolMeta(node.rpcName);
+                if (targetMeta?.fnMeta?.inputSchemaName) {
+                    const targetSchema = targetMeta.schemas.get(targetMeta.fnMeta.inputSchemaName);
+                    if (targetSchema?.properties) {
+                        for (const [field, fieldValue] of Object.entries(node.input)) {
+                            if (typeof fieldValue === 'object' &&
+                                fieldValue !== null &&
+                                fieldValue.$ref === ref &&
+                                !fieldValue.path) {
+                                const targetType = targetSchema.properties[field]?.type;
+                                if (targetType && targetType !== 'object') {
+                                    errors.push(`Node '${nodeId}' input field '${field}' expects type '${targetType}', but references the whole ${ref} object without a path. Use { $ref: "${ref}", path: "${field}" } to extract the field.`);
+                                }
+                            }
+                        }
+                    }
+                }
+                continue;
+            }
+            if (!nodeIds.has(ref)) {
+                errors.push(`Node '${nodeId}' references unknown node '${ref}' in input`);
+                continue;
+            }
+            const sourceNode = nodes[ref];
+            if (!sourceNode?.rpcName)
+                continue;
+            const sourceMeta = resolveToolMeta(sourceNode.rpcName);
+            if (!sourceMeta?.fnMeta?.outputSchemaName)
+                continue;
+            const sourceSchema = sourceMeta.schemas.get(sourceMeta.fnMeta.outputSchemaName);
+            if (!sourceSchema?.properties)
+                continue;
+            for (const [field, fieldValue] of Object.entries(node.input)) {
+                if (typeof fieldValue === 'object' &&
+                    fieldValue !== null &&
+                    fieldValue.$ref === ref &&
+                    fieldValue.path) {
+                    const pathRoot = fieldValue.path.split('.')[0];
+                    if (sourceSchema.properties &&
+                        !(pathRoot in sourceSchema.properties)) {
+                        errors.push(`Node '${nodeId}' input field '${field}' references path '${fieldValue.path}' but node '${ref}' (${sourceNode.rpcName}) output has no property '${pathRoot}'`);
+                        continue;
+                    }
+                    const targetMeta = resolveToolMeta(node.rpcName);
+                    if (!targetMeta?.fnMeta?.inputSchemaName)
+                        continue;
+                    const targetSchema = targetMeta.schemas.get(targetMeta.fnMeta.inputSchemaName);
+                    if (!targetSchema?.properties?.[field])
+                        continue;
+                    const sourceType = sourceSchema.properties[pathRoot]?.type;
+                    const targetType = targetSchema.properties[field].type;
+                    if (sourceType && targetType && sourceType !== targetType) {
+                        errors.push(`Node '${nodeId}' input field '${field}' expects type '${targetType}', but node '${ref}' output field '${pathRoot}' is type '${sourceType}'`);
+                    }
+                }
+            }
+        }
+    }
+    return errors;
+}
+export function generateMermaidDiagram(workflowName, nodes, entryNodeIds) {
+    const lines = ['graph TD'];
+    for (const [nodeId, node] of Object.entries(nodes)) {
+        const label = node.rpcName || nodeId;
+        const isEntry = entryNodeIds.includes(nodeId);
+        lines.push(`  ${nodeId}${isEntry ? '([' : '['}${label}${isEntry ? '])' : ']'}`);
+        const nextTargets = normalizeTargets(node.next);
+        for (const target of nextTargets) {
+            lines.push(`  ${nodeId} --> ${target}`);
+        }
+        const errorTargets = normalizeTargets(node.onError);
+        for (const target of errorTargets) {
+            lines.push(`  ${nodeId} -.->|error| ${target}`);
+        }
+    }
+    return lines.join('\n');
+}

package/dist/wirings/workflow/graph/index.d.ts

@@ -2,3 +2,4 @@ export { continueGraph, executeGraphStep, onGraphNodeComplete, runFromMeta, runW
 export { template } from './template.js';
 export type { TemplateString } from './template.js';
 export { pikkuWorkflowGraph, type PikkuWorkflowGraphConfig, type PikkuWorkflowGraphResult, } from './wire-workflow-graph.js';
+export { validateWorkflowWiring, computeEntryNodeIds, generateMermaidDiagram, } from './graph-validation.js';

package/dist/wirings/workflow/graph/index.js

@@ -1,3 +1,4 @@
 export { continueGraph, executeGraphStep, onGraphNodeComplete, runFromMeta, runWorkflowGraph, } from './graph-runner.js';
 export { template } from './template.js';
 export { pikkuWorkflowGraph, } from './wire-workflow-graph.js';
+export { validateWorkflowWiring, computeEntryNodeIds, generateMermaidDiagram, } from './graph-validation.js';

package/dist/wirings/workflow/index.d.ts

@@ -6,5 +6,5 @@ export { addWorkflow } from './dsl/workflow-runner.js';
 export { template, type TemplateString } from './graph/template.js';
 export { pikkuWorkflowGraph, type PikkuWorkflowGraphConfig, type PikkuWorkflowGraphResult, } from './graph/wire-workflow-graph.js';
 export { workflow, workflowStart, workflowStatus, graphStart, } from './workflow-helpers.js';
-export type { WorkflowService, WorkflowServiceConfig, WorkflowRunWire, WorkflowStatus, StepStatus, WorkflowRun, StepState, WorkflowRunService, CoreWorkflow, PikkuWorkflow, ContextVariable, WorkflowContext, WorkflowsMeta, WorkflowRuntimeMeta, WorkflowsRuntimeMeta, WorkflowStepInput, WorkflowOrchestratorInput, WorkflowSleeperInput, } from './workflow.types.js';
+export type { WorkflowService, WorkflowServiceConfig, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, StepStatus, WorkflowRun, StepState, WorkflowRunService, CoreWorkflow, PikkuWorkflow, ContextVariable, WorkflowContext, WorkflowsMeta, WorkflowRuntimeMeta, WorkflowsRuntimeMeta, WorkflowStepInput, WorkflowOrchestratorInput, WorkflowSleeperInput, } from './workflow.types.js';
 export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchCase, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, } from './workflow.types.js';

package/dist/wirings/workflow/pikku-workflow-service.d.ts

@@ -1,5 +1,5 @@
 import type { SerializedError } from '../../types/core.types.js';
-import type { StepState, WorkflowRun, WorkflowRunWire, WorkflowStatus, WorkflowStepOptions } from './workflow.types.js';
+import type { StepState, WorkflowRun, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, WorkflowStepOptions } from './workflow.types.js';
 import type { WorkflowService } from '../../services/workflow-service.js';
 import { PikkuError } from '../../errors/error-handler.js';
 /**
@@ -197,11 +197,17 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      * @returns The state object with all variables
      */
     abstract getRunState(runId: string): Promise<Record<string, unknown>>;
-    abstract upsertWorkflowVersion(name: string, graphHash: string, graph: any, source: string): Promise<void>;
+    abstract upsertWorkflowVersion(name: string, graphHash: string, graph: any, source: string, status?: WorkflowVersionStatus): Promise<void>;
+    abstract updateWorkflowVersionStatus(name: string, graphHash: string, status: WorkflowVersionStatus): Promise<void>;
     abstract getWorkflowVersion(name: string, graphHash: string): Promise<{
         graph: any;
         source: string;
     } | null>;
+    abstract getAIGeneratedWorkflows(agentName?: string): Promise<Array<{
+        workflowName: string;
+        graphHash: string;
+        graph: any;
+    }>>;
     /**
      * Resume a paused workflow by triggering the orchestrator
      * @param runId - Run ID

package/dist/wirings/workflow/pikku-workflow-service.js

@@ -162,8 +162,7 @@ export class PikkuWorkflowService {
         if (!workflowMeta) {
             throw new WorkflowNotFoundError(name);
         }
-        // Check if this is a graph workflow (source === 'graph')
-        if (workflowMeta.source === 'graph') {
+        if (workflowMeta.source === 'graph' || workflowMeta.source === 'ai-agent') {
             const shouldInline = options?.inline || !getSingletonServices()?.queueService;
             return runWorkflowGraph(this, name, input, rpcService, shouldInline, options?.startNode, wire);
         }

package/dist/wirings/workflow/workflow.types.d.ts

@@ -19,6 +19,10 @@ export interface WorkflowServiceConfig {
  * Workflow run status
  */
 export type WorkflowStatus = 'running' | 'suspended' | 'completed' | 'failed' | 'cancelled';
+/**
+ * Workflow version status (for AI-generated workflows)
+ */
+export type WorkflowVersionStatus = 'draft' | 'active' | 'declined';
 /**
  * Workflow step status
  */
@@ -102,6 +106,11 @@ export interface WorkflowRunService {
         graph: any;
         source: string;
     } | null>;
+    getAIGeneratedWorkflows(agentName?: string): Promise<Array<{
+        workflowName: string;
+        graphHash: string;
+        graph: any;
+    }>>;
     deleteRun(id: string): Promise<boolean>;
 }
 /**
@@ -167,7 +176,7 @@ export interface WorkflowRuntimeMeta {
     /** Pikku function name (for execution) */
     pikkuFuncId: string;
     /** Source type: 'dsl' (serializable), 'complex' (has inline steps), 'graph' */
-    source: 'dsl' | 'complex' | 'graph';
+    source: 'dsl' | 'complex' | 'graph' | 'ai-agent';
     /** Optional description */
     description?: string;
     /** Tags for organization */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.2",
+  "version": "0.12.3",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",
@@ -41,8 +41,10 @@
     "./services": "./dist/services/index.js",
     "./services/local-content": "./dist/services/local-content.js",
     "./services/gopass-secrets": "./dist/services/gopass-secrets.js",
+    "./crypto-utils": "./dist/crypto-utils.js",
     "./internal": "./dist/internal.js",
-    "./schema": "./dist/schema.js"
+    "./schema": "./dist/schema.js",
+    "./testing": "./dist/testing/index.js"
   },
   "dependencies": {
     "@standard-schema/spec": "^1.1.0",

package/src/crypto-utils.test.ts

@@ -1,6 +1,15 @@
 import { describe, test } from 'node:test'
 import assert from 'node:assert'
-import { encryptJSON, decryptJSON } from './crypto-utils.js'
+import {
+  encryptJSON,
+  decryptJSON,
+  generateDEK,
+  wrapDEK,
+  unwrapDEK,
+  envelopeEncrypt,
+  envelopeDecrypt,
+  envelopeRewrap,
+} from './crypto-utils.js'
 
 describe('encryptJSON / decryptJSON', () => {
   const secret = 'test-secret-key-for-encryption'
@@ -114,3 +123,92 @@ describe('encryptJSON / decryptJSON', () => {
     assert.deepStrictEqual(decrypted, original)
   })
 })
+
+describe('envelope encryption', () => {
+  const kek = 'my-key-encryption-key'
+
+  test('generateDEK produces unique keys', async () => {
+    const dek1 = await generateDEK()
+    const dek2 = await generateDEK()
+    assert.notStrictEqual(dek1, dek2)
+    assert.ok(dek1.length > 0)
+  })
+
+  test('wrapDEK / unwrapDEK round-trip', async () => {
+    const dek = await generateDEK()
+    const wrapped = await wrapDEK(kek, dek)
+    const unwrapped = await unwrapDEK(kek, wrapped)
+    assert.strictEqual(unwrapped, dek)
+  })
+
+  test('unwrapDEK fails with wrong KEK', async () => {
+    const dek = await generateDEK()
+    const wrapped = await wrapDEK(kek, dek)
+    await assert.rejects(
+      () => unwrapDEK('wrong-kek', wrapped),
+      (err: any) => err instanceof Error
+    )
+  })
+
+  test('envelopeEncrypt / envelopeDecrypt round-trip', async () => {
+    const original = {
+      apiKey: 'sk-secret-123',
+      endpoint: 'https://api.example.com',
+    }
+    const { ciphertext, wrappedDEK } = await envelopeEncrypt(kek, original)
+    const decrypted = await envelopeDecrypt(kek, ciphertext, wrappedDEK)
+    assert.deepStrictEqual(decrypted, original)
+  })
+
+  test('envelopeEncrypt produces unique ciphertexts and DEKs per call', async () => {
+    const value = { same: 'data' }
+    const r1 = await envelopeEncrypt(kek, value)
+    const r2 = await envelopeEncrypt(kek, value)
+    assert.notStrictEqual(r1.ciphertext, r2.ciphertext)
+    assert.notStrictEqual(r1.wrappedDEK, r2.wrappedDEK)
+  })
+
+  test('envelopeDecrypt fails with wrong KEK', async () => {
+    const { ciphertext, wrappedDEK } = await envelopeEncrypt(kek, 'secret')
+    await assert.rejects(
+      () => envelopeDecrypt('wrong-kek', ciphertext, wrappedDEK),
+      (err: any) => err instanceof Error
+    )
+  })
+
+  test('envelopeRewrap allows decryption with new KEK', async () => {
+    const newKEK = 'my-new-kek'
+    const original = { token: 'abc-123' }
+    const { ciphertext, wrappedDEK } = await envelopeEncrypt(kek, original)
+
+    const rewrapped = await envelopeRewrap(kek, newKEK, wrappedDEK)
+
+    await assert.rejects(
+      () => envelopeDecrypt(kek, ciphertext, rewrapped),
+      (err: any) => err instanceof Error
+    )
+
+    const decrypted = await envelopeDecrypt(newKEK, ciphertext, rewrapped)
+    assert.deepStrictEqual(decrypted, original)
+  })
+
+  test('envelopeRewrap does not change the ciphertext', async () => {
+    const original = { data: 'important' }
+    const { ciphertext, wrappedDEK } = await envelopeEncrypt(kek, original)
+    const rewrapped = await envelopeRewrap(kek, 'new-kek', wrappedDEK)
+
+    assert.notStrictEqual(rewrapped, wrappedDEK)
+
+    const decrypted = await envelopeDecrypt('new-kek', ciphertext, rewrapped)
+    assert.deepStrictEqual(decrypted, original)
+  })
+
+  test('envelope handles string secrets', async () => {
+    const { ciphertext, wrappedDEK } = await envelopeEncrypt(
+      kek,
+      'plain-string-secret'
+    )
+    const decrypted = await envelopeDecrypt<string>(kek, ciphertext, wrappedDEK)
+    assert.strictEqual(decrypted, 'plain-string-secret')
+  })
+})

package/src/crypto-utils.ts

@@ -97,3 +97,117 @@ export const decryptJSON = async <T>(
   )
   return JSON.parse(decoder.decode(new Uint8Array(decrypted))) as T
 }
+
+/**
+ * Envelope encryption utilities.
+ *
+ * Each secret gets its own random DEK (data encryption key).
+ * The DEK is wrapped (encrypted) by a KEK (key encryption key) — typically an env var.
+ * The actual secret is encrypted with the DEK.
+ *
+ * KEK rotation only re-wraps the DEK, never touches the ciphertext.
+ */
+
+const importRawKey = async (rawBytes: Uint8Array): Promise<CryptoKey> => {
+  const subtle = getSubtle()
+  return subtle.importKey(
+    'raw',
+    rawBytes.buffer as ArrayBuffer,
+    { name: 'AES-GCM' },
+    true,
+    ['encrypt', 'decrypt']
+  )
+}
+
+export const generateDEK = async (): Promise<string> => {
+  const raw = globalThis.crypto.getRandomValues(new Uint8Array(32))
+  return toBase64Url(raw)
+}
+
+export const wrapDEK = async (
+  kek: string,
+  plaintextDEK: string
+): Promise<string> => {
+  return encryptJSON(kek, plaintextDEK)
+}
+
+export const unwrapDEK = async (
+  kek: string,
+  wrappedDEK: string
+): Promise<string> => {
+  return decryptJSON<string>(kek, wrappedDEK)
+}
+
+const encryptWithDEK = async (
+  dekBase64: string,
+  value: unknown
+): Promise<string> => {
+  const crypto = globalThis.crypto
+  const subtle = getSubtle()
+  const iv = crypto.getRandomValues(new Uint8Array(12))
+  const key = await importRawKey(fromBase64Url(dekBase64))
+  const plaintext = encoder.encode(JSON.stringify(value))
+  const encrypted = await subtle.encrypt(
+    { name: 'AES-GCM', iv },
+    key,
+    plaintext
+  )
+  const cipherBytes = new Uint8Array(encrypted)
+  const out = new Uint8Array(iv.length + cipherBytes.length)
+  out.set(iv, 0)
+  out.set(cipherBytes, iv.length)
+  return toBase64Url(out)
+}
+
+const decryptWithDEK = async <T>(
+  dekBase64: string,
+  token: string
+): Promise<T> => {
+  const subtle = getSubtle()
+  const data = fromBase64Url(token)
+  if (data.length < 13) {
+    throw new Error('Invalid encrypted payload')
+  }
+  const iv = data.slice(0, 12)
+  const ciphertext = data.slice(12)
+  const key = await importRawKey(fromBase64Url(dekBase64))
+  const decrypted = await subtle.decrypt(
+    { name: 'AES-GCM', iv },
+    key,
+    ciphertext
+  )
+  return JSON.parse(decoder.decode(new Uint8Array(decrypted))) as T
+}
+
+export interface EnvelopeEncryptResult {
+  ciphertext: string
+  wrappedDEK: string
+}
+
+export const envelopeEncrypt = async (
+  kek: string,
+  value: unknown
+): Promise<EnvelopeEncryptResult> => {
+  const dek = await generateDEK()
+  const ciphertext = await encryptWithDEK(dek, value)
+  const wrappedDEK = await wrapDEK(kek, dek)
+  return { ciphertext, wrappedDEK }
+}
+
+export const envelopeDecrypt = async <T>(
+  kek: string,
+  ciphertext: string,
+  wrappedDEK: string
+): Promise<T> => {
+  const dek = await unwrapDEK(kek, wrappedDEK)
+  return decryptWithDEK<T>(dek, ciphertext)
+}
+
+export const envelopeRewrap = async (
+  oldKEK: string,
+  newKEK: string,
+  wrappedDEK: string
+): Promise<string> => {
+  const dek = await unwrapDEK(oldKEK, wrappedDEK)
+  return wrapDEK(newKEK, dek)
+}

package/src/function/function-runner.ts

@@ -95,7 +95,7 @@ export const getAllFunctionNames = (): string[] => {
   const mainFunctionsMeta = pikkuState(null, 'function', 'meta')
   functions.push(...Object.keys(mainFunctionsMeta))
 
-  const addons = pikkuState(null, 'rpc', 'addons')
+  const addons = pikkuState(null, 'addons', 'packages')
   for (const [namespace, config] of addons) {
     const packageFunctionsMeta = pikkuState(config.package, 'function', 'meta')
     for (const funcName of Object.keys(packageFunctionsMeta)) {
@@ -280,6 +280,10 @@ export const runPikkuFunc = async <In = any, Out = any>(
     // Validate and coerce data if schema is defined
     const inputSchemaName = funcMeta.inputSchemaName
     if (inputSchemaName) {
+      // Coerce (top level) data types before validation (e.g. string→array, string→date)
+      if (coerceDataFromSchema) {
+        coerceTopLevelDataFromSchema(inputSchemaName, actualData, packageName)
+      }
       // Validate request data against the defined schema, if any
       await validateSchema(
         resolvedSingletonServices.logger,
@@ -288,10 +292,6 @@ export const runPikkuFunc = async <In = any, Out = any>(
         actualData,
         packageName
       )
-      // Coerce (top level) query string parameters or date objects if specified by the schema
-      if (coerceDataFromSchema) {
-        coerceTopLevelDataFromSchema(inputSchemaName, actualData, packageName)
-      }
     }
 
     if (

package/src/function/functions.types.ts

@@ -7,6 +7,7 @@ import type {
   PickRequired,
 } from '../types/core.types.js'
 import type { StandardSchemaV1 } from '@standard-schema/spec'
+import type { PikkuError } from '../errors/error-handler.js'
 import type { CoreNodeConfig } from '../wirings/node/node.types.js'
 
 /**
@@ -194,6 +195,40 @@ export const pikkuPermissionFactory = <In = any>(
   return factory
 }
 
+/**
+ * A function that generates a human-readable description of a pending approval action.
+ * Used by AI agents to show meaningful approval prompts instead of raw tool arguments.
+ *
+ * @template In - The input type (same as the function it describes).
+ * @template Services - The services type, defaults to `CoreSingletonServices`.
+ */
+export type CorePikkuApprovalDescription<
+  In = any,
+  Services extends CoreSingletonServices = CoreSingletonServices,
+> = (services: Services, data: In) => Promise<string>
+
+/**
+ * Factory function for creating approval description functions with tree-shaking support.
+ *
+ * @example
+ * ```typescript
+ * export const deleteTodoApproval = pikkuApprovalDescription(
+ *   async ({ todoStore }, { id }) => {
+ *     const todo = await todoStore.get(id)
+ *     return `Delete todo: "${todo.title}"`
+ *   }
+ * )
+ * ```
+ */
+export const pikkuApprovalDescription = <
+  In = any,
+  Services extends CoreSingletonServices = CoreSingletonServices,
+>(
+  fn: CorePikkuApprovalDescription<In, Services>
+): CorePikkuApprovalDescription<In, Services> => {
+  return fn
+}
+
 export type CorePikkuAuth<
   Services extends CoreSingletonServices = CoreServices,
   Session extends CoreUserSession = CoreUserSession,
@@ -256,7 +291,8 @@ export type CorePikkuFunctionConfig<
   remote?: boolean
   mcp?: boolean
   readonly?: boolean
-  requiresApproval?: boolean
+  approvalRequired?: boolean
+  approvalDescription?: any
   func: PikkuFunction
   auth?: boolean
   permissions?: CorePermissionGroup<PikkuPermission>
@@ -264,4 +300,5 @@ export type CorePikkuFunctionConfig<
   input?: InputSchema
   output?: OutputSchema
   node?: CoreNodeConfig
+  errors?: Array<typeof PikkuError>
 }