@pikku/core 0.12.8 → 0.12.10

package/dist/services/typed-credential-service.js

@@ -0,0 +1,40 @@
+export class TypedCredentialService {
+    credentials;
+    credentialsMeta;
+    constructor(credentials, credentialsMeta) {
+        this.credentials = credentials;
+        this.credentialsMeta = credentialsMeta;
+    }
+    async get(name, userId) {
+        return this.credentials.get(name, userId);
+    }
+    async set(name, value, userId) {
+        return this.credentials.set(name, value, userId);
+    }
+    async delete(name, userId) {
+        return this.credentials.delete(name, userId);
+    }
+    async has(name, userId) {
+        return this.credentials.has(name, userId);
+    }
+    async getAll(userId) {
+        return this.credentials.getAll(userId);
+    }
+    async getAllStatus(userId) {
+        const results = [];
+        for (const [name, meta] of Object.entries(this.credentialsMeta)) {
+            results.push({
+                name,
+                displayName: meta.displayName,
+                isConfigured: await this.credentials.has(name, userId),
+                type: meta.type,
+                oauth2: meta.oauth2,
+            });
+        }
+        return results;
+    }
+    async getMissing(userId) {
+        const all = await this.getAllStatus(userId);
+        return all.filter((c) => !c.isConfigured);
+    }
+}

package/dist/testing/service-tests.d.ts

@@ -6,6 +6,7 @@ import type { DeploymentService } from '../services/deployment-service.js';
 import type { AIStorageService } from '../services/ai-storage-service.js';
 import type { AIRunStateService } from '../services/ai-run-state-service.js';
 import type { SecretService } from '../services/secret-service.js';
+import type { CredentialService } from '../services/credential-service.js';
 import type { AgentRunService } from '../wirings/ai-agent/ai-agent.types.js';
 export interface ServiceTestConfig {
     name: string;
@@ -26,6 +27,13 @@ export interface ServiceTestConfig {
         }) => Promise<SecretService & {
             rotateKEK?(): Promise<number>;
         }>;
+        credentialService?: (config: {
+            key: string;
+            keyVersion?: number;
+            previousKey?: string;
+        }) => Promise<CredentialService & {
+            rotateKEK?(): Promise<number>;
+        }>;
     };
 }
 export declare function defineServiceTests(config: ServiceTestConfig): void;

package/dist/testing/service-tests.js

@@ -523,7 +523,7 @@ export function defineServiceTests(config) {
             test('getSecret throws for missing key', async () => {
                 const service = await factory({ key: kek });
                 await assert.rejects(() => service.getSecret('nonexistent'), {
-                    message: 'Secret not found: nonexistent',
+                    message: 'Requested secret not found',
                 });
             });
             test('setSecretJSON upserts existing key', async () => {
@@ -570,6 +570,112 @@ export function defineServiceTests(config) {
             });
         });
     }
