@pikku/core 0.12.2 → 0.12.3

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

@@ -69,6 +69,8 @@ export interface AIAgentInput {
   threadId: string
   resourceId: string
   attachments?: AIAgentInputAttachment[]
+  model?: string
+  temperature?: number
 }
 
 export interface AIAgentOutput {
@@ -78,6 +80,14 @@ export interface AIAgentOutput {
   threadId: string
   steps: AIAgentStep[]
   usage: { inputTokens: number; outputTokens: number }
+  status?: 'completed' | 'suspended'
+  pendingApprovals?: Array<{
+    toolCallId: string
+    toolName: string
+    args: unknown
+    reason?: string
+    runId: string
+  }>
 }
 
 export interface AIAgentToolDef {
@@ -86,6 +96,7 @@ export interface AIAgentToolDef {
   inputSchema: Record<string, unknown>
   execute: (input: unknown) => Promise<unknown>
   needsApproval?: boolean
+  approvalDescriptionFn?: (input: unknown) => Promise<string>
 }
 
 export interface PikkuAIMiddlewareHooks<
@@ -189,13 +200,14 @@ export type CoreAIAgent<
   temperature?: number
   tools?: unknown[]
   agents?: unknown[]
+  agentMode?: 'delegate' | 'supervise'
   memory?: AIAgentMemoryConfig
   maxSteps?: number
   toolChoice?: 'auto' | 'required' | 'none'
+  dynamicWorkflows?: 'read' | 'always' | 'ask'
   input?: unknown
   output?: unknown
   tags?: string[]
-  protocol?: 'ui-message-stream'
   prepareStep?: (ctx: {
     stepNumber: number
     messages: AIMessage[]
@@ -267,6 +279,13 @@ export type AIStreamEvent =
       session?: string
     }
   | { type: 'audio-done'; agent?: string; session?: string }
+  | {
+      type: 'workflow-created'
+      workflowName: string
+      graph: any
+      agent?: string
+      session?: string
+    }
   | {
       type: 'suspended'
       reason: 'rpc-missing'
@@ -298,6 +317,7 @@ export interface AgentRunState {
   threadId: string
   resourceId: string
   status: 'running' | 'suspended' | 'completed' | 'failed'
+  errorMessage?: string
   suspendReason?: 'approval' | 'rpc-missing'
   missingRpcs?: string[]
   pendingApprovals?: PendingApproval[]
@@ -312,6 +332,7 @@ export interface AgentRunRow {
   threadId: string
   resourceId: string
   status: string
+  errorMessage?: string
   suspendReason?: string
   missingRpcs?: string[]
   usageInputTokens: number
@@ -356,5 +377,6 @@ export type AIAgentMeta = Record<
     channelMiddleware?: MiddlewareMetadata[]
     aiMiddleware?: MiddlewareMetadata[]
     permissions?: PermissionMetadata[]
+    dynamicWorkflows?: 'read' | 'always' | 'ask'
   }
 >

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

@@ -4,12 +4,8 @@ export {
   agentResume,
   agentApprove,
 } from './ai-agent-helpers.js'
-export { runAIAgent } from './ai-agent-runner.js'
+export { runAIAgent, resumeAIAgentSync } from './ai-agent-runner.js'
 export { streamAIAgent, resumeAIAgent } from './ai-agent-stream.js'
-export {
-  createAssistantUIChannel,
-  parseAssistantUIInput,
-} from './ai-agent-assistant-ui.js'
 export {
   type RunAIAgentParams,
   type StreamAIAgentOptions,

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

@@ -98,11 +98,18 @@ export const processMessageHandlers = (
       return
     }
 
+    const routeMeta = getRouteMeta(
+      channelConfig.name,
+      routingProperty,
+      routerValue
+    )
     const {
-      pikkuFuncId,
+      packageName,
       middleware: routeInheritedMiddleware,
       permissions: inheritedPermissions,
-    } = getRouteMeta(channelConfig.name, routingProperty, routerValue)
+    } = routeMeta
+
+    const pikkuFuncId = routeMeta.pikkuFuncId
 
     // Get wire middleware: channel-level middleware + message-specific middleware
     const channelWireMiddleware = channelConfig.middleware || []
@@ -146,12 +153,14 @@ export const processMessageHandlers = (
       wireChannelMiddleware: wireChannelMiddleware as any,
       inheritedPermissions,
       wirePermissions,
+      coerceDataFromSchema: true,
       tags: channelConfig.tags,
       sessionService: userSession,
       wire: {
         channel: channelHandler.getChannel(),
         ...(userSession && createMiddlewareSessionWireProps(userSession)),
       },
+      packageName,
     })
   }
 

package/src/wirings/channel/channel.types.ts

@@ -1,4 +1,3 @@
-import type { PikkuError } from '../../errors/error-handler.js'
 import type {
   HTTPFunctionMetaInputTypes,
   PikkuHTTPRequest,
@@ -47,6 +46,7 @@ export type RunChannelParams<ChannelData> = {
 
 export interface ChannelMessageMeta {
   pikkuFuncId: string
+  packageName?: string
   summary?: string
   description?: string
   errors?: string[]
@@ -141,12 +141,6 @@ export type CoreChannel<
     data: BinaryData,
     channel: PikkuChannel<ChannelData, any>
   ) => Promise<BinaryData | void> | BinaryData | void
-  docs?: Partial<{
-    description: string
-    response: string
-    errors: Array<typeof PikkuError>
-    tags: string[]
-  }>
   tags?: string[]
 }
 

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

@@ -8,7 +8,7 @@ export class PikkuLocalChannelHandler<
   private onMessageCallback?: (message: unknown) => void
   private onBinaryMessageCallback?: (data: BinaryData) => void
   private openCallBack?: () => void
-  private closeCallback?: () => void
+  private closeCallbacks: (() => void)[] = []
   private sendCallback?: (message: Out, isBinary?: boolean) => void
   private sendBinaryCallback?: (data: BinaryData) => void
 
@@ -44,7 +44,7 @@ export class PikkuLocalChannelHandler<
   }
 
   public registerOnClose(callback: () => void): void {
-    this.closeCallback = callback
+    this.closeCallbacks.push(callback)
   }
 
   public close() {
@@ -52,7 +52,9 @@ export class PikkuLocalChannelHandler<
       return
     }
     super.close()
-    this.closeCallback?.()
+    for (const cb of this.closeCallbacks) {
+      cb()
+    }
   }
 
   public registerOnSend(send: (message: Out) => void) {

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

@@ -119,9 +119,12 @@ export const runLocalChannel = async ({
             if (result !== undefined) {
               await channel.send(result)
             }
-          } catch (e) {
+          } catch (e: any) {
             singletonServices.logger.error(`Error handling onConnect: ${e}`)
-            channel.send({ error: e.message || 'Unknown error' })
+            channel.send({
+              error: e.message || 'Unknown error',
+              errorName: e.constructor?.name,
+            })
           }
         }
       })
@@ -138,9 +141,12 @@ export const runLocalChannel = async ({
               channel,
               channelMiddlewareMeta: meta.channelMiddleware,
             })
-          } catch (e) {
+          } catch (e: any) {
             singletonServices.logger.error(`Error handling onDisconnect: ${e}`)
-            channel.send({ error: e.message || 'Unknown error' })
+            channel.send({
+              error: e.message || 'Unknown error',
+              errorName: e.constructor?.name,
+            })
           }
         }
 
