@pikku/core 0.12.13 → 0.12.14

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 ## 0.12.4
 
+## 0.12.14
+
+### Patch Changes
+
+- f85c234: Add unified credential system with per-user OAuth and AI agent pre-flight checks
+
+  - Unified CredentialService with lazy loading per user via pikkuUserId
+  - wire.getCredential() for typed single credential lookup
+  - MissingCredentialError with structured payload for client-side connect flows
+  - Console UI: Global/Users credential tabs, per-user OAuth connect/revoke
+  - AI agent pre-flight check: detects missing OAuth credentials from addon metadata, shows "Connect your accounts" prompt before chat
+  - CLI codegen: generates credentialsMeta per addon package for runtime lookup
+  - Vercel AI runner: catches MissingCredentialError as runtime fallback
+
+- 88d3100: Fix CLI command resolution for addon functions by passing packageName to addFunction during registration.
+
 ## 0.12.13
 
 ### Patch Changes

package/dist/errors/errors.d.ts

@@ -42,6 +42,20 @@ export declare class PaymentRequiredError extends PikkuError {
  */
 export declare class ForbiddenError extends PikkuError {
 }
+/**
+ * A required credential is missing. The payload contains metadata
+ * about the credential so the client can initiate a connect flow.
+ * @group Error
+ */
+export declare class MissingCredentialError extends PikkuError {
+    payload: {
+        error: 'missing_credential';
+        credentialName: string;
+        credentialType: 'oauth2' | 'apikey';
+        connectUrl?: string;
+    };
+    constructor(credentialName: string, credentialType: 'oauth2' | 'apikey', connectUrl?: string);
+}
 /**
  * The session is readonly and cannot access a non-readonly function.
  * @group Error

package/dist/errors/errors.js

@@ -72,6 +72,27 @@ addError(ForbiddenError, {
     status: 403,
     message: 'The client does not have permission to access the requested resource.',
 });
+/**
+ * A required credential is missing. The payload contains metadata
+ * about the credential so the client can initiate a connect flow.
+ * @group Error
+ */
+export class MissingCredentialError extends PikkuError {
+    payload;
+    constructor(credentialName, credentialType, connectUrl) {
+        super(`Missing credential: ${credentialName}`);
+        this.payload = {
+            error: 'missing_credential',
+            credentialName,
+            credentialType,
+            connectUrl,
+        };
+    }
+}
+addError(MissingCredentialError, {
+    status: 403,
+    message: 'A required credential is not configured.',
+});
 /**
  * The session is readonly and cannot access a non-readonly function.
  * @group Error

package/dist/function/function-runner.d.ts

@@ -2,7 +2,7 @@ import type { CoreServices, CoreUserSession, CorePikkuMiddleware, PikkuWiringTyp
 import type { CorePikkuChannelMiddleware } from '../wirings/channel/channel.types.js';
 import type { CorePermissionGroup, CorePikkuFunctionConfig, CorePikkuPermission } from './functions.types.js';
 import type { SessionService } from '../services/user-session-service.js';
-import type { PikkuCredentialWireService } from '../services/credential-wire-service.js';
+import { PikkuCredentialWireService } from '../services/credential-wire-service.js';
 export declare const addFunction: (funcName: string, funcConfig: CorePikkuFunctionConfig<any, any>, packageName?: string | null) => void;
 export declare const getFunctionNames: (packageName?: string | null) => string[];
 export declare const getAllFunctionNames: () => string[];

package/dist/function/function-runner.js

@@ -6,7 +6,7 @@ import { coerceTopLevelDataFromSchema, validateSchema } from '../schema.js';
 import { parseVersionedId } from '../version.js';
 import { createFunctionSessionWireProps } from '../services/user-session-service.js';
 import { ForbiddenError, ReadonlySessionError } from '../errors/errors.js';
-import { createWireServicesCredentialWireProps } from '../services/credential-wire-service.js';
+import { PikkuCredentialWireService, createWireServicesCredentialWireProps, } from '../services/credential-wire-service.js';
 import { rpcService } from '../wirings/rpc/rpc-runner.js';
 import { closeWireServices } from '../utils.js';
 /**
@@ -114,6 +114,13 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
     const resolvedWire = allChannelMiddleware.length > 0 && wire.channel
         ? wrapChannelWithMiddleware(wire, resolvedSingletonServices, allChannelMiddleware)
         : wire;
+    // Set up credential wire service early so middleware can use setCredential.
+    // Skip if already set up (e.g. addon functions reuse the parent wire).
+    if (!resolvedWire.getCredentials) {
+        const resolvedCredentialWireService = credentialWireService ??
+            new PikkuCredentialWireService(resolvedSingletonServices.credentialService, resolvedWire);
+        Object.assign(resolvedWire, createWireServicesCredentialWireProps(resolvedCredentialWireService));
+    }
     // Convert tags to PermissionMetadata and merge with inheritedPermissions
     let mergedInheritedPermissions;
     if (tags && tags.length > 0) {
@@ -189,9 +196,6 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
                 packageName,
             });
         }
-        if (credentialWireService) {
-            Object.assign(resolvedWire, createWireServicesCredentialWireProps(credentialWireService));
-        }
         const wireServices = await resolvedCreateWireServices?.(resolvedSingletonServices, resolvedWire);
         try {
             const services = wireServices && Object.keys(wireServices).length > 0

package/dist/pikku-state.js

@@ -127,6 +127,7 @@ const createEmptyPackageState = () => ({
         factories: null,
         singletonServices: null,
         metaDir: null,
+        credentialsMeta: null,
     },
 });
 /**

package/dist/services/credential-service.d.ts

@@ -37,4 +37,15 @@ export interface CredentialService {
      * @returns A record of credential name to value.
      */
     getAll(userId: string): Promise<Record<string, unknown>>;
+    /**
+     * Lists all user IDs that have a specific credential configured.
+     * @param name - The credential name.
+     * @returns Array of user IDs.
+     */
+    getUsersWithCredential(name: string): Promise<string[]>;
+    /**
+     * Lists all unique user IDs that have any credential configured.
+     * @returns Array of user IDs.
+     */
+    getAllUsers(): Promise<string[]>;
 }

