@pikku/core 0.12.9 → 0.12.11

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/cli/channel/cli-raw-channel-runner.d.ts

@@ -0,0 +1,15 @@
+import type { CoreSingletonServices, CreateWireServices } from '../../../types/core.types.js';
+/**
+ * Handles raw CLI input from a WebSocket channel.
+ * Parses the args, resolves the command, and either returns help or executes it.
+ */
+export declare function handleRawCLI({ programName, args, singletonServices, createWireServices, }: {
+    programName: string;
+    args: string[];
+    singletonServices: CoreSingletonServices;
+    createWireServices?: CreateWireServices;
+}): Promise<{
+    help?: string;
+    result?: unknown;
+    error?: string;
+}>;

package/dist/wirings/cli/channel/cli-raw-channel-runner.js

@@ -0,0 +1,58 @@
+import { pikkuState } from '../../../pikku-state.js';
+import { parseCLIArguments, generateCommandHelp } from '../command-parser.js';
+import { runCLICommand } from '../cli-runner.js';
+/**
+ * Handles raw CLI input from a WebSocket channel.
+ * Parses the args, resolves the command, and either returns help or executes it.
+ */
+export async function handleRawCLI({ programName, args, singletonServices, createWireServices, }) {
+    const allCLIMeta = pikkuState(null, 'cli', 'meta');
+    if (!allCLIMeta) {
+        return { error: 'CLI metadata not found' };
+    }
+    const programMeta = allCLIMeta.programs[programName];
+    if (!programMeta) {
+        return { error: `Program "${programName}" not found` };
+    }
+    // Handle empty input or explicit help
+    if (args.length === 0 ||
+        args.includes('--help') ||
+        args.includes('-h') ||
+        args[0] === 'help') {
+        const helpArgs = args.filter((a) => a !== 'help' && a !== '--help' && a !== '-h');
+        const helpText = generateCommandHelp(programName, allCLIMeta, helpArgs);
+        return { help: helpText };
+    }
+    // Parse the args
+    const parsed = parseCLIArguments(args, programName, allCLIMeta);
+    // If there are errors or the command resolves to a group (no function), show help
+    if (parsed.errors.length > 0 || parsed.commandPath.length === 0) {
+        const helpText = generateCommandHelp(programName, allCLIMeta, parsed.commandPath);
+        return { help: helpText };
+    }
+    // Check if the resolved command has a pikkuFuncId (is executable)
+    let current = programMeta.commands[parsed.commandPath[0]];
+    for (let i = 1; i < parsed.commandPath.length; i++) {
+        current = current?.subcommands?.[parsed.commandPath[i]];
+    }
+    if (!current?.pikkuFuncId) {
+        // It's a group command — show help scoped to that group
+        const helpText = generateCommandHelp(programName, allCLIMeta, parsed.commandPath);
+        return { help: helpText };
+    }
+    // Execute the command
+    const data = { ...parsed.positionals, ...parsed.options };
+    try {
+        const result = await runCLICommand({
+            program: programName,
+            commandPath: parsed.commandPath,
+            data,
+            singletonServices,
+            createWireServices,
+        });
+        return { result };
+    }
+    catch (e) {
+        return { error: e.message };
+    }
+}

package/dist/wirings/cli/channel/index.d.ts

@@ -1 +1,2 @@
 export { executeCLIViaChannel } from './cli-channel-runner.js';
+export { handleRawCLI } from './cli-raw-channel-runner.js';

package/dist/wirings/cli/channel/index.js

@@ -1 +1,2 @@
 export { executeCLIViaChannel } from './cli-channel-runner.js';
+export { handleRawCLI } from './cli-raw-channel-runner.js';

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;

package/dist/wirings/credential/validate-credential-definitions.js

@@ -0,0 +1,38 @@
+export function validateAndBuildCredentialDefinitionsMeta(definitions, schemaLookup) {
+    const meta = {};
+    for (const def of definitions) {
+        const existing = meta[def.name];
+        if (existing) {
+            if (def.schema && existing.schema) {
+                const defSchemaRef = schemaLookup.get(def.schema);
+                const existingSchemaRef = schemaLookup.get(existing.schema);
+                if (defSchemaRef && existingSchemaRef) {
+                    if (defSchemaRef.variableName !== existingSchemaRef.variableName ||
+                        defSchemaRef.sourceFile !== existingSchemaRef.sourceFile) {
+                        throw new Error(`Credential '${def.name}' is defined with different schemas.\n` +
+                            `  First definition: ${existing.sourceFile} (schema: ${existingSchemaRef.variableName})\n` +
+                            `  Second definition: ${def.sourceFile} (schema: ${defSchemaRef.variableName})\n` +
+                            `Credentials sharing a name must use the same schema.`);
+                    }
+                }
+            }
+            if (def.type !== existing.type) {
+                throw new Error(`Credential '${def.name}' is defined with different types.\n` +
+                    `  First definition: ${existing.sourceFile} (type: ${existing.type})\n` +
+                    `  Second definition: ${def.sourceFile} (type: ${def.type})\n` +
+                    `Credentials sharing a name must use the same type.`);
+            }
+            continue;
+        }
+        meta[def.name] = {
+            name: def.name,
+            displayName: def.displayName,
+            description: def.description,
+            type: def.type,
+            schema: def.schema,
+            oauth2: def.oauth2,
+            sourceFile: def.sourceFile,
+        };
+    }
+    return meta;
+}