@@ -157,9 +163,13 @@ export const runLocalChannel = async ({
         try {
           const result = await onMessage(data)
           await channel.send(result)
-        } catch (e) {
-          singletonServices.logger.error(`Error handling message: ${e.message}`)
-          channel.send({ error: e.message || 'Unknown error' })
+        } catch (e: any) {
+          singletonServices.logger.error(e)
+          channel.send({
+            error: e.message || 'Unknown error',
+            errorName: e.constructor?.name,
+          })
+          setTimeout(() => channel.close(), 200)
         }
       })
       if (onBinaryMessage) {

package/src/wirings/channel/serverless/serverless-channel-runner.ts

@@ -276,7 +276,10 @@ export const runChannelMessage = async (
     singletonServices.logger.error(
       `Error processing message: ${e.message || e}`
     )
-    return { error: e.message || 'Unknown error' }
+    return {
+      error: e.message || 'Unknown error',
+      errorName: e.constructor?.name,
+    }
   } finally {
     if (wireServices) {
       await closeWireServices(singletonServices.logger, wireServices)

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

@@ -218,7 +218,9 @@ function pluckCLIData(
   const funcMeta = pikkuState(null, 'function', 'meta')[funcName]
   const schemaName = funcMeta?.inputSchemaName
   const schema = schemaName
-    ? pikkuState(null, 'misc', 'schemas').get(schemaName)
+    ? pikkuState(funcMeta?.packageName ?? null, 'misc', 'schemas').get(
+        schemaName
+      )
     : null
 
   if (schema && schema.properties) {
@@ -226,7 +228,13 @@ function pluckCLIData(
     const result: Record<string, any> = {}
     for (const key of Object.keys(schema.properties)) {
       if (key in mergedData) {
-        result[key] = mergedData[key]
+        let value = mergedData[key]
+        // CLI passes all values as strings — coerce to array when schema expects one
+        const propSchema = schema.properties[key]
+        if (propSchema?.type === 'array' && !Array.isArray(value)) {
+          value = typeof value === 'string' ? value.split(',') : [value]
+        }
+        result[key] = value
       } else if (availableOptions[key]?.default !== undefined) {
         // Apply default if not provided
         result[key] = availableOptions[key].default
@@ -354,9 +362,11 @@ export async function runCLICommand({
       wireMiddleware: allWireMiddleware,
       inheritedPermissions: currentCommand.permissions,
       wirePermissions: undefined,
+      coerceDataFromSchema: true,
       tags: programData?.tags,
       wire,
       sessionService: userSession,
+      packageName: currentCommand.packageName,
     })
 
     // Apply renderer one final time with the final output (if renderer exists)

package/src/wirings/cli/cli.types.ts

@@ -70,6 +70,7 @@ export interface CLIProgramState {
 export interface CLICommandMeta {
   parameters?: string
   pikkuFuncId: string
+  packageName?: string
   positionals: CLIPositional[]
   options: Record<string, CLIOption>
   renderName?: string

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

@@ -166,7 +166,6 @@ function registerRoute(
     contentType: route.contentType,
     timeout: route.timeout,
     headers: route.headers,
-    docs: route.docs,
     sse: route.sse,
   } as any)
 }

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

@@ -38,6 +38,7 @@ import { PikkuFetchHTTPResponse } from './pikku-fetch-http-response.js'
 import { PikkuFetchHTTPRequest } from './pikku-fetch-http-request.js'
 import type { PikkuChannel } from '../channel/channel.types.js'
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
+import { applyWebResponse } from './web-request.js'
 import { httpRouter } from './routers/http-router.js'
 import { validateSchema } from '../../schema.js'
 import { runMiddleware } from '../../middleware-runner.js'
@@ -396,10 +397,13 @@ const executeRoute = async (
       tags: route.tags,
       wire,
       sessionService: userSession,
+      packageName: meta.packageName,
     }
   )
   if (!matchedRoute.route.sse) {
-    if (result === undefined || result === null) {
+    if (result instanceof Response) {
+      await applyWebResponse(http!.response!, result)
+    } else if (result === undefined || result === null) {
       http?.response?.status(204)
     } else if (route.returnsJSON === false) {
       http?.response?.arrayBuffer(result)
@@ -484,6 +488,7 @@ export const fetchData = async <In, Out>(
     logWarningsForStatusCodes = [],
     coerceDataFromSchema = true,
     bubbleErrors = false,
+    exposeErrors = false,
     generateRequestId,
   }: RunHTTPWiringOptions = {}
 ): Promise<Out | void> => {
@@ -545,15 +550,35 @@ export const fetchData = async <In, Out>(
 
     return result
   } catch (e: any) {
-    handleHTTPError(
-      e,
-      http,
-      requestId,
-      singletonServices.logger,
-      logWarningsForStatusCodes,
-      respondWith404,
-      bubbleErrors
-    )
+    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)
+      try {
+        response.arrayBuffer(
+          JSON.stringify({
+            type: 'error',
+            errorText: e instanceof Error ? e.message : String(e),
+          })
+        )
+        response.arrayBuffer('[DONE]')
+      } catch (streamErr: any) {
+        singletonServices.logger.error(
+          `SSE error while sending error payload: ${streamErr instanceof Error ? streamErr.message : String(streamErr)}`
+        )
+      }
+      response.close?.()
+    } else {
+      handleHTTPError(
+        e,
+        http,
+        requestId,
+        singletonServices.logger,
+        logWarningsForStatusCodes,
+        respondWith404,
+        bubbleErrors,
+        exposeErrors
+      )
+    }
   } finally {
     // Clean up any session-specific services created during processing
     if (wireServices) {

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

@@ -1,6 +1,5 @@
 import type { SerializeOptions } from 'cookie'
 import type { StandardSchemaV1 } from '@standard-schema/spec'
-import type { PikkuError } from '../../errors/error-handler.js'
 import type {
   CorePikkuMiddleware,
   CommonWireMeta,
@@ -36,6 +35,7 @@ export type RunHTTPWiringOptions = Partial<{
   logWarningsForStatusCodes: number[]
   coerceDataFromSchema: boolean
   bubbleErrors: boolean
+  exposeErrors: boolean
   generateRequestId: () => string
 }>
 
@@ -59,16 +59,6 @@ export type HTTPHeadersSchema = StandardSchemaV1<
   Record<string, string | string[] | undefined>
 >
 
-/**
- * Documentation config for OpenAPI generation
- */
-export type HTTPRouteDocsConfig = {
-  description?: string
-  response?: string
-  errors?: Array<typeof PikkuError>
-  tags?: string[]
-}
-
 /**
  * Common HTTP route configuration shared between wireHTTP and wireHTTPRoutes
  */
@@ -77,7 +67,6 @@ export type HTTPRouteBaseConfig = {
   timeout?: number
   tags?: string[]
   headers?: HTTPHeadersSchema
-  docs?: HTTPRouteDocsConfig
 }
 
 /**
@@ -271,6 +260,7 @@ export interface PikkuHTTPRequest<In = unknown> {
   data(): Promise<In>
   json(): Promise<unknown>
   arrayBuffer(): Promise<ArrayBuffer>
+  headers(): Record<string, string>
   header(headerName: string): string | null
   cookie(name?: string): string | null
   params(): Partial<Record<string, string | string[]>>
@@ -293,6 +283,7 @@ export interface PikkuHTTPResponse<Out = unknown> {
       | ReadableStream
   ): this
   json(data: Out): this
+  send?(data: string | ArrayBuffer | Buffer): this
   redirect(location: string, status?: number): this
   close?: () => void
   setMode?: (mode: 'stream') => void

package/src/wirings/http/index.ts

@@ -11,12 +11,15 @@ export {
 } from './http-runner.js'
 
 export { wireHTTPRoutes, defineHTTPRoutes } from './http-routes.js'
+export { toWebRequest, applyWebResponse } from './web-request.js'
 
 export type {
   AssertHTTPWiringParams,
   CoreHTTPFunctionWiring,
   HTTPMethod,
   HTTPRouteBaseConfig,
+  HTTPRouteContract,
+  HTTPRouteMap,
   HTTPWiringsMeta,
   PikkuHTTPRequest,
   PikkuHTTPResponse,

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

@@ -43,6 +43,10 @@ export class PikkuFetchHTTPRequest<In = unknown>
     return this.request.arrayBuffer()
   }
 
+  public headers(): Record<string, string> {
+    return Object.fromEntries(this.request.headers.entries())
+  }
+
   /**
    * Retrieves the value of a specific header.
    * @param headerName - The name of the header to retrieve.

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

@@ -83,10 +83,10 @@ export class PikkuFetchHTTPResponse implements PikkuHTTPResponse {
     return this
   }
 
-  // public body(body: BodyInit): this {
-  //   this.#body = body
-  //   return this
-  // }
+  public send(data: any): this {
+    this.#body = data
+    return this
+  }
 
   public redirect(location: string, status: number = 302): this {
     if (