package/dist/services/credential-wire-service.d.ts

@@ -1,13 +1,24 @@
+import type { CredentialService } from './credential-service.js';
+import type { PikkuWire } from '../types/core.types.js';
 export declare class PikkuCredentialWireService {
+    private credentialService?;
+    private wire?;
     private credentials;
+    private loaded;
+    private loadPromise;
+    constructor(credentialService?: CredentialService | undefined, wire?: PikkuWire | undefined);
     set(name: string, value: unknown): void;
-    getAll(): Record<string, unknown>;
-    getScoped(allowedNames: string[]): Record<string, unknown>;
+    get<T = unknown>(name: string): T | null | Promise<T | null>;
+    getAll(): Record<string, unknown> | Promise<Record<string, unknown>>;
+    getScoped(allowedNames: string[]): Record<string, unknown> | Promise<Record<string, unknown>>;
+    private lazyLoad;
+    private doLoad;
 }
 export declare function createMiddlewareCredentialWireProps(credentialWire: PikkuCredentialWireService): {
     setCredential: (name: string, value: unknown) => void;
 };
 export declare function createWireServicesCredentialWireProps(credentialWire: PikkuCredentialWireService, allowedNames?: string[]): {
     setCredential: (name: string, value: unknown) => void;
-    getCredentials: () => Record<string, unknown>;
+    getCredential: <T = unknown>(name: string) => T | Promise<T | null> | null;
+    getCredentials: () => Record<string, unknown> | Promise<Record<string, unknown>>;
 };

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