package/dist/wirings/credential/wire-credential.d.ts

@@ -0,0 +1,48 @@
+import type { CoreCredential } from './credential.types.js';
+/**
+ * No-op function for declaring credentials.
+ * This exists purely for TypeScript type checking and will be tree-shaken.
+ * The CLI extracts metadata via AST parsing.
+ *
+ * @example
+ * ```typescript
+ * // Per-user API key
+ * wireCredential({
+ *   name: 'stripe',
+ *   displayName: 'Stripe API Key',
+ *   type: 'wire',
+ *   schema: z.object({ apiKey: z.string() }),
+ * })
+ *
+ * // Per-user OAuth
+ * wireCredential({
+ *   name: 'google-sheets',
+ *   displayName: 'Google Sheets',
+ *   type: 'wire',
+ *   schema: z.object({ accessToken: z.string(), refreshToken: z.string() }),
+ *   oauth2: {
+ *     appCredentialSecretId: 'GOOGLE_OAUTH_APP',
+ *     authorizationUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
+ *     tokenUrl: 'https://oauth2.googleapis.com/token',
+ *     scopes: ['https://www.googleapis.com/auth/spreadsheets'],
+ *     tokenSecretId: 'GOOGLE_OAUTH_TOKENS',
+ *   }
+ * })
+ *
+ * // Platform-level OAuth (singleton)
+ * wireCredential({
+ *   name: 'slack',
+ *   displayName: 'Slack',
+ *   type: 'singleton',
+ *   schema: z.object({ accessToken: z.string(), refreshToken: z.string() }),
+ *   oauth2: {
+ *     appCredentialSecretId: 'SLACK_OAUTH_APP',
+ *     authorizationUrl: 'https://slack.com/oauth/v2/authorize',
+ *     tokenUrl: 'https://slack.com/api/oauth.v2.access',
+ *     scopes: ['chat:write', 'channels:read'],
+ *     tokenSecretId: 'SLACK_OAUTH_TOKENS',
+ *   }
+ * })
+ * ```
+ */
+export declare const wireCredential: <T>(_config: CoreCredential<T>) => void;

package/dist/wirings/credential/wire-credential.js

@@ -0,0 +1,47 @@
+/**
+ * No-op function for declaring credentials.
+ * This exists purely for TypeScript type checking and will be tree-shaken.
+ * The CLI extracts metadata via AST parsing.
+ *
+ * @example
+ * ```typescript
+ * // Per-user API key
+ * wireCredential({
+ *   name: 'stripe',
+ *   displayName: 'Stripe API Key',
+ *   type: 'wire',
+ *   schema: z.object({ apiKey: z.string() }),
+ * })
+ *
+ * // Per-user OAuth
+ * wireCredential({
+ *   name: 'google-sheets',
+ *   displayName: 'Google Sheets',
+ *   type: 'wire',
+ *   schema: z.object({ accessToken: z.string(), refreshToken: z.string() }),
+ *   oauth2: {
+ *     appCredentialSecretId: 'GOOGLE_OAUTH_APP',
+ *     authorizationUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
+ *     tokenUrl: 'https://oauth2.googleapis.com/token',
+ *     scopes: ['https://www.googleapis.com/auth/spreadsheets'],
+ *     tokenSecretId: 'GOOGLE_OAUTH_TOKENS',
+ *   }
+ * })
+ *
+ * // Platform-level OAuth (singleton)
+ * wireCredential({
+ *   name: 'slack',
+ *   displayName: 'Slack',
+ *   type: 'singleton',
+ *   schema: z.object({ accessToken: z.string(), refreshToken: z.string() }),
+ *   oauth2: {
+ *     appCredentialSecretId: 'SLACK_OAUTH_APP',
+ *     authorizationUrl: 'https://slack.com/oauth/v2/authorize',
+ *     tokenUrl: 'https://slack.com/api/oauth.v2.access',
+ *     scopes: ['chat:write', 'channels:read'],
+ *     tokenSecretId: 'SLACK_OAUTH_TOKENS',
+ *   }
+ * })
+ * ```
+ */
+export const wireCredential = (_config) => { };

