@pikku/core 0.12.13 → 0.12.14

package/src/wirings/ai-agent/ai-agent-prepare.ts

@@ -70,6 +70,75 @@ export class ToolApprovalRequired extends PikkuError {
   }
 }
 
+export class ToolCredentialRequired extends PikkuError {
+  public readonly toolCallId: string
+  public readonly toolName: string
+  public readonly args: unknown
+  public readonly credentialName: string
+  public readonly credentialType: 'oauth2' | 'apikey'
+  public readonly connectUrl?: string
+
+  constructor(
+    toolCallId: string,
+    toolName: string,
+    args: unknown,
+    credentialName: string,
+    credentialType: 'oauth2' | 'apikey',
+    connectUrl?: string
+  ) {
+    super(`Tool '${toolName}' requires credential '${credentialName}'`)
+    this.toolCallId = toolCallId
+    this.toolName = toolName
+    this.args = args
+    this.credentialName = credentialName
+    this.credentialType = credentialType
+    this.connectUrl = connectUrl
+  }
+}
+
+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 function getAddonCredentialRequirements(
+  toolNames: string[]
+): AddonCredentialRequirement[] {
+  const requirements = new Map<string, AddonCredentialRequirement>()
+
+  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 as Record<string, any>
+    )) {
+      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 type StreamContext = {
   channel: AIStreamChannel
   options?: StreamAIAgentOptions
@@ -478,8 +547,9 @@ export async function buildToolDefs(
         let execError: unknown
         try {
           result = await originalExecute(args)
-        } catch (err) {
+        } catch (err: any) {
           execError = err
+          if (err?.payload?.error === 'missing_credential') throw err
           result = err instanceof Error ? err.message : String(err)
         }
         const durationMs = Date.now() - startTime

package/src/wirings/ai-agent/ai-agent-runner.ts

@@ -430,8 +430,12 @@ export async function resumeAIAgentSync(
           typeof toolResult === 'string'
             ? toolResult
             : JSON.stringify(toolResult)
-      } catch (err) {
-        resultStr = `Error: ${err instanceof Error ? err.message : String(err)}`
+      } catch (err: any) {
+        if (err?.payload?.error === 'missing_credential') {
+          resultStr = JSON.stringify(err.payload)
+        } else {
+          resultStr = `Error: ${err instanceof Error ? err.message : String(err)}`
+        }
       }
     } else {
       continue

package/src/wirings/ai-agent/ai-agent-stream.ts

@@ -36,6 +36,7 @@ import {
   buildToolDefs,
   createScopedChannel,
   ToolApprovalRequired,
+  ToolCredentialRequired,
   type RunAIAgentParams,
   type StreamAIAgentOptions,
   type StreamContext,
@@ -236,6 +237,7 @@ type StepLoopParams = {
 type StepLoopResult =
   | { outcome: 'done' }
   | { outcome: 'approval'; approvals: ToolApprovalRequired[] }
+  | { outcome: 'credential'; credentialRequests: ToolCredentialRequired[] }
 
 async function runStreamStepLoop(
   params: StepLoopParams
@@ -310,6 +312,13 @@ async function runStreamStepLoop(
       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)
   }
 
@@ -386,6 +395,40 @@ export function checkForApprovals(
   return approvals
 }
 
+export function checkForCredentialRequests(
+  stepResult: AIAgentStepResult,
+  runId: string
+): ToolCredentialRequired[] {
+  const requests: ToolCredentialRequired[] = []
+  for (const tr of stepResult.toolResults) {
+    if (
+      tr.result &&
+      typeof tr.result === 'object' &&
+      '__credentialRequired' in (tr.result as object)
+    ) {
+      const r = tr.result as {
+        credentialName: string
+        credentialType: 'oauth2' | 'apikey'
+        connectUrl?: string
+      }
+      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: AIAgentRunnerParams,
   stepResult: AIAgentStepResult
@@ -472,6 +515,40 @@ function handleApprovals(
   })()
 }
 
+function handleCredentialRequests(
+  requests: ToolCredentialRequired[],
+  runId: string,
+  channel: AIStreamChannel,
+  aiRunState: AIRunStateService,
+  persistingChannel: PersistingChannel
+): Promise<void> {
+  return (async () => {
+    await persistingChannel.flush()
+
+    const pendingApprovals = requests.map((req) => ({
+      type: 'credential-request' as const,
+      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: string,
   input: {
@@ -665,6 +742,17 @@ export async function streamAIAgent(
       return persistingChannel.fullText
     }
 
+    if (loopResult.outcome === 'credential') {
+      await handleCredentialRequests(
+        loopResult.credentialRequests,
+        runId,
+        channel,
+        aiRunState,
+        persistingChannel
+      )
+      return persistingChannel.fullText
+    }
+
     await postStreamCleanup(
       persistingChannel,
       aiMiddlewares,
@@ -769,7 +857,8 @@ export async function resumeAIAgent(
             {
               id: input.toolCallId,
               name:
-                pending.type === 'tool-call'
+                pending.type === 'tool-call' ||
+                pending.type === 'credential-request'
                   ? pending.toolName
                   : pending.agentName,
               result: denialResult,
@@ -896,8 +985,12 @@ export async function resumeAIAgent(
     let isError = false
     try {
       toolResult = await matchingTool.execute(toolArgs)
-    } catch (execErr) {
-      toolResult = `Error: ${execErr instanceof Error ? execErr.message : String(execErr)}`
+    } catch (execErr: any) {
+      if (execErr?.payload?.error === 'missing_credential') {
+        toolResult = execErr.payload
+      } else {
+        toolResult = `Error: ${execErr instanceof Error ? execErr.message : String(execErr)}`
+      }
       isError = true
     }
 
@@ -1111,6 +1204,17 @@ async function continueAfterToolResult(
       return
     }
 
+    if (loopResult.outcome === 'credential') {
+      await handleCredentialRequests(
+        loopResult.credentialRequests,
+        run.runId,
+        channel,
+        aiRunState,
+        persistingChannel
+      )
+      return
+    }
+
     await postStreamCleanup(
       persistingChannel,
       aiMiddlewares,

package/src/wirings/ai-agent/ai-agent.types.ts

@@ -263,6 +263,18 @@ export type AIStreamEvent =
       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: { input: number; output: number }
@@ -310,6 +322,15 @@ export type PendingApproval =
       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
@@ -318,7 +339,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: { inputTokens: number; outputTokens: number; model: string }

package/src/wirings/ai-agent/index.ts

@@ -10,6 +10,7 @@ export {
   type RunAIAgentParams,
   type StreamAIAgentOptions,
   ToolApprovalRequired,
+  ToolCredentialRequired,
 } from './ai-agent-prepare.js'
 export {
   addAIAgent,

package/src/wirings/channel/channel-handler.ts

@@ -13,7 +13,6 @@ import { pikkuState } from '../../pikku-state.js'
 import { runPikkuFunc } from '../../function/function-runner.js'
 import type { SessionService } from '../../services/user-session-service.js'
 import { createMiddlewareSessionWireProps } from '../../services/user-session-service.js'
-
 const getChannelMeta = (channelName: string) => {
   return pikkuState(null, 'channel', 'meta')[channelName]
 }

package/src/wirings/cli/cli-runner.ts

@@ -191,7 +191,7 @@ function registerCLICommands(
       }
     }
 
-    addFunction(funcName, unwrapFunc(command))
+    addFunction(funcName, unwrapFunc(command), currentMeta?.packageName)
 
     // Register renderer if provided
     if (typeof command === 'object' && command.render) {

package/src/wirings/http/http-runner.ts

@@ -33,10 +33,6 @@ import {
 } 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'
@@ -303,7 +299,6 @@ const executeRoute = async (
   }
 ) => {
   const userSession = new PikkuSessionService<CoreUserSession>()
-  const credentialWire = new PikkuCredentialWireService()
   const { params, route, meta } = matchedRoute
   const { singletonServices, createWireServices, skipUserSession, requestId } =
     services
@@ -382,7 +377,6 @@ const executeRoute = async (
     setSession: (s: any) => userSession.setInitial(s),
     getSession: () => userSession.get(),
     hasSessionChanged: () => userSession.sessionChanged,
-    ...createMiddlewareCredentialWireProps(credentialWire),
   }
 
   result = await runPikkuFunc(
@@ -402,7 +396,6 @@ const executeRoute = async (
       tags: route.tags,
       wire,
       sessionService: userSession,
-      credentialWireService: credentialWire,
       packageName: meta.packageName,
     }
   )

package/src/wirings/mcp/mcp-runner.ts

@@ -29,7 +29,6 @@ import {
   PikkuSessionService,
   createMiddlewareSessionWireProps,
 } from '../../services/user-session-service.js'
-
 export class MCPError extends Error {
   constructor(public readonly error: JsonRpcErrorResponse) {
     super(error?.message || 'MCP Error')

package/src/wirings/queue/queue-runner.ts

@@ -12,7 +12,6 @@ import {
   pikkuState,
 } from '../../pikku-state.js'
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
-
 /**
  * Error class for queue processor not found
  */
@@ -132,6 +131,7 @@ export async function runQueueJob({
   const queue: PikkuQueue = {
     queueName: job.queueName,
     jobId: job.id,
+    pikkuUserId: job.pikkuUserId,
     updateProgress:
       updateProgress ||
       (async (progress: number | string | object) => {

package/src/wirings/queue/queue.types.ts

@@ -96,6 +96,8 @@ export interface QueueJob<T = any, R = any> {
   result?: R
   waitForCompletion?: (ttl?: number) => Promise<R>
   metadata?: () => Promise<QueueJobMetadata> | QueueJobMetadata
+  /** Pikku user ID propagated from the job producer */
+  pikkuUserId?: string
 }
 
 /**
@@ -109,6 +111,8 @@ export interface JobOptions {
   removeOnComplete?: number
   removeOnFail?: number
   jobId?: string
+  /** Pikku user ID to propagate to the queue worker for credential resolution */
+  pikkuUserId?: string
 }
 
 /**
@@ -180,6 +184,8 @@ export interface PikkuQueue {
   queueName: string
   /** The current job ID */
   jobId: string
+  /** Pikku user ID propagated from the job producer for credential resolution */
+  pikkuUserId?: string
   /** Update job progress (0-100 or custom value) */
   updateProgress: (progress: number | string | object) => Promise<void>
   /** Fail the current job with optional reason */

package/src/wirings/rpc/rpc-runner.ts

@@ -239,6 +239,7 @@ export class ContextAwareRPCService {
       type: this.wire.wireType ?? 'unknown',
       id: this.wire.wireId,
       ...(parentRunId ? { parentRunId } : {}),
+      ...(this.wire.pikkuUserId ? { pikkuUserId: this.wire.pikkuUserId } : {}),
     }
     return this.services.workflowService.startWorkflow(
       workflowName,
@@ -306,9 +307,14 @@ export class ContextAwareRPCService {
         approvals: { toolCallId: string; approved: boolean }[],
         expectedAgentName?: string
       ) => {
-        const result = await resumeAIAgentSync(runId, approvals, {
-          sessionService: this.options.sessionService,
-        }, expectedAgentName)
+        const result = await resumeAIAgentSync(
+          runId,
+          approvals,
+          {
+            sessionService: this.options.sessionService,
+          },
+          expectedAgentName
+        )
         return {
           runId: result.runId,
           result: result.object ?? result.text,

package/src/wirings/workflow/dsl/workflow-dsl.types.ts

@@ -306,6 +306,8 @@ export interface PikkuWorkflowWire {
   name: string
   /** The current run ID */
   runId: string
+  /** Pikku user ID propagated from the originating request for credential resolution */
+  pikkuUserId?: string
   /** Get the current workflow run */
   getRun: () => Promise<WorkflowRun>
 

package/src/wirings/workflow/pikku-workflow-service.ts

@@ -600,8 +600,10 @@ export abstract class PikkuWorkflowService implements WorkflowService {
         runId,
         rpcService
       )
+      workflowWire.pikkuUserId = run.wire?.pikkuUserId
       const wire: PikkuWire = {
         workflow: workflowWire,
+        pikkuUserId: run.wire?.pikkuUserId,
         session: rpcService.wire?.session,
         rpc: rpcService.wire?.rpc,
       }

package/src/wirings/workflow/workflow.types.ts

@@ -41,6 +41,8 @@ export interface WorkflowRunWire {
   id?: string
   parentRunId?: string
   parentStepId?: string
+  /** Pikku user ID propagated from the originating request for credential resolution */
+  pikkuUserId?: string
 }
 
 export interface WorkflowServiceConfig {