@@ -1,19 +1,61 @@
+import { defaultPikkuUserIdResolver } from './pikku-user-id.js';
 export class PikkuCredentialWireService {
+    credentialService;
+    wire;
     credentials = {};
+    loaded = false;
+    loadPromise;
+    constructor(credentialService, wire) {
+        this.credentialService = credentialService;
+        this.wire = wire;
+    }
     set(name, value) {
         this.credentials[name] = value;
     }
+    get(name) {
+        if (this.loaded)
+            return this.credentials[name] ?? null;
+        return this.lazyLoad().then(() => this.credentials[name] ?? null);
+    }
     getAll() {
-        return this.credentials;
+        if (this.loaded)
+            return this.credentials;
+        return this.lazyLoad().then(() => this.credentials);
     }
     getScoped(allowedNames) {
-        const scoped = {};
-        for (const name of allowedNames) {
-            if (name in this.credentials) {
-                scoped[name] = this.credentials[name];
+        const buildScoped = () => {
+            const scoped = {};
+            for (const name of allowedNames) {
+                if (name in this.credentials) {
+                    scoped[name] = this.credentials[name];
+                }
+            }
+            return scoped;
+        };
+        if (this.loaded)
+            return buildScoped();
+        return this.lazyLoad().then(buildScoped);
+    }
+    lazyLoad() {
+        if (this.loadPromise)
+            return this.loadPromise;
+        this.loadPromise = this.doLoad();
+        return this.loadPromise;
+    }
+    async doLoad() {
+        this.loaded = true;
+        if (!this.credentialService || !this.wire)
+            return;
+        const userId = defaultPikkuUserIdResolver(this.wire);
+        if (!userId)
+            return;
+        this.wire.pikkuUserId = userId;
+        const allCreds = await this.credentialService.getAll(userId);
+        for (const [name, value] of Object.entries(allCreds)) {
+            if (!(name in this.credentials)) {
+                this.credentials[name] = value;
             }
         }
-        return scoped;
     }
 }
 export function createMiddlewareCredentialWireProps(credentialWire) {
@@ -24,6 +66,7 @@ export function createMiddlewareCredentialWireProps(credentialWire) {
 export function createWireServicesCredentialWireProps(credentialWire, allowedNames) {
     return {
         setCredential: (name, value) => credentialWire.set(name, value),
+        getCredential: (name) => credentialWire.get(name),
         getCredentials: () => allowedNames
             ? credentialWire.getScoped(allowedNames)
             : credentialWire.getAll(),

package/dist/services/local-credential-service.d.ts

@@ -7,4 +7,6 @@ export declare class LocalCredentialService implements CredentialService {
     delete(name: string, userId?: string): Promise<void>;
     has(name: string, userId?: string): Promise<boolean>;
     getAll(userId: string): Promise<Record<string, unknown>>;
+    getUsersWithCredential(name: string): Promise<string[]>;
+    getAllUsers(): Promise<string[]>;
 }

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

@@ -30,4 +30,24 @@ export class LocalCredentialService {
         }
         return result;
     }
+    async getUsersWithCredential(name) {
+        const suffix = `:${name}`;
+        const users = [];
+        for (const key of this.store.keys()) {
+            if (key.endsWith(suffix)) {
+                users.push(key.slice(0, -suffix.length));
+            }
+        }
+        return users;
+    }
+    async getAllUsers() {
+        const users = new Set();
+        for (const key of this.store.keys()) {
+            const colonIndex = key.indexOf(':');
+            if (colonIndex > 0) {
+                users.add(key.slice(0, colonIndex));
+            }
+        }
+        return [...users];
+    }
 }

package/dist/services/pikku-user-id.d.ts

@@ -0,0 +1,3 @@
+import type { PikkuWire } from '../types/core.types.js';
+export type PikkuUserIdResolver = (wire: PikkuWire) => string | undefined;
+export declare const defaultPikkuUserIdResolver: PikkuUserIdResolver;

package/dist/services/pikku-user-id.js

@@ -0,0 +1,16 @@
+export const defaultPikkuUserIdResolver = (wire) => {
+    // Explicit pikkuUserId on wire (set by earlier middleware or runner)
+    if (wire.pikkuUserId)
+        return wire.pikkuUserId;
+    // Session userId (from auth middleware — user-defined session shape)
+    const session = wire.session;
+    if (session?.userId && typeof session.userId === 'string')
+        return session.userId;
+    // Queue job: carried in job metadata
+    if (wire.queue?.pikkuUserId)
+        return wire.queue.pikkuUserId;
+    // Workflow: carried in run wire metadata
+    if (wire.workflow?.pikkuUserId)
+        return wire.workflow.pikkuUserId;
+    return undefined;
+};

package/dist/services/typed-credential-service.d.ts

@@ -22,6 +22,8 @@ export declare class TypedCredentialService<TMap = Record<string, unknown>> impl
     delete(name: string, userId?: string): Promise<void>;
     has(name: string, userId?: string): Promise<boolean>;
     getAll(userId: string): Promise<Record<string, unknown>>;
+    getUsersWithCredential(name: string): Promise<string[]>;
+    getAllUsers(): Promise<string[]>;
     getAllStatus(userId?: string): Promise<CredentialStatusInfo[]>;
     getMissing(userId?: string): Promise<CredentialStatusInfo[]>;
 }

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

@@ -20,6 +20,12 @@ export class TypedCredentialService {
     async getAll(userId) {
         return this.credentials.getAll(userId);
     }
+    async getUsersWithCredential(name) {
+        return this.credentials.getUsersWithCredential(name);
+    }
+    async getAllUsers() {
+        return this.credentials.getAllUsers();
+    }
     async getAllStatus(userId) {
         const results = [];
         for (const [name, meta] of Object.entries(this.credentialsMeta)) {

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

@@ -203,10 +203,14 @@ 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;
+    /** The resolved user identity for credential lookups */
+    pikkuUserId: string;
     /** 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>;
+    /** Get a single credential by name — lazy-loads from CredentialService on first call, sync thereafter */
+    getCredential: <T = unknown>(name: string) => T | null | Promise<T | null>;
+    /** Get all resolved credentials — lazy-loads from CredentialService on first call, sync thereafter */
+    getCredentials: () => Record<string, unknown> | Promise<Record<string, unknown>>;
 }>;
 /**
  * A function that can wrap an wire and be called before or after

package/dist/types/state.types.d.ts

@@ -132,5 +132,12 @@ export interface PikkuPackageState {
         singletonServices: CoreSingletonServices | null;
         /** Absolute path to this package's .pikku directory */
         metaDir: string | null;
+        /** Credential metadata for this addon package */
+        credentialsMeta: Record<string, {
+            name: string;
+            displayName: string;
+            type: string;
+            oauth2?: boolean;
+        }> | null;
     };
 }

package/dist/wirings/ai-agent/ai-agent-prepare.d.ts

@@ -19,6 +19,27 @@ export declare class ToolApprovalRequired extends PikkuError {
     readonly agentRunId?: string;
     constructor(toolCallId: string, toolName: string, args: unknown, reason?: string, displayToolName?: string, displayArgs?: unknown, agentRunId?: string);
 }
+export declare class ToolCredentialRequired extends PikkuError {
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly args: unknown;
+    readonly credentialName: string;
+    readonly credentialType: 'oauth2' | 'apikey';
+    readonly connectUrl?: string;
+    constructor(toolCallId: string, toolName: string, args: unknown, credentialName: string, credentialType: 'oauth2' | 'apikey', connectUrl?: string);
+}
+export interface AddonCredentialRequirement {
+    credentialName: string;
+    displayName: string;
+    addonNamespace: string;
+    type: 'wire';
+    oauth2: boolean;
+}
+/**
+ * Given a list of tool names (e.g. ["oauth-api:getProfile"]),
+ * returns the wire OAuth credentials required by their addons.
+ */
+export declare function getAddonCredentialRequirements(toolNames: string[]): AddonCredentialRequirement[];
 export type StreamContext = {
     channel: AIStreamChannel;
     options?: StreamAIAgentOptions;

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

@@ -28,6 +28,52 @@ export class ToolApprovalRequired extends PikkuError {
         this.agentRunId = agentRunId;
     }
 }
+export class ToolCredentialRequired extends PikkuError {
+    toolCallId;
+    toolName;
+    args;
+    credentialName;
+    credentialType;
+    connectUrl;
+    constructor(toolCallId, toolName, args, credentialName, credentialType, connectUrl) {
+        super(`Tool '${toolName}' requires credential '${credentialName}'`);
+        this.toolCallId = toolCallId;
+        this.toolName = toolName;
+        this.args = args;
+        this.credentialName = credentialName;
+        this.credentialType = credentialType;
+        this.connectUrl = connectUrl;
+    }
+}
+/**
+ * Given a list of tool names (e.g. ["oauth-api:getProfile"]),
+ * returns the wire OAuth credentials required by their addons.
+ */
+export function getAddonCredentialRequirements(toolNames) {
+    const requirements = new Map();
+    for (const toolName of toolNames) {
+        if (!toolName.includes(':'))
+            continue;
+        const resolved = resolveNamespace(toolName);
+        if (!resolved)
+            continue;
+        const credsMeta = pikkuState(resolved.package, 'package', 'credentialsMeta');
+        if (!credsMeta)
+            continue;
+        for (const [name, meta] of Object.entries(credsMeta)) {
+            if (meta.type === 'wire' && meta.oauth2 && !requirements.has(name)) {
+                requirements.set(name, {
+                    credentialName: name,
+                    displayName: meta.displayName ?? name,
+                    addonNamespace: toolName.split(':')[0],
+                    type: 'wire',
+                    oauth2: true,
+                });
+            }
+        }
+    }
+    return [...requirements.values()];
+}
 export const resolveAgent = (agentName) => {
     const mainAgent = pikkuState(null, 'agent', 'agents').get(agentName);
     if (mainAgent) {
@@ -324,6 +370,8 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                 }
                 catch (err) {
                     execError = err;
+                    if (err?.payload?.error === 'missing_credential')
+                        throw err;
                     result = err instanceof Error ? err.message : String(err);
                 }
                 const durationMs = Date.now() - startTime;

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

@@ -298,7 +298,12 @@ export async function resumeAIAgentSync(runId, approvals, params, expectedAgentN
                         : JSON.stringify(toolResult);
             }
             catch (err) {
-                resultStr = `Error: ${err instanceof Error ? err.message : String(err)}`;
+                if (err?.payload?.error === 'missing_credential') {
+                    resultStr = JSON.stringify(err.payload);
+                }
+                else {
+                    resultStr = `Error: ${err instanceof Error ? err.message : String(err)}`;
+                }
             }
         }
         else {

package/dist/wirings/ai-agent/ai-agent-stream.d.ts

@@ -1,7 +1,8 @@
 import type { AIStreamChannel } from './ai-agent.types.js';
 import type { AIAgentRunnerParams, AIAgentStepResult } from '../../services/ai-agent-runner-service.js';
-import { ToolApprovalRequired, type RunAIAgentParams, type StreamAIAgentOptions } from './ai-agent-prepare.js';
+import { ToolApprovalRequired, ToolCredentialRequired, type RunAIAgentParams, type StreamAIAgentOptions } from './ai-agent-prepare.js';
 export declare function checkForApprovals(stepResult: AIAgentStepResult, tools: AIAgentRunnerParams['tools'], runId: string): ToolApprovalRequired[];
+export declare function checkForCredentialRequests(stepResult: AIAgentStepResult, runId: string): ToolCredentialRequired[];
 export declare function appendStepMessages(runnerParams: AIAgentRunnerParams, stepResult: AIAgentStepResult): void;
 export declare function streamAIAgent(agentName: string, input: {
     message: string;

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

@@ -3,7 +3,7 @@ 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';
-import { prepareAgentRun, resolveAgent, buildInstructions, buildToolDefs, createScopedChannel, ToolApprovalRequired, } from './ai-agent-prepare.js';
+import { prepareAgentRun, resolveAgent, buildInstructions, buildToolDefs, createScopedChannel, ToolApprovalRequired, ToolCredentialRequired, } from './ai-agent-prepare.js';
 import { resolveModelConfig } from './ai-agent-model-config.js';
 function createPersistingChannel(parent, storage, threadId) {
     let fullText = '';
@@ -197,6 +197,12 @@ async function runStreamStepLoop(params) {
             }
             return { outcome: 'approval', approvals: approvalsNeeded };
         }
+        const credentialRequests = checkForCredentialRequests(stepResult, runId);
+        if (credentialRequests.length > 0) {
+            // Append step messages so the tool result is preserved for resume
+            appendStepMessages(runnerParams, stepResult);
+            return { outcome: 'credential', credentialRequests };
+        }
         appendStepMessages(runnerParams, stepResult);
     }
     return { outcome: 'done' };
@@ -226,6 +232,19 @@ export function checkForApprovals(stepResult, tools, runId) {
     }
     return approvals;
 }
+export function checkForCredentialRequests(stepResult, runId) {
+    const requests = [];
+    for (const tr of stepResult.toolResults) {
+        if (tr.result &&
+            typeof tr.result === 'object' &&
+            '__credentialRequired' in tr.result) {
+            const r = tr.result;
+            const tc = stepResult.toolCalls.find((t) => t.toolCallId === tr.toolCallId);
+            requests.push(new ToolCredentialRequired(tr.toolCallId, tc?.toolName ?? 'unknown', tc?.args ?? {}, r.credentialName, r.credentialType, r.connectUrl));
+        }
+    }
+    return requests;
+}
 export function appendStepMessages(runnerParams, stepResult) {
     const assistantMsg = {
         id: randomUUID(),
@@ -293,6 +312,30 @@ function handleApprovals(approvals, runId, channel, aiRunState, persistingChanne
         channel.close();
     })();
 }
+function handleCredentialRequests(requests, runId, channel, aiRunState, persistingChannel) {
+    return (async () => {
+        await persistingChannel.flush();
+        const pendingApprovals = requests.map((req) => ({
+            type: 'credential-request',
+            toolCallId: req.toolCallId,
+            toolName: req.toolName,
+            args: req.args,
+            credentialName: req.credentialName,
+            credentialType: req.credentialType,
+            connectUrl: req.connectUrl,
+        }));
+        await aiRunState.updateRun(runId, {
+            status: 'suspended',
+            suspendReason: 'credential',
+            pendingApprovals,
+        });
+        // Don't send credential-request SSE events — the tool result with
+        // __credentialRequired was already streamed. The frontend detects it
+        // from the tool result and shows Connect/Ignore buttons.
+        channel.send({ type: 'done' });
+        channel.close();
+    })();
+}
 export async function streamAIAgent(agentName, input, channel, params, agentSessionMap, options) {
     const sessionMap = agentSessionMap ?? new Map();
     const normalizedInput = input;
@@ -419,6 +462,10 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
             await handleApprovals(loopResult.approvals, runId, channel, aiRunState, persistingChannel);
             return persistingChannel.fullText;
         }
+        if (loopResult.outcome === 'credential') {
+            await handleCredentialRequests(loopResult.credentialRequests, runId, channel, aiRunState, persistingChannel);
+            return persistingChannel.fullText;
+        }
         await postStreamCleanup(persistingChannel, aiMiddlewares, singletonServices, storage, memoryConfig, threadId, workingMemorySchemaName, runnerParams.messages, aiRunState, runId);
         channel.send({ type: 'done' });
         channel.close();
@@ -487,7 +534,8 @@ export async function resumeAIAgent(input, channel, params, options) {
                     toolResults: [
                         {
                             id: input.toolCallId,
-                            name: pending.type === 'tool-call'
+                            name: pending.type === 'tool-call' ||
+                                pending.type === 'credential-request'
                                 ? pending.toolName
                                 : pending.agentName,
                             result: denialResult,
@@ -573,7 +621,12 @@ export async function resumeAIAgent(input, channel, params, options) {
             toolResult = await matchingTool.execute(toolArgs);
         }
         catch (execErr) {
-            toolResult = `Error: ${execErr instanceof Error ? execErr.message : String(execErr)}`;
+            if (execErr?.payload?.error === 'missing_credential') {
+                toolResult = execErr.payload;
+            }
+            else {
+                toolResult = `Error: ${execErr instanceof Error ? execErr.message : String(execErr)}`;
+            }
             isError = true;
         }
         const resultStr = typeof toolResult === 'string' ? toolResult : JSON.stringify(toolResult);
@@ -708,6 +761,10 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
             await handleApprovals(loopResult.approvals, run.runId, channel, aiRunState, persistingChannel);
             return;
         }
+        if (loopResult.outcome === 'credential') {
+            await handleCredentialRequests(loopResult.credentialRequests, run.runId, channel, aiRunState, persistingChannel);
+            return;
+        }
         await postStreamCleanup(persistingChannel, aiMiddlewares, singletonServices, storage, memoryConfig, run.threadId, workingMemorySchemaName, runnerParams.messages, aiRunState, run.runId);
         channel.send({ type: 'done' });
         channel.close();

package/dist/wirings/ai-agent/ai-agent.types.d.ts

@@ -256,6 +256,17 @@ export type AIStreamEvent = {
     reason?: string;
     agent?: string;
     session?: string;
+} | {
+    type: 'credential-request';
+    toolCallId: string;
+    toolName: string;
+    args: unknown;
+    credentialName: string;
+    credentialType: 'oauth2' | 'apikey';
+    connectUrl?: string;
+    runId: string;
+    agent?: string;
+    session?: string;
 } | {
     type: 'usage';
     tokens: {
@@ -307,6 +318,14 @@ export type PendingApproval = {
     agentRunId: string;
     displayToolName: string;
     displayArgs: unknown;
+} | {
+    type: 'credential-request';
+    toolCallId: string;
+    toolName: string;
+    args: unknown;
+    credentialName: string;
+    credentialType: 'oauth2' | 'apikey';
+    connectUrl?: string;
 };
 export interface AgentRunState {
     runId: string;
@@ -315,7 +334,7 @@ export interface AgentRunState {
     resourceId: string;
     status: 'running' | 'suspended' | 'completed' | 'failed';
     errorMessage?: string;
-    suspendReason?: 'approval' | 'rpc-missing';
+    suspendReason?: 'approval' | 'credential' | 'rpc-missing';
     missingRpcs?: string[];
     pendingApprovals?: PendingApproval[];
     usage: {

package/dist/wirings/ai-agent/index.d.ts

@@ -1,6 +1,6 @@
 export { agent, agentStream, agentResume, agentApprove, } from './ai-agent-helpers.js';
 export { runAIAgent, resumeAIAgentSync } from './ai-agent-runner.js';
 export { streamAIAgent, resumeAIAgent } from './ai-agent-stream.js';
-export { type RunAIAgentParams, type StreamAIAgentOptions, ToolApprovalRequired, } from './ai-agent-prepare.js';
+export { type RunAIAgentParams, type StreamAIAgentOptions, ToolApprovalRequired, ToolCredentialRequired, } from './ai-agent-prepare.js';
 export { addAIAgent, approveAIAgent, getAIAgents, getAIAgentsMeta, } from './ai-agent-registry.js';
 export type { AIAgentInput, AIAgentInputAttachment, AIAgentMeta, AIAgentMemoryConfig, AIAgentStep, AIContentPart, AgentRunRow, AgentRunService, AgentRunState, AIMessage, AIStreamChannel, AIStreamEvent, AIThread, CoreAIAgent, PendingApproval, PikkuAIMiddlewareHooks, } from './ai-agent.types.js';

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

@@ -1,5 +1,5 @@
 export { agent, agentStream, agentResume, agentApprove, } from './ai-agent-helpers.js';
 export { runAIAgent, resumeAIAgentSync } from './ai-agent-runner.js';
 export { streamAIAgent, resumeAIAgent } from './ai-agent-stream.js';
-export { ToolApprovalRequired, } from './ai-agent-prepare.js';
+export { ToolApprovalRequired, ToolCredentialRequired, } from './ai-agent-prepare.js';
 export { addAIAgent, approveAIAgent, getAIAgents, getAIAgentsMeta, } from './ai-agent-registry.js';