@pikku/core 0.12.13 → 0.12.15

package/src/types/core.types.ts

@@ -34,6 +34,7 @@ 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'
+import type { MetaService } from '../services/meta-service.js'
 
 export type PikkuWiringTypes =
   | 'http'
@@ -108,6 +109,7 @@ export type FunctionRuntimeMeta = {
   remote?: boolean
   mcp?: boolean
   readonly?: boolean
+  deploy?: 'serverless' | 'server' | 'auto'
   sessionless?: boolean
   version?: number
   approvalRequired?: boolean
@@ -130,6 +132,8 @@ export type FunctionMeta = FunctionRuntimeMeta &
       middleware: MiddlewareMetadata[]
       permissions: PermissionMetadata[]
       isDirectFunction: boolean
+      sourceFile: string
+      exportedName: string
     } & CommonWireMeta
   >
 
@@ -230,6 +234,8 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
   workflowRunService?: WorkflowRunService
   /** Credential service for dynamic/managed credentials (OAuth tokens, per-user API keys) */
   credentialService?: CredentialService
+  /** Meta service for reading .pikku metadata files (filesystem on Node, R2/KV on CF) */
+  metaService?: MetaService
 }
 
 /**
@@ -248,6 +254,8 @@ export type PikkuWire<
 > = Partial<{
   wireType: PikkuWiringTypes
   wireId: string
+  /** Trace ID for distributed tracing — propagated across remote RPC calls via x-trace-id header */
+  traceId: string
   http: PikkuHTTP<In>
   mcp: PikkuMCP<MCPTools>
   rpc: TypedRPC
@@ -273,10 +281,16 @@ export type PikkuWire<
   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>>
 }>
 
 /**

package/src/types/state.types.ts

@@ -182,7 +182,12 @@ export interface PikkuPackageState {
     } | null
     /** Cached singleton services for this package */
     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
+    /** Services this addon needs from the parent project */
+    requiredParentServices: string[] | null
   }
 }

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

@@ -11,6 +11,7 @@ import type {
 } from './ai-agent.types.js'
 import type { AIAgentRunnerParams } from '../../services/ai-agent-runner-service.js'
 import { PikkuError } from '../../errors/error-handler.js'
+import { checkAuthPermissions } from '../../permissions.js'
 import { AIProviderNotConfiguredError } from '../../errors/errors.js'
 import { pikkuState, getSingletonServices } from '../../pikku-state.js'
 import { createMiddlewareSessionWireProps } from '../../services/user-session-service.js'
@@ -22,10 +23,6 @@ import {
   resolveNamespace,
   ContextAwareRPCService,
 } from '../../wirings/rpc/rpc-runner.js'
