@pikku/core 0.12.14 → 0.12.16

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,
@@ -148,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 }
@@ -181,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 +=
@@ -194,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
 }
 
@@ -279,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
 
@@ -315,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)
@@ -393,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,
@@ -507,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
   )
@@ -594,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,10 +433,12 @@ 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 =

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

@@ -1166,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 = {

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[]
@@ -398,6 +399,7 @@ export type AIAgentMeta = Record<
     channelMiddleware?: MiddlewareMetadata[]
     aiMiddleware?: MiddlewareMetadata[]
     permissions?: PermissionMetadata[]
-    dynamicWorkflows?: 'read' | 'always' | 'ask'
+    sourceFile?: string
+    exportedName?: string
   }
 >

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)

package/src/wirings/channel/local/local-channel-runner.test.ts

@@ -70,7 +70,11 @@ export class PikkuMockRequest implements PikkuHTTPRequest {
 }
 
 export class PikkuMockResponse implements PikkuHTTPResponse {
-  public _status: number | undefined
+  public _status: number = 200
+
+  public get statusCode(): number {
+    return this._status
+  }
 
   status(code: number): this {
     this._status = code

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

@@ -369,15 +369,16 @@ describe('CLI Runner', () => {
       assert.strictEqual(programs['my-cli'].middleware[0], middleware)
     })
 
-    test('should throw error when CLI metadata not found', () => {
+    test('should skip when CLI metadata not found', () => {
       pikkuState(null, 'cli', 'meta', { programs: {}, renderers: {} })
 
-      assert.throws(() => {
-        wireCLI({
-          program: 'nonexistent',
-          commands: {},
-        })
-      }, /CLI metadata not found for program 'nonexistent'/)
+      wireCLI({
+        program: 'nonexistent',
+        commands: {},
+      })
+
+      const programs = pikkuState(null, 'cli', 'programs')
+      assert.strictEqual(programs['nonexistent'], undefined)
     })
   })
 

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

@@ -1,4 +1,4 @@
-import { NotFoundError, PikkuMissingMetaError } from '../../errors/errors.js'
+import { NotFoundError } from '../../errors/errors.js'
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
 import { pikkuState } from '../../pikku-state.js'
 import type {
@@ -66,9 +66,10 @@ export const wireCLI = <
   const cliMeta = pikkuState(null, 'cli', 'meta') || {}
 
   if (!cliMeta.programs?.[cli.program]) {
-    throw new PikkuMissingMetaError(
-      `CLI metadata not found for program '${cli.program}'`
+    console.warn(
+      `[pikku] Skipping CLI program '${cli.program}' — metadata not found. Consider moving this wiring to its own file.`
     )
+    return
   }
 
   // Get existing programs state and add this program
@@ -499,8 +500,9 @@ export async function executeCLI({
       ? await createConfig(new LocalVariablesService(), data)
       : ({} as any)
 
-    // Create services with config
+    // Create services with config and register in global state
     const singletonServices = await createSingletonServices(config)
+    pikkuState(null, 'package', 'singletonServices', singletonServices)
 
     // Execute the command
     await runCLICommand({

package/src/wirings/cli/command-parser.ts

@@ -6,6 +6,11 @@ import type {
   CLIOption,
 } from './cli.types.js'
 
+/** Convert kebab-case to camelCase: "from-plan" → "fromPlan" */
+function toCamelCase(str: string): string {
+  return str.replace(/-([a-z])/g, (_, c) => c.toUpperCase())
+}
+
 /**
  * Result of parsing CLI arguments
  */
@@ -117,11 +122,11 @@ export function parseCLIArguments(
     const arg = args[currentIndex]
 
     if (arg.startsWith('--')) {
-      // Long option
+      // Long option (--from-plan → fromPlan)
       const equalIndex = arg.indexOf('=')
       if (equalIndex > 0) {
         // --option=value format
-        const key = arg.slice(2, equalIndex)
+        const key = toCamelCase(arg.slice(2, equalIndex))
         const optionDef = availableOptions[key]
 
         // Unknown options are allowed for forward compatibility
@@ -129,7 +134,7 @@ export function parseCLIArguments(
         optionArgs[key] = parseOptionValue(value, optionDef)
       } else {
         // --option value format
-        const key = arg.slice(2)
+        const key = toCamelCase(arg.slice(2))
         const optionDef = availableOptions[key]
 
         // Unknown options are allowed for forward compatibility

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

@@ -21,7 +21,7 @@ import type {
   PikkuWire,
   PikkuWiringTypes,
 } from '../../types/core.types.js'
-import { NotFoundError, PikkuMissingMetaError } from '../../errors/errors.js'
+import { NotFoundError } from '../../errors/errors.js'
 import {
   closeWireServices,
   createWeakUID,
@@ -180,9 +180,14 @@ export const wireHTTP = <
   const httpMeta = pikkuState(null, 'http', 'meta')
   const routeMeta = httpMeta[httpWiring.method][httpWiring.route]
   if (!routeMeta) {
-    throw new PikkuMissingMetaError(
-      `Missing generated metadata for HTTP route '${httpWiring.method.toUpperCase()} ${httpWiring.route}'`
+    // In deploy units with filtered metadata, wiring files may include
+    // routes for functions not in this unit. This happens when multiple
+    // wirings share a file — split them into separate files for better
+    // tree-shaking.
+    console.warn(
+      `[pikku] Skipping HTTP route '${httpWiring.method.toUpperCase()} ${httpWiring.route}' — metadata not found. Consider moving this wiring to its own file.`
     )
+    return
   }
   if (httpWiring.func) {
     addFunction(routeMeta.pikkuFuncId, httpWiring.func)
@@ -371,6 +376,7 @@ const executeRoute = async (
   }
 
   const wire: PikkuWire = {
+    traceId: requestId,
     http,
     channel,
     session: userSession.get() as CoreUserSession | undefined,
@@ -489,6 +495,7 @@ export const fetchData = async <In, Out>(
     bubbleErrors = false,
     exposeErrors = false,
     generateRequestId,
+    traceId: externalTraceId,
   }: RunHTTPWiringOptions = {}
 ): Promise<Out | void> => {
   const singletonServices = getSingletonServices()
@@ -499,11 +506,20 @@ export const fetchData = async <In, Out>(
   // Combine the request and response into one wire object
   const pikkuRequest =
     request instanceof Request ? new PikkuFetchHTTPRequest(request) : request
-  let requestId: string | null = null
-  try {
-    requestId = pikkuRequest.header('x-request-id')
-  } catch {}
+
+  // Resolve traceId: external (e.g. CF-Ray) > x-request-id header > generated
+  let requestId: string | null = externalTraceId ?? null
+  if (!requestId) {
+    try {
+      requestId = pikkuRequest.header('x-request-id')
+    } catch {}
+  }
   requestId = requestId || generateRequestId?.() || createWeakUID()
+
+  // Scoped logger for HTTP runner internal logging (error handling, route matching)
+  // Functions/middleware receive singletonServices.logger directly for compatibility
+  const scopedLogger =
+    singletonServices.logger.scope?.(requestId) ?? singletonServices.logger
   const http = createHTTPWire(pikkuRequest, response)
   const apiType = http!.request!.method()
   const apiRoute = http!.request!.path()
@@ -526,7 +542,7 @@ export const fetchData = async <In, Out>(
         response.status(204).json(undefined as any)
         return
       }
-      singletonServices.logger.info({
+      scopedLogger.info({
         message: 'Route not found',
         apiRoute,
         apiType,
@@ -551,7 +567,7 @@ export const fetchData = async <In, Out>(
   } catch (e: any) {
     if (matchedRoute?.route.sse) {
       // For SSE routes, send error through the stream since the response is already in stream mode
-      singletonServices.logger.error(e instanceof Error ? e.message : e)
+      scopedLogger.error(e instanceof Error ? e.message : e)
       try {
         const errorResponse = getErrorResponse(e)
         response.arrayBuffer(
@@ -562,7 +578,7 @@ export const fetchData = async <In, Out>(
         )
         response.arrayBuffer(JSON.stringify({ type: 'done' }))
       } catch (streamErr: any) {
-        singletonServices.logger.error(
+        scopedLogger.error(
           `SSE error while sending error payload: ${streamErr instanceof Error ? streamErr.message : String(streamErr)}`
         )
       }
@@ -572,7 +588,7 @@ export const fetchData = async <In, Out>(
         e,
         http,
         requestId,
-        singletonServices.logger,
+        scopedLogger,
         logWarningsForStatusCodes,
         respondWith404,
         bubbleErrors,

package/src/wirings/http/http.types.ts

@@ -37,6 +37,8 @@ export type RunHTTPWiringOptions = Partial<{
   bubbleErrors: boolean
   exposeErrors: boolean
   generateRequestId: () => string
+  /** Pre-resolved trace ID (e.g. CF-Ray). Falls back to x-request-id header or generated ID. */
+  traceId: string
 }>
 
 /**
@@ -269,6 +271,7 @@ export interface PikkuHTTPRequest<In = unknown> {
 }
 
 export interface PikkuHTTPResponse<Out = unknown> {
+  readonly statusCode: number
   status(code: number): this
   cookie(name: string, value: string | null, options: SerializeOptions): this
   header(name: string, value: string | string[]): this

package/src/wirings/http/pikku-fetch-http-response.ts

@@ -19,6 +19,10 @@ export class PikkuFetchHTTPResponse implements PikkuHTTPResponse {
     }
   }
 
+  public get statusCode(): number {
+    return this.#statusCode
+  }
+
   public status(code: number): this {
     this.#statusCode = code
     return this

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

@@ -20,11 +20,7 @@ import {
 } from '../../pikku-state.js'
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
 import { resolveNamespace } from '../rpc/rpc-runner.js'
-import {
-  BadRequestError,
-  NotFoundError,
-  PikkuMissingMetaError,
-} from '../../errors/errors.js'
+import { BadRequestError, NotFoundError } from '../../errors/errors.js'
 import {
   PikkuSessionService,
   createMiddlewareSessionWireProps,
@@ -57,9 +53,10 @@ export const wireMCPResource = <
   const resourcesMeta = pikkuState(null, 'mcp', 'resourcesMeta')
   const mcpResourceMeta = resourcesMeta[mcpResource.uri]
   if (!mcpResourceMeta) {
-    throw new PikkuMissingMetaError(
-      `Missing generated metadata for MCP resource '${mcpResource.uri}'`
+    console.warn(
+      `[pikku] Skipping MCP resource '${mcpResource.uri}' — metadata not found. Consider moving this wiring to its own file.`
     )
+    return
   }
   addFunction(mcpResourceMeta.pikkuFuncId, mcpResource.func as any)
   const resources = pikkuState(null, 'mcp', 'resources')
@@ -79,9 +76,10 @@ export const wireMCPPrompt = <
   const promptsMeta = pikkuState(null, 'mcp', 'promptsMeta')
   const mcpPromptMeta = promptsMeta[mcpPrompt.name]
   if (!mcpPromptMeta) {
-    throw new PikkuMissingMetaError(
-      `Missing generated metadata for MCP prompt '${mcpPrompt.name}'`
+    console.warn(
+      `[pikku] Skipping MCP prompt '${mcpPrompt.name}' — metadata not found. Consider moving this wiring to its own file.`
     )
+    return
   }
   addFunction(mcpPromptMeta.pikkuFuncId, mcpPrompt.func as any)
   const prompts = pikkuState(null, 'mcp', 'prompts')

package/src/wirings/mcp/mcp.types.ts

@@ -127,7 +127,7 @@ export type CoreMCPTool<
 > = {
   name: string
   title?: string
-  description: string
+  description?: string
   summary?: string
   errors?: string[]
   func: PikkuFunctionConfig

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

@@ -72,7 +72,7 @@ describe('wireQueueWorker', () => {
     assert.equal(registrations.get('test-queue'), mockWorker)
   })
 
-  test('should throw error when processor metadata not found', () => {
+  test('should skip when queue worker metadata not found', () => {
     const mockWorker: CoreQueueWorker = {
       name: 'missing-meta-queue',
       func: {
@@ -81,16 +81,10 @@ describe('wireQueueWorker', () => {
       },
     }
 
-    assert.throws(
-      () => wireQueueWorker(mockWorker),
-      (error: any) => {
-        assert(
-          error.message.includes('Missing generated metadata for queue worker')
-        )
-        assert(error.message.includes('missing-meta-queue'))
-        return true
-      }
-    )
+    wireQueueWorker(mockWorker)
+
+    const registrations = pikkuState(null, 'queue', 'registrations')
+    assert.equal(registrations.has('missing-meta-queue'), false)
   })
 
   test('should wire worker with middleware and tags', () => {

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

@@ -58,9 +58,10 @@ export const wireQueueWorker = <
   const meta = pikkuState(null, 'queue', 'meta')
   const processorMeta = meta[queueWorker.name]
   if (!processorMeta) {
-    throw new PikkuMissingMetaError(
-      `Missing generated metadata for queue worker '${queueWorker.name}'`
+    console.warn(
+      `[pikku] Skipping queue worker '${queueWorker.name}' — metadata not found. Consider moving this wiring to its own file.`
     )
+    return
   }
 
   // Register the function with pikku
@@ -104,13 +105,19 @@ export async function removeQueueWorker(name: string): Promise<void> {
 export async function runQueueJob({
   job,
   updateProgress,
+  traceId,
 }: {
   job: QueueJob
   updateProgress?: (progress: number | string | object) => Promise<void>
+  /** Pre-resolved trace ID (e.g. from queue message metadata) */
+  traceId?: string
 }): Promise<void> {
   const singletonServices = getSingletonServices()
   const createWireServices = getCreateWireServices()
-  const logger = singletonServices.logger
+  const resolvedTraceId = traceId ?? `q-${job.id}`
+  const logger =
+    singletonServices.logger.scope?.(resolvedTraceId) ??
+    singletonServices.logger
 
   const meta = pikkuState(null, 'queue', 'meta')
   const processorMeta = meta[job.queueName]
@@ -150,6 +157,7 @@ export async function runQueueJob({
     logger.info(`Processing job ${job.id} in queue ${job.queueName}`)
 
     const wire: PikkuWire = {
+      traceId: resolvedTraceId,
       queue,
     }