package/dist/wirings/http/http-runner.js

@@ -3,6 +3,7 @@ import { closeWireServices, createWeakUID, isSerializable, } from '../../utils.j
 import { getSingletonServices, getCreateWireServices, } from '../../pikku-state.js';
 import { PikkuSessionService } from '../../services/user-session-service.js';
 import { getErrorResponse } from '../../errors/error-handler.js';
+import { PikkuCredentialWireService, createMiddlewareCredentialWireProps, } from '../../services/credential-wire-service.js';
 import { handleHTTPError } from '../../handle-error.js';
 import { pikkuState } from '../../pikku-state.js';
 import { PikkuFetchHTTPResponse } from './pikku-fetch-http-response.js';
@@ -197,6 +198,7 @@ export const createHTTPWire = (request, response) => {
  */
 const executeRoute = async (services, matchedRoute, http, options) => {
     const userSession = new PikkuSessionService();
+    const credentialWire = new PikkuCredentialWireService();
     const { params, route, meta } = matchedRoute;
     const { singletonServices, createWireServices, skipUserSession, requestId } = services;
     // Attach URL parameters to the request object
@@ -257,6 +259,7 @@ const executeRoute = async (services, matchedRoute, http, options) => {
         setSession: (s) => userSession.setInitial(s),
         getSession: () => userSession.get(),
         hasSessionChanged: () => userSession.sessionChanged,
+        ...createMiddlewareCredentialWireProps(credentialWire),
     };
     result = await runPikkuFunc('http', `${meta.method}:${meta.route}`, meta.pikkuFuncId, {
         singletonServices,
@@ -271,6 +274,7 @@ const executeRoute = async (services, matchedRoute, http, options) => {
         tags: route.tags,
         wire,
         sessionService: userSession,
+        credentialWireService: credentialWire,
         packageName: meta.packageName,
     });
     if (!matchedRoute.route.sse) {

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

@@ -1,3 +1,4 @@
 export { OAuth2Client } from './oauth2-client.js';
-export { wireOAuth2Credential } from './wire-oauth2-credential.js';
+export { createOAuth2Handler } from './oauth2-routes.js';
+export type { CreateOAuth2HandlerOptions } from './oauth2-routes.js';
 export type { OAuth2AppCredential, OAuth2Token } from './oauth2.types.js';

package/dist/wirings/oauth2/index.js

@@ -1,2 +1,2 @@
 export { OAuth2Client } from './oauth2-client.js';
-export { wireOAuth2Credential } from './wire-oauth2-credential.js';
+export { createOAuth2Handler } from './oauth2-routes.js';

package/dist/wirings/oauth2/oauth2-client.js

@@ -26,7 +26,8 @@
  * })
  * ```
  */
-const DEFAULT_TIMEOUT_MS = 30000;
+const DEFAULT_TIMEOUT_MS = 30_000;
+const TOKEN_EXPIRY_BUFFER_MS = 60_000;
 /**
  * Helper to fetch with a timeout using AbortController.
  */
@@ -114,16 +115,13 @@ export class OAuth2Client {
      * Uses a promise lock to prevent concurrent refresh attempts.
      */
     async refreshAndGetToken() {
-        // If already refreshing, wait for that to complete
         if (this.refreshPromise) {
             const token = await this.refreshPromise;
             return token.accessToken;
         }
-        // Start refresh
         this.refreshPromise = this.doRefreshToken();
         try {
             const token = await this.refreshPromise;
-            this.cachedToken = token;
             return token.accessToken;
         }
         finally {
@@ -169,9 +167,8 @@ export class OAuth2Client {
             tokenType: data.token_type || 'Bearer',
             scope: data.scope,
         };
-        // Cache and persist the refreshed token
-        this.cachedToken = token;
         await this.secrets.setSecretJSON(this.oauth2Config.tokenSecretId, token);
+        this.cachedToken = token;
         return token;
     }
     /**
@@ -181,8 +178,7 @@ export class OAuth2Client {
         if (!token.expiresAt) {
             return true; // No expiry info, assume valid
         }
-        // Add 60 second buffer to account for clock skew
-        return token.expiresAt > Date.now() + 60000;
+        return token.expiresAt > Date.now() + TOKEN_EXPIRY_BUFFER_MS;
     }
     /**
      * Get app credentials (cached).