-import {
-  buildDynamicWorkflowInstructions,
-  buildWorkflowTools,
-} from './agent-dynamic-workflow.js'
 import {
   resolveMemoryServices,
   loadContextMessages,
@@ -70,6 +67,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
@@ -79,6 +145,13 @@ export type StreamContext = {
 export const resolveAgent = (
   agentName: string
 ): { agent: CoreAIAgent; packageName: string | null; resolvedName: string } => {
+  if (!agentName) {
+    console.error(
+      '[resolveAgent] agentName is undefined/null! Stack:',
+      new Error().stack
+    )
+    throw new Error('resolveAgent called with undefined agentName')
+  }
   const mainAgent = pikkuState(null, 'agent', 'agents').get(agentName)
   if (mainAgent) {
     return { agent: mainAgent, packageName: null, resolvedName: agentName }
@@ -112,10 +185,21 @@ export async function buildInstructions(
   packageName: string | null
 ): Promise<string> {
   const meta = pikkuState(packageName, 'agent', 'agentsMeta')[agentName]
-  const rawInstructions = meta?.instructions ?? ''
-  let instructions = Array.isArray(rawInstructions)
-    ? rawInstructions.join('\n')
-    : rawInstructions
+  const parts: string[] = []
+  if (meta?.role) parts.push(meta.role)
+  if (meta?.personality) parts.push(meta.personality)
+  if (meta?.goal) parts.push(meta.goal)
+  let instructions = parts.join('\n\n')
+
+  if (meta?.tools?.length) {
+    instructions +=
+      '\n\nTool usage rules:\n' +
+      '- Act immediately with the information given. Do NOT ask clarifying questions unless a required field is truly missing.\n' +
+      '- Only use fields defined in your tool schemas. Never mention or ask for fields that do not exist.\n' +
+      '- Never fill optional fields with placeholder or zero values. Omit them entirely unless the user provides a real value.\n' +
+      '- Never stuff unrelated information into the wrong field.\n' +
+      '- Keep responses concise.'
+  }
 
   if (meta?.agents?.length) {
     instructions +=
@@ -125,13 +209,6 @@ export async function buildInstructions(
       'When a request involves multiple actions for the same domain, combine them into a single sub-agent call rather than making separate calls.'
   }
 
-  if (meta?.dynamicWorkflows && meta.tools?.length) {
-    instructions += buildDynamicWorkflowInstructions(
-      meta.tools,
-      meta.dynamicWorkflows
-    )
-  }
-
   return instructions
 }
 
@@ -210,6 +287,11 @@ export async function buildToolDefs(
   const meta = pikkuState(packageName, 'agent', 'agentsMeta')[agentName]
   if (!meta) return { tools, missingRpcs }
 
+  // Get session for permission filtering
+  const session = params.sessionService
+    ? await params.sessionService.get()
+    : null
+
   const metaTools = meta.tools
   const metaAgents = meta.agents
 
@@ -246,6 +328,18 @@ export async function buildToolDefs(
         continue
       }
 
+      // Filter out tools the user doesn't have auth for
+      if (fnMeta.permissions?.length) {
+        if (!session) continue
+        const allowed = await checkAuthPermissions(
+          fnMeta.permissions,
+          session,
+          singletonServices,
+          resolvedPkg
+        )
+        if (!allowed) continue
+      }
+
       const inputSchemaName = fnMeta?.inputSchemaName
       let inputSchema = inputSchemaName
         ? schemas.get(inputSchemaName)
@@ -324,6 +418,17 @@ export async function buildToolDefs(
         continue
       }
 
+      // Filter out sub-agents the user doesn't have auth for
+      if (subMeta.permissions?.length) {
+        if (!session) continue
+        const allowed = await checkAuthPermissions(
+          subMeta.permissions,
+          session,
+          singletonServices
+        )
+        if (!allowed) continue
+      }
+
       tools.push({
         name: subAgentName,
         description: subMeta.description,
@@ -438,18 +543,6 @@ export async function buildToolDefs(
     }
   }
 
-  if (meta.dynamicWorkflows) {
-    const workflowTools = buildWorkflowTools(
-      agentName,
-      packageName,
-      meta.tools ?? [],
-      meta.dynamicWorkflows,
-      streamContext,
-      params.sessionService
-    )
-    tools.push(...workflowTools)
-  }
-
   const hasToolHooks = aiMiddlewares?.some(
     (mw) => mw.beforeToolCall || mw.afterToolCall
   )
@@ -478,8 +571,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
@@ -524,19 +618,6 @@ export async function prepareAgentRun(
     throw new AIProviderNotConfiguredError()
   }
 
-  if (agent.dynamicWorkflows && singletonServices.workflowService) {
-    const persisted =
-      await singletonServices.workflowService.getAIGeneratedWorkflows(
-        resolvedName
-      )
-    const allMeta = pikkuState(null, 'workflows', 'meta')
-    for (const wf of persisted) {
-      if (!allMeta[wf.workflowName]) {
-        allMeta[wf.workflowName] = wf.graph
-      }
-    }
-  }
-
   const { storage } = resolveMemoryServices(agent, singletonServices)
   const memoryConfig = agent.memory
   const threadId = input.threadId

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

@@ -1,7 +1,6 @@
 import type { CoreAIAgent, AgentRunState } from './ai-agent.types.js'
 import { pikkuState } from '../../pikku-state.js'
 import type { AIRunStateService } from '../../services/ai-run-state-service.js'
-import { PikkuMissingMetaError } from '../../errors/errors.js'
 
 export const addAIAgent = (
   agentName: string,
@@ -11,9 +10,10 @@ export const addAIAgent = (
   const agentsMeta = pikkuState(packageName, 'agent', 'agentsMeta')
   const agentMeta = agentsMeta[agentName]
   if (!agentMeta) {
-    throw new PikkuMissingMetaError(
-      `Missing generated metadata for AI agent '${agentName}'`
+    console.warn(
+      `[pikku] Skipping AI agent '${agentName}' — metadata not found. Consider moving this wiring to its own file.`
     )
+    return
   }
   const agents = pikkuState(packageName, 'agent', 'agents')
   if (agents.has(agentName)) {

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

@@ -32,6 +32,19 @@ 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'
+
+function stripNulls(obj: unknown): unknown {
+  if (obj === null) return undefined
+  if (Array.isArray(obj)) return obj.map(stripNulls)
+  if (typeof obj !== 'object') return obj
+  const result: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(obj as Record<string, unknown>)) {
+    if (value !== null) {
+      result[key] = stripNulls(value)
+    }
+  }
+  return result
+}
 import { randomUUID } from 'crypto'
 
 export async function runAIAgent(
@@ -420,18 +433,24 @@ export async function resumeAIAgentSync(
           `Tool "${pending.toolName}" not found in agent definition`
         )
       }
-      const toolArgs =
+      const rawArgs =
         typeof pending.args === 'string'
           ? JSON.parse(pending.args)
           : pending.args
+      // Strip null values recursively — LLMs send null for optional fields but Zod expects undefined
+      const toolArgs = stripNulls(rawArgs) ?? {}
       try {
         const toolResult = await matchingTool.execute(toolArgs)
         resultStr =
           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
     }
 
@@ -1073,6 +1166,14 @@ async function continueAfterToolResult(
   ).tools
 
   const resolved = resolveModelConfig(resolvedName, agent)
+  console.log(
+    '[DEBUG resume] resolvedName:',
+    resolvedName,
+    'agent.model:',
+    agent.model,
+    'resolved.model:',
+    resolved.model
+  )
   const maxSteps = resolved.maxSteps ?? 10
 
   const runnerParams: AIAgentRunnerParams = {
@@ -1111,6 +1212,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

@@ -195,7 +195,9 @@ export type CoreAIAgent<
   description: string
   summary?: string
   errors?: string[]
-  instructions: string | string[]
+  role?: string
+  personality?: string
+  goal: string
   model: string
   temperature?: number
   tools?: unknown[]
@@ -204,7 +206,6 @@ export type CoreAIAgent<
   memory?: AIAgentMemoryConfig
   maxSteps?: number
   toolChoice?: 'auto' | 'required' | 'none'
-  dynamicWorkflows?: 'read' | 'always' | 'ask'
   input?: unknown
   output?: unknown
   tags?: string[]
@@ -263,6 +264,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 +323,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 +340,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 }
@@ -377,6 +399,7 @@ export type AIAgentMeta = Record<
     channelMiddleware?: MiddlewareMetadata[]
     aiMiddleware?: MiddlewareMetadata[]
     permissions?: PermissionMetadata[]
-    dynamicWorkflows?: 'read' | 'always' | 'ask'
+    sourceFile?: string
+    exportedName?: 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/channel/channel-runner.ts

@@ -1,4 +1,4 @@
-import { NotFoundError, PikkuMissingMetaError } from '../../errors/errors.js'
+import { NotFoundError } from '../../errors/errors.js'
 import { addFunction } from '../../function/function-runner.js'
 import type { CorePikkuPermission } from '../../function/functions.types.js'
 import { pikkuState, getSingletonServices } from '../../pikku-state.js'
@@ -36,13 +36,12 @@ export const wireChannel = <
   const channelsMeta = pikkuState(null, 'channel', 'meta')
   const channelMeta = channelsMeta[channel.name]
   if (!channelMeta) {
-    throw new PikkuMissingMetaError(
-      `Missing generated metadata for channel '${channel.name}'`
+    console.warn(
+      `[pikku] Skipping channel '${channel.name}' — metadata not found. Consider moving this wiring to its own file.`
     )
+    return
   }
 
-  pikkuState(null, 'channel', 'channels').set(channel.name, channel as any)
-
   // Register onConnect function if provided
   if (channel.onConnect && channelMeta.connect) {
     addFunction(channelMeta.connect.pikkuFuncId, channel.onConnect as any)