+    if (services.credentialService) {
+        const factory = services.credentialService;
+        const kek = 'test-key-encryption-key-32chars!';
+        describe(`CredentialService [${name}]`, () => {
+            test('set and get (global)', async () => {
+                const service = await factory({ key: kek });
+                await service.set('stripe', { apiKey: 'sk-123' });
+                const result = await service.get('stripe');
+                assert.deepEqual(result, { apiKey: 'sk-123' });
+            });
+            test('get returns null for missing', async () => {
+                const service = await factory({ key: kek });
+                const result = await service.get('nonexistent');
+                assert.equal(result, null);
+            });
+            test('has returns true/false', async () => {
+                const service = await factory({ key: kek });
+                await service.set('exists', { key: 'val' });
+                assert.strictEqual(await service.has('exists'), true);
+                assert.strictEqual(await service.has('nope'), false);
+            });
+            test('set upserts existing credential', async () => {
+                const service = await factory({ key: kek });
+                await service.set('upsert', { v: 1 });
+                await service.set('upsert', { v: 2 });
+                const result = await service.get('upsert');
+                assert.deepEqual(result, { v: 2 });
+            });
+            test('delete removes credential', async () => {
+                const service = await factory({ key: kek });
+                await service.set('to-delete', { bye: true });
+                assert.strictEqual(await service.has('to-delete'), true);
+                await service.delete('to-delete');
+                assert.strictEqual(await service.has('to-delete'), false);
+            });
+            test('per-user isolation', async () => {
+                const service = await factory({ key: kek });
+                await service.set('token', { access: 'user1' }, 'user-1');
+                await service.set('token', { access: 'user2' }, 'user-2');
+                const u1 = await service.get('token', 'user-1');
+                const u2 = await service.get('token', 'user-2');
+                assert.deepEqual(u1, { access: 'user1' });
+                assert.deepEqual(u2, { access: 'user2' });
+            });
+            test('per-user delete does not affect other users', async () => {
+                const service = await factory({ key: kek });
+                await service.set('cred', { val: 'a' }, 'user-a');
+                await service.set('cred', { val: 'b' }, 'user-b');
+                await service.delete('cred', 'user-a');
+                assert.strictEqual(await service.has('cred', 'user-a'), false);
+                assert.strictEqual(await service.has('cred', 'user-b'), true);
+            });
+            test('global and per-user are separate', async () => {
+                const service = await factory({ key: kek });
+                await service.set('shared', { scope: 'global' });
+                await service.set('shared', { scope: 'user' }, 'user-1');
+                const global = await service.get('shared');
+                const perUser = await service.get('shared', 'user-1');
+                assert.deepEqual(global, { scope: 'global' });
+                assert.deepEqual(perUser, { scope: 'user' });
+            });
+            test('getAll returns all credentials for a user', async () => {
+                const service = await factory({ key: kek });
+                await service.set('cred-a', { a: 1 }, 'user-x');
+                await service.set('cred-b', { b: 2 }, 'user-x');
+                await service.set('cred-c', { c: 3 }, 'user-y');
+                const all = await service.getAll('user-x');
+                assert.deepEqual(all['cred-a'], { a: 1 });
+                assert.deepEqual(all['cred-b'], { b: 2 });
+                assert.strictEqual(all['cred-c'], undefined);
+            });
+            test('getAll returns empty for unknown user', async () => {
+                const service = await factory({ key: kek });
+                const all = await service.getAll('nobody');
+                assert.deepEqual(all, {});
+            });
+            test('rotateKEK re-wraps all credentials', async () => {
+                const newKEK = 'new-key-encryption-key-rotated!';
+                const oldService = await factory({ key: kek });
+                await oldService.set('rotate-cred', { important: 'data' }, 'user-r');
+                const rotatedService = await factory({
+                    key: newKEK,
+                    keyVersion: 2,
+                    previousKey: kek,
+                });
+                const before = await rotatedService.get('rotate-cred', 'user-r');
+                assert.deepEqual(before, { important: 'data' });
+                assert.ok(rotatedService.rotateKEK);
+                const count = await rotatedService.rotateKEK();
+                assert.ok(count > 0);
+                const newOnlyService = await factory({
+                    key: newKEK,
+                    keyVersion: 2,
+                });
+                const after = await newOnlyService.get('rotate-cred', 'user-r');
+                assert.deepEqual(after, { important: 'data' });
+            });
+            test('rotateKEK throws without previousKey', async () => {
+                const service = await factory({ key: kek });
+                assert.ok(service.rotateKEK);
+                await assert.rejects(() => service.rotateKEK(), {
+                    message: 'No previousKey configured — nothing to rotate from',
+                });
+            });
+        });
+    }
     if (services.agentRunService) {
         const factory = services.agentRunService;
         describe(`AgentRunService [${name}]`, () => {

package/dist/types/core.types.d.ts

@@ -23,6 +23,7 @@ import type { AIRunStateService } from '../services/ai-run-state-service.js';
 import type { AgentRunService } from '../wirings/ai-agent/ai-agent.types.js';
 import type { PikkuAIMiddlewareHooks } from '../wirings/ai-agent/ai-agent.types.js';
 import type { WorkflowRunService } from '../wirings/workflow/workflow.types.js';
+import type { CredentialService } from '../services/credential-service.js';
 export type PikkuWiringTypes = 'http' | 'scheduler' | 'trigger' | 'channel' | 'rpc' | 'queue' | 'mcp' | 'cli' | 'workflow' | 'agent' | 'gateway';
 export interface FunctionServicesMeta {
     optimized: boolean;
@@ -172,6 +173,8 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
     agentRunService?: AgentRunService;
     /** Workflow run service (listing workflow runs) */
     workflowRunService?: WorkflowRunService;
+    /** Credential service for dynamic/managed credentials (OAuth tokens, per-user API keys) */
+    credentialService?: CredentialService;
 }
 /**
  * Represents different forms of wire within Pikku and the outside world.
@@ -200,6 +203,10 @@ export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boo
     getSession: () => Promise<UserSession> | UserSession | undefined;
     /** Whether the session was modified during this run */
     hasSessionChanged: () => boolean;
+    /** Set a credential value (available in middleware) */
+    setCredential: (name: string, value: unknown) => void;
+    /** Get all resolved credentials (only available in pikkuWireServices) */
+    getCredentials: () => Record<string, unknown>;
 }>;
 /**
  * A function that can wrap an wire and be called before or after

package/dist/wirings/ai-agent/agent-dynamic-workflow.js

@@ -4,11 +4,95 @@ import { runWorkflowGraph } from '../workflow/graph/graph-runner.js';
 import { ContextAwareRPCService, resolveNamespace } from '../rpc/rpc-runner.js';
 import { createMiddlewareSessionWireProps } from '../../services/user-session-service.js';
 import { validateWorkflowWiring, computeEntryNodeIds, } from '../workflow/graph/graph-validation.js';
+function formatSchemaType(schema, depth = 0) {
+    if (!schema)
+        return 'any';
+    if (schema.enum)
+        return schema.enum.map((v) => 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]) => `${k}: ${formatSchemaType(v, depth + 1)}`)
+            .join(', ');
+        return `{${fields}}`;
+    }
+    return schema.type || 'any';
+}
+function resolveToolMetaForWorkflow(toolName) {
+    const resolved = toolName.includes(':') ? resolveNamespace(toolName) : null;
+    let fnMeta;
+    let schemas;
+    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');
+    }
+    if (!fnMeta)
+        return null;
+    const inputSchema = fnMeta.inputSchemaName
+        ? schemas.get(fnMeta.inputSchemaName)
+        : null;
+    const outputSchema = fnMeta.outputSchemaName
+        ? schemas.get(fnMeta.outputSchemaName)
+        : null;
+    return { fnMeta, inputSchema, outputSchema, schemas };
+}
+function buildDetailedToolSchemas(toolNames) {
+    const lines = [];
+    for (const toolName of toolNames) {
+        const meta = resolveToolMetaForWorkflow(toolName);
+        if (!meta)
+            continue;
+        const { inputSchema, outputSchema } = meta;
+        const inputProps = inputSchema?.properties
+            ? Object.entries(inputSchema.properties)
+                .map(([k, v]) => `${k}${inputSchema.required?.includes(k) ? '' : '?'}: ${formatSchemaType(v)}`)
+                .join(', ')
+            : '';
+        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, prefix = '') {
+    if (!schema?.properties)
+        return [];
+    const paths = [];
+    for (const [key, prop] of Object.entries(schema.properties)) {
+        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, mode) {
     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.');
+            "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' +
@@ -19,66 +103,94 @@ export function buildDynamicWorkflowInstructions(tools, mode) {
             '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 = [];
+    const toolSummaryLines = [];
     for (const toolName of tools) {
-        let fnMeta;
-        let schemas;
-        const resolved = toolName.includes(':') ? resolveNamespace(toolName) : 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');
-        }
-        if (!fnMeta)
+        const meta = resolveToolMetaForWorkflow(toolName);
+        if (!meta)
             continue;
-        const inputSchema = fnMeta.inputSchemaName
-            ? schemas.get(fnMeta.inputSchemaName)
-            : null;
-        const outputSchema = fnMeta.outputSchemaName
-            ? schemas.get(fnMeta.outputSchemaName)
-            : null;
-        const toolDescription = fnMeta.description || fnMeta.title || '';
-        const inputProps = inputSchema?.properties
-            ? Object.entries(inputSchema.properties)
-                .map(([k, v]) => `${k}${inputSchema.required?.includes(k) ? '' : '?'}: ${v.type || 'any'}`)
-                .join(', ')
+        const { fnMeta, inputSchema, outputSchema } = meta;
+        const desc = fnMeta.description || fnMeta.title || '';
+        const inputFields = inputSchema?.properties
+            ? Object.keys(inputSchema.properties).join(', ')
             : '';
-        const outputProps = outputSchema?.properties
-            ? Object.entries(outputSchema.properties)
-                .map(([k, v]) => `${k}: ${v.type || 'any'}`)
-                .join(', ')
-            : 'any';
-        toolSchemaLines.push(`- ${toolName}(input: {${inputProps}}) → {${outputProps}}${toolDescription ? ` — ${toolDescription}` : ''}`);
+        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 = [
+        '\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(agentName, packageName, toolNames, mode, streamContext, sessionService) {
     const tools = [];
     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.',
+            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: {
@@ -92,7 +204,7 @@ export function buildWorkflowTools(agentName, packageName, toolNames, mode, stre
                     },
                     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":{}}}',
+                        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'],
@@ -117,11 +229,18 @@ export function buildWorkflowTools(agentName, packageName, toolNames, mode, stre
                         error: 'A workflow must have at least 2 nodes. A single node is just a tool call — use the tool directly instead.',
                     };
                 }
+                const usedTools = [
+                    ...new Set(Object.values(nodes)
+                        .map((n) => 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 entryNodeIds = computeEntryNodeIds(nodes);
@@ -152,7 +271,8 @@ export function buildWorkflowTools(agentName, packageName, toolNames, mode, stre
                     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.`,
+                    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.`,
                 };
             },
         });

package/dist/wirings/ai-agent/ai-agent-prepare.js

@@ -1,4 +1,5 @@
 import { PikkuError } from '../../errors/error-handler.js';
+import { AIProviderNotConfiguredError } from '../../errors/errors.js';
 import { pikkuState, getSingletonServices } from '../../pikku-state.js';
 import { createMiddlewareSessionWireProps } from '../../services/user-session-service.js';
 import { randomUUID } from 'crypto';
@@ -354,7 +355,7 @@ export async function prepareAgentRun(agentName, input, params, agentSessionMap,
     const { agent, packageName, resolvedName } = resolveAgent(agentName);
     const agentRunner = singletonServices.aiAgentRunner;
     if (!agentRunner) {
-        throw new Error('AIAgentRunnerService not available in singletonServices');
+        throw new AIProviderNotConfiguredError();
     }
     if (agent.dynamicWorkflows && singletonServices.workflowService) {
         const persisted = await singletonServices.workflowService.getAIGeneratedWorkflows(resolvedName);

package/dist/wirings/ai-agent/ai-agent-runner.js

@@ -3,6 +3,7 @@ import { prepareAgentRun, resolveAgent, buildInstructions, buildToolDefs, } from
 import { checkForApprovals, appendStepMessages } from './ai-agent-stream.js';
 import { pikkuState, getSingletonServices } from '../../pikku-state.js';
 import { resolveModelConfig } from './ai-agent-model-config.js';
+import { AIProviderNotConfiguredError } from '../../errors/errors.js';
 import { randomUUID } from 'crypto';
 export async function runAIAgent(agentName, input, params, agentSessionMap) {
     const sessionMap = agentSessionMap ?? new Map();
@@ -262,7 +263,7 @@ export async function resumeAIAgentSync(runId, approvals, params, expectedAgentN
     const memoryConfig = agent.memory;
     const agentRunner = singletonServices.aiAgentRunner;
     if (!agentRunner) {
-        throw new Error('AIAgentRunnerService not available');
+        throw new AIProviderNotConfiguredError();
     }
     const approvedIds = new Set(approvals.filter((a) => a.approved).map((a) => a.toolCallId));
     const rejectedIds = new Set(approvals.filter((a) => !a.approved).map((a) => a.toolCallId));

package/dist/wirings/ai-agent/ai-agent-stream.js

@@ -1,4 +1,5 @@
 import { pikkuState, getSingletonServices } from '../../pikku-state.js';
+import { AIProviderNotConfiguredError } from '../../errors/errors.js';
 import { combineChannelMiddleware, wrapChannelWithMiddleware, } from '../channel/channel-middleware-runner.js';
 import { randomUUID } from 'crypto';
 import { parseWorkingMemory, deepMergeWorkingMemory, resolveMemoryServices, loadContextMessages, trimMessages, } from './ai-agent-memory.js';
@@ -471,7 +472,7 @@ export async function resumeAIAgent(input, channel, params, options) {
     const memoryConfig = agent.memory;
     const agentRunner = singletonServices.aiAgentRunner;
     if (!agentRunner) {
-        throw new Error('AIAgentRunnerService not available in singletonServices');
+        throw new AIProviderNotConfiguredError();
     }
     if (!input.approved) {
         if (pending.type === 'agent-call') {

package/dist/wirings/channel/local/local-channel-runner.js

@@ -3,6 +3,8 @@ import { createHTTPWire } from '../../http/http-runner.js';
 import { closeWireServices } from '../../../utils.js';
 import { processMessageHandlers } from '../channel-handler.js';
 import { PikkuLocalChannelHandler } from './local-channel-handler.js';
+import { isProduction } from '../../../env.js';
+import { getErrorResponse } from '../../../errors/error-handler.js';
 import { handleHTTPError } from '../../../handle-error.js';
 import { PikkuSessionService, createMiddlewareSessionWireProps, } from '../../../services/user-session-service.js';
 import { runChannelLifecycleWithMiddleware } from '../channel-common.js';
@@ -75,9 +77,10 @@ export const runLocalChannel = async ({ channelId, request, response, route, ski
                     }
                     catch (e) {
                         singletonServices.logger.error(`Error handling onConnect: ${e}`);
+                        const errorResponse = getErrorResponse(e);
                         channel.send({
-                            error: e.message || 'Unknown error',
-                            errorName: e.constructor?.name,
+                            error: errorResponse?.message ?? (isProduction() ? 'Internal server error' : e.message),
+                            ...(!isProduction() && { errorName: e.constructor?.name }),
                         });
                     }
                 }
@@ -97,9 +100,10 @@ export const runLocalChannel = async ({ channelId, request, response, route, ski
                     }
                     catch (e) {
                         singletonServices.logger.error(`Error handling onDisconnect: ${e}`);
+                        const errorResponse = getErrorResponse(e);
                         channel.send({
-                            error: e.message || 'Unknown error',
-                            errorName: e.constructor?.name,
+                            error: errorResponse?.message ?? (isProduction() ? 'Internal server error' : e.message),
+                            ...(!isProduction() && { errorName: e.constructor?.name }),
                         });
                     }
                 }
@@ -113,9 +117,10 @@ export const runLocalChannel = async ({ channelId, request, response, route, ski
                 }
                 catch (e) {
                     singletonServices.logger.error(e);
+                    const errorResponse = getErrorResponse(e);
                     channel.send({
-                        error: e.message || 'Unknown error',
-                        errorName: e.constructor?.name,
+                        error: errorResponse?.message ?? (isProduction() ? 'Internal server error' : e.message),
+                        ...(!isProduction() && { errorName: e.constructor?.name }),
                     });
                     setTimeout(() => channel.close(), 200);
                 }

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

@@ -0,0 +1,24 @@
+import type { OAuth2CredentialConfig } from '../secret/secret.types.js';
+export type CoreCredential<T = unknown> = {
+    name: string;
+    displayName: string;
+    description?: string;
+    type: 'singleton' | 'wire';
+    schema: T;
+    oauth2?: OAuth2CredentialConfig & {
+        appCredentialSecretId: string;
+    };
+};
+export type CredentialDefinitionMeta = {
+    name: string;
+    displayName: string;
+    description?: string;
+    type: 'singleton' | 'wire';
+    schema?: Record<string, unknown> | string;
+    oauth2?: OAuth2CredentialConfig & {
+        appCredentialSecretId: string;
+    };
+    sourceFile?: string;
+};
+export type CredentialDefinitionsMeta = Record<string, CredentialDefinitionMeta>;
+export type CredentialDefinitions = CredentialDefinitionMeta[];

package/dist/wirings/credential/credential.types.js

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

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

@@ -0,0 +1,3 @@
+export { wireCredential } from './wire-credential.js';
+export { validateAndBuildCredentialDefinitionsMeta } from './validate-credential-definitions.js';
+export type { CoreCredential, CredentialDefinitionMeta, CredentialDefinitionsMeta, CredentialDefinitions, } from './credential.types.js';

package/dist/wirings/credential/index.js

@@ -0,0 +1,2 @@
+export { wireCredential } from './wire-credential.js';
+export { validateAndBuildCredentialDefinitionsMeta } from './validate-credential-definitions.js';

package/dist/wirings/credential/validate-credential-definitions.d.ts

@@ -0,0 +1,6 @@
+import type { CredentialDefinitions, CredentialDefinitionsMeta } from './credential.types.js';
+export interface SchemaRefLike {
+    variableName: string;
+    sourceFile: string;
+}
+export declare function validateAndBuildCredentialDefinitionsMeta(definitions: CredentialDefinitions, schemaLookup: Map<string, SchemaRefLike>): CredentialDefinitionsMeta;