@pikku/core 0.12.0 → 0.12.1

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

@@ -1,8 +1,8 @@
-import {
+import type {
   CorePermissionGroup,
   CorePikkuPermission,
 } from '../../function/functions.types.js'
-import {
+import type {
   CorePikkuMiddleware,
   MiddlewareMetadata,
   PermissionMetadata,
@@ -65,6 +65,7 @@ export interface AIAgentToolDef {
   description: string
   inputSchema: Record<string, unknown>
   execute: (input: unknown) => Promise<unknown>
+  needsApproval?: boolean
 }
 
 export interface PikkuAIMiddlewareHooks<
@@ -97,6 +98,50 @@ export interface PikkuAIMiddlewareHooks<
   ) =>
     | Promise<{ text: string; messages: AIMessage[] }>
     | { text: string; messages: AIMessage[] }
+
+  beforeToolCall?: (
+    services: Services,
+    ctx: {
+      toolName: string
+      toolCallId: string
+      args: Record<string, unknown>
+    }
+  ) =>
+    | Promise<{ args: Record<string, unknown> } | void>
+    | { args: Record<string, unknown> }
+    | void
+
+  afterToolCall?: (
+    services: Services,
+    ctx: {
+      toolName: string
+      toolCallId: string
+      args: Record<string, unknown>
+      result: unknown
+      durationMs: number
+    }
+  ) => Promise<{ result: unknown } | void> | { result: unknown } | void
+
+  afterStep?: (
+    services: Services,
+    ctx: {
+      stepNumber: number
+      text: string
+      toolCalls: { toolCallId: string; toolName: string; args: unknown }[]
+      toolResults: { toolCallId: string; toolName: string; result: unknown }[]
+      usage: { inputTokens: number; outputTokens: number }
+      finishReason: string
+    }
+  ) => Promise<void> | void
+
+  onError?: (
+    services: Services,
+    ctx: {
+      error: Error
+      stepNumber: number
+      messages: AIMessage[]
+    }
+  ) => Promise<void> | void
 }
 
 export type AIAgentMemoryConfig = {
@@ -126,6 +171,15 @@ export type CoreAIAgent<
   input?: unknown
   output?: unknown
   tags?: string[]
+  protocol?: 'ui-message-stream'
+  prepareStep?: (ctx: {
+    stepNumber: number
+    messages: AIMessage[]
+    tools: AIAgentToolDef[]
+    toolChoice: 'auto' | 'required' | 'none'
+    model: string
+    stop: () => void
+  }) => void | Promise<void>
   middleware?: PikkuMiddleware[]
   channelMiddleware?: CorePikkuChannelMiddleware<any, any>[]
   aiMiddleware?: PikkuAIMiddlewareHooks<any, any>[]
@@ -133,6 +187,7 @@ export type CoreAIAgent<
 }
 
 export type AIStreamEvent =
+  | { type: 'step-start'; stepNumber: number; agent?: string; session?: string }
   | { type: 'text-delta'; text: string; agent?: string; session?: string }
   | { type: 'reasoning-delta'; text: string; agent?: string; session?: string }
   | {

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

@@ -1,5 +1,15 @@
+export {
+  agent,
+  agentStream,
+  agentResume,
+  agentApprove,
+} from './ai-agent-helpers.js'
 export { runAIAgent } 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,
@@ -12,6 +22,7 @@ export {
   getAIAgentsMeta,
 } from './ai-agent-registry.js'
 export type {
+  AIAgentInput,
   AIAgentMeta,
   AIAgentMemoryConfig,
   AIAgentStep,

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

@@ -1,10 +1,10 @@
-import {
+import type {
   CoreSingletonServices,
   CorePikkuMiddleware,
   PikkuWire,
   MiddlewareMetadata,
 } from '../../types/core.types.js'
-import { CoreChannel, ChannelMessageMeta } from './channel.types.js'
+import type { CoreChannel, ChannelMessageMeta } from './channel.types.js'
 import { combineMiddleware, runMiddleware } from '../../middleware-runner.js'
 import { runPikkuFuncDirectly } from '../../function/function-runner.js'
 import {

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

@@ -1,19 +1,17 @@
-import {
+import type {
   CoreServices,
   JSONValue,
   CoreUserSession,
 } from '../../types/core.types.js'
-import {
+import type {
   ChannelMessageMeta,
   CoreChannel,
   PikkuChannelHandler,
 } from './channel.types.js'
 import { pikkuState } from '../../pikku-state.js'
 import { runPikkuFunc } from '../../function/function-runner.js'
-import {
-  SessionService,
-  createMiddlewareSessionWireProps,
-} from '../../services/user-session-service.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]
@@ -81,7 +79,13 @@ export const processMessageHandlers = (
     routingProperty?: string,
     routerValue?: string
   ): Promise<unknown> => {
-    if (!validateAuth(requiresSession, channelHandler, onMessage)) {
+    if (
+      !validateAuth(
+        requiresSession,
+        userSession?.get() as CoreUserSession | undefined,
+        onMessage
+      )
+    ) {
       const routeMessage = routingProperty
         ? `route '${routingProperty}:${routerValue}'`
         : 'the default message route'
@@ -159,7 +163,7 @@ export const processMessageHandlers = (
       let messageData: any
       try {
         messageData = JSON.parse(rawData)
-      } catch (error) {
+      } catch {
         // Most likely a json error.. ignore
       }
 
@@ -201,7 +205,7 @@ export const processMessageHandlers = (
       logger.error(
         `No handler found for message in channel ${channelConfig.name} for ${JSON.stringify(rawData)}`
       )
-      logger.error(`Channel ${JSON.stringify(channelConfig)}`)
+      logger.error(`Channel config name: ${channelConfig.name}`)
     }
 
     return result

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

@@ -1,12 +1,12 @@
 import { NotFoundError, PikkuMissingMetaError } from '../../errors/errors.js'
 import { addFunction } from '../../function/function-runner.js'
-import { CorePikkuPermission } from '../../function/functions.types.js'
-import { pikkuState } from '../../pikku-state.js'
+import type { CorePikkuPermission } from '../../function/functions.types.js'
+import { pikkuState, getSingletonServices } from '../../pikku-state.js'
 import { coerceTopLevelDataFromSchema, validateSchema } from '../../schema.js'
-import { SessionService } from '../../services/user-session-service.js'
-import { CorePikkuMiddleware } from '../../types/core.types.js'
+import type { SessionService } from '../../services/user-session-service.js'
+import type { CorePikkuMiddleware } from '../../types/core.types.js'
 import { httpRouter } from '../http/routers/http-router.js'
-import {
+import type {
   ChannelMeta,
   CoreChannel,
   RunChannelOptions,
@@ -122,7 +122,6 @@ const getMatchingChannelConfig = (path: string) => {
 
 export const openChannel = async ({
   route,
-  singletonServices,
   coerceDataFromSchema = true,
   request,
 }: Pick<CoreChannel<unknown, string>, 'route'> &
@@ -133,6 +132,7 @@ export const openChannel = async ({
   channelConfig: CoreChannel<unknown, any>
   meta: ChannelMeta
 }> => {
+  const singletonServices = getSingletonServices()
   const matchingChannel = getMatchingChannelConfig(route)
   if (!matchingChannel) {
     singletonServices.logger.info(`Channel not found: ${route}`)

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

@@ -1,4 +1,4 @@
-import { CoreUserSession } from '../../types/core.types.js'
+import type { CoreUserSession } from '../../types/core.types.js'
 
 export type Channel<ChannelType = unknown, OpeningData = unknown> = {
   channelId: string

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

@@ -1,12 +1,10 @@
-import { PikkuError } from '../../errors/error-handler.js'
-import {
+import type { PikkuError } from '../../errors/error-handler.js'
+import type {
   HTTPFunctionMetaInputTypes,
   PikkuHTTPRequest,
   PikkuHTTPResponse,
 } from '../http/http.types.js'
-import {
-  CoreSingletonServices,
-  CreateWireServices,
+import type {
   CorePikkuMiddleware,
   MiddlewareMetadata,
   PermissionMetadata,
@@ -23,7 +21,7 @@ export type CorePikkuChannelMiddlewareFactory<
   Services = any,
   Event = unknown,
 > = (input: In) => CorePikkuChannelMiddleware<Services, Event>
-import {
+import type {
   CorePermissionGroup,
   CorePikkuFunction,
   CorePikkuFunctionConfig,
@@ -41,10 +39,8 @@ export type RunChannelOptions = Partial<{
 
 export type RunChannelParams<ChannelData> = {
   channelId: string
-  singletonServices: CoreSingletonServices
   request?: PikkuHTTPRequest<ChannelData>
   response?: PikkuHTTPResponse
-  createWireServices?: CreateWireServices
 }
 
 export interface ChannelMessageMeta {

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

@@ -3,13 +3,13 @@ import * as assert from 'node:assert/strict'
 import { runLocalChannel } from './local-channel-runner.js'
 import { pikkuState, resetPikkuState } from '../../../pikku-state.js'
 import { wireChannel } from '../channel-runner.js'
-import {
+import type {
   HTTPMethod,
   PikkuHTTPRequest,
   PikkuHTTPResponse,
   PikkuQuery,
 } from '../../http/http.types.js'
-import { SerializeOptions } from 'cookie'
+import type { SerializeOptions } from 'cookie'
 import { httpRouter } from '../../http/routers/http-router.js'
 
 /**
@@ -102,6 +102,10 @@ const mockCreateWireServices = async () => ({
 beforeEach(() => {
   resetPikkuState()
   httpRouter.reset()
+  pikkuState(null, 'package', 'singletonServices', mockSingletonServices as any)
+  pikkuState(null, 'package', 'factories', {
+    createWireServices: mockCreateWireServices,
+  } as any)
 })
 
 afterEach(() => {
@@ -113,11 +117,9 @@ test('runChannel should return undefined and 404 if no matching channel is found
   const mockResponse = new PikkuMockResponse()
 
   const result = await runLocalChannel({
-    singletonServices: mockSingletonServices,
     channelId: 'test-channel-id',
     request: new PikkuMockRequest('/non-existent-channel', 'get'),
     response: mockResponse,
-    createWireServices: mockCreateWireServices,
   })
 
   assert.equal(
@@ -131,6 +133,10 @@ test('runChannel should return undefined and 404 if no matching channel is found
 
 test('runChannel should return a channel handler if channel matches and no auth required', async () => {
   resetPikkuState()
+  pikkuState(null, 'package', 'singletonServices', mockSingletonServices as any)
+  pikkuState(null, 'package', 'factories', {
+    createWireServices: mockCreateWireServices,
+  } as any)
 
   pikkuState(null, 'channel', 'meta', {
     test: {
@@ -148,12 +154,10 @@ test('runChannel should return a channel handler if channel matches and no auth
   httpRouter.initialize()
 
   const result = await runLocalChannel({
-    singletonServices: mockSingletonServices,
     channelId: 'test-channel-id',
     request: new PikkuMockRequest('/test-channel', 'get'),
     response: new PikkuMockResponse(),
     route: '/test-channel',
-    createWireServices: mockCreateWireServices,
   })
 
   assert.ok(result, 'Should return a PikkuChannelHandler instance')
@@ -164,6 +168,7 @@ test('runChannel should return a channel handler if channel matches and no auth
 
 test('runChannel should close wire services once when channel closes', async () => {
   resetPikkuState()
+  pikkuState(null, 'package', 'singletonServices', mockSingletonServices as any)
   let closeCount = 0
 
   pikkuState(null, 'channel', 'meta', {
@@ -180,12 +185,7 @@ test('runChannel should close wire services once when channel closes', async ()
 
   httpRouter.initialize()
 
-  const result = await runLocalChannel({
-    singletonServices: mockSingletonServices,
-    channelId: 'test-channel-id',
-    request: new PikkuMockRequest('/test-channel', 'get'),
-    response: new PikkuMockResponse(),
-    route: '/test-channel',
+  pikkuState(null, 'package', 'factories', {
     createWireServices: async () => ({
       tracked: {
         close: async () => {
@@ -193,6 +193,13 @@ test('runChannel should close wire services once when channel closes', async ()
         },
       },
     }),
+  } as any)
+
+  const result = await runLocalChannel({
+    channelId: 'test-channel-id',
+    request: new PikkuMockRequest('/test-channel', 'get'),
+    response: new PikkuMockResponse(),
+    route: '/test-channel',
   })
 
   assert.ok(result)

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

@@ -2,36 +2,43 @@ import { openChannel } from '../channel-runner.js'
 import { createHTTPWire } from '../../http/http-runner.js'
 import { closeWireServices } from '../../../utils.js'
 import { processMessageHandlers } from '../channel-handler.js'
-import {
-  CoreChannel,
-  RunChannelOptions,
-  RunChannelParams,
-} from '../channel.types.js'
+import type { CoreChannel, RunChannelOptions } from '../channel.types.js'
 import { PikkuLocalChannelHandler } from './local-channel-handler.js'
-import { PikkuWire, WireServices } from '../../../types/core.types.js'
+import type { PikkuWire, WireServices } from '../../../types/core.types.js'
 import { handleHTTPError } from '../../../handle-error.js'
 import {
   PikkuSessionService,
   createMiddlewareSessionWireProps,
 } from '../../../services/user-session-service.js'
-import { PikkuHTTP } from '../../http/http.types.js'
+import type {
+  PikkuHTTP,
+  PikkuHTTPRequest,
+  PikkuHTTPResponse,
+} from '../../http/http.types.js'
 import { runChannelLifecycleWithMiddleware } from '../channel-common.js'
+import {
+  getSingletonServices,
+  getCreateWireServices,
+} from '../../../pikku-state.js'
 
 export const runLocalChannel = async ({
-  singletonServices,
   channelId,
   request,
   response,
   route,
-  createWireServices,
   skipUserSession = false,
   respondWith404 = true,
   coerceDataFromSchema = true,
   logWarningsForStatusCodes = [],
   bubbleErrors = false,
 }: Partial<Pick<CoreChannel<unknown, any>, 'route'>> &
-  RunChannelOptions &
-  RunChannelParams<unknown>): Promise<PikkuLocalChannelHandler | void> => {
+  RunChannelOptions & {
+    channelId: string
+    request?: PikkuHTTPRequest
+    response?: PikkuHTTPResponse
+  }): Promise<PikkuLocalChannelHandler | void> => {
+  const singletonServices = getSingletonServices()
+  const createWireServices = getCreateWireServices()
   let wireServices: WireServices<typeof singletonServices> | undefined
   let closedWireServices = false
 
@@ -48,12 +55,10 @@ export const runLocalChannel = async ({
   try {
     ;({ openingData, channelConfig, meta } = await openChannel({
       channelId,
-      createWireServices,
       respondWith404,
       request,
       response,
       route,
-      singletonServices,
       skipUserSession,
       coerceDataFromSchema,
       userSession,

package/src/wirings/channel/local/local-eventhub-service.test.ts

@@ -1,7 +1,7 @@
 import * as assert from 'assert'
 import { test } from 'node:test'
-import { PikkuChannelHandler } from '../channel.types.js'
-import { CoreUserSession } from '../../../types/core.types.js'
+import type { PikkuChannelHandler } from '../channel.types.js'
+import type { CoreUserSession } from '../../../types/core.types.js'
 import { LocalEventHubService } from './local-eventhub-service.js'
 
 class MockChannelHandler implements PikkuChannelHandler {

package/src/wirings/channel/local/local-eventhub-service.ts

@@ -1,5 +1,5 @@
-import { PikkuChannelHandler } from '../channel.types.js'
-import { EventHubService } from '../eventhub-service.js'
+import type { PikkuChannelHandler } from '../channel.types.js'
+import type { EventHubService } from '../eventhub-service.js'
 
 /**
  * Implementation of the SubscriptionService interface.

package/src/wirings/channel/log-channels.ts

@@ -1,5 +1,5 @@
 import { pikkuState } from '../../pikku-state.js'
-import { Logger } from '../../services/index.js'
+import type { Logger } from '../../services/index.js'
 
 /**
  * Logs all the loaded channels.

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

@@ -1,4 +1,4 @@
-import { PikkuChannel, PikkuChannelHandler } from './channel.types.js'
+import type { PikkuChannel, PikkuChannelHandler } from './channel.types.js'
 
 export abstract class PikkuAbstractChannelHandler<
   OpeningData = unknown,

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

@@ -1,4 +1,4 @@
-import { PikkuWire, WireServices } from '../../../types/core.types.js'
+import type { PikkuWire, WireServices } from '../../../types/core.types.js'
 import { closeWireServices } from '../../../utils.js'
 import { processMessageHandlers } from '../channel-handler.js'
 import { openChannel } from '../channel-runner.js'
@@ -9,15 +9,19 @@ import type {
   PikkuChannelHandlerFactory,
 } from '../channel.types.js'
 import { createHTTPWire } from '../../http/http-runner.js'
-import { ChannelStore } from '../channel-store.js'
+import type { ChannelStore } from '../channel-store.js'
 import { handleHTTPError } from '../../../handle-error.js'
 import {
   PikkuSessionService,
   createMiddlewareSessionWireProps,
 } from '../../../services/user-session-service.js'
-import { pikkuState } from '../../../pikku-state.js'
+import {
+  getSingletonServices,
+  getCreateWireServices,
+  pikkuState,
+} from '../../../pikku-state.js'
 import { PikkuFetchHTTPRequest } from '../../http/pikku-fetch-http-request.js'
-import { PikkuHTTP } from '../../http/http.types.js'
+import type { PikkuHTTP } from '../../http/http.types.js'
 import { runChannelLifecycleWithMiddleware } from '../channel-common.js'
 
 export interface RunServerlessChannelParams<ChannelData>
@@ -62,13 +66,11 @@ const getVariablesForChannel = ({
 }
 
 export const runChannelConnect = async ({
-  singletonServices,
   channelId,
   channelObject,
   request,
   response,
   route,
-  createWireServices,
   channelStore,
   channelHandlerFactory,
   coerceDataFromSchema = true,
@@ -78,6 +80,8 @@ export const runChannelConnect = async ({
 }: Pick<CoreChannel<unknown, any>, 'route'> &
   RunChannelOptions &
   RunServerlessChannelParams<unknown>) => {
+  const singletonServices = getSingletonServices()
+  const createWireServices = getCreateWireServices()
   let wireServices: WireServices | undefined
 
   let http: PikkuHTTP | undefined
@@ -89,10 +93,8 @@ export const runChannelConnect = async ({
 
   const { channelConfig, openingData, meta } = await openChannel({
     channelId,
-    createWireServices,
     request,
     route,
-    singletonServices,
     coerceDataFromSchema,
     userSession,
   })
@@ -155,9 +157,12 @@ export const runChannelConnect = async ({
 }
 
 export const runChannelDisconnect = async ({
-  singletonServices,
-  ...params
+  channelId,
+  channelStore,
+  channelHandlerFactory,
 }: RunServerlessChannelParams<unknown>): Promise<void> => {
+  const singletonServices = getSingletonServices()
+  const createWireServices = getCreateWireServices()
   let wireServices: WireServices | undefined
 
   // Try to get channel from store. In serverless environments (especially with
@@ -166,35 +171,31 @@ export const runChannelDisconnect = async ({
   // there's nothing to disconnect, so we can return early.
   let channelData
   try {
-    channelData = await params.channelStore.getChannelAndSession(
-      params.channelId
-    )
-  } catch (error) {
+    channelData = await channelStore.getChannelAndSession(channelId)
+  } catch {
     singletonServices.logger.info(
-      `Channel ${params.channelId} not found during disconnect - already cleaned up`
+      `Channel ${channelId} not found during disconnect - already cleaned up`
     )
     return
   }
 
   const { openingData, channelName, session } = channelData
   const { channel, channelConfig, meta } = getVariablesForChannel({
-    ...params,
+    channelId,
+    channelHandlerFactory,
     openingData,
     channelName,
   })
 
-  const userSession = new PikkuSessionService(
-    params.channelStore,
-    params.channelId
-  )
+  const userSession = new PikkuSessionService(channelStore, channelId)
   userSession.setInitial(session)
   const wire: PikkuWire = {
     channel,
     ...createMiddlewareSessionWireProps(userSession),
   }
 
-  if (!wireServices && params.createWireServices) {
-    wireServices = await params.createWireServices(singletonServices, wire)
+  if (createWireServices) {
+    wireServices = await createWireServices(singletonServices, wire)
   }
 
   const services = {
@@ -219,38 +220,42 @@ export const runChannelDisconnect = async ({
       )
     }
   }
-  await params.channelStore.removeChannels([channel.channelId])
+  await channelStore.removeChannels([channel.channelId])
   if (wireServices) {
     await closeWireServices(singletonServices.logger, wireServices)
   }
 }
 
 export const runChannelMessage = async (
-  { singletonServices, ...params }: RunServerlessChannelParams<unknown>,
+  {
+    channelId,
+    channelStore,
+    channelHandlerFactory,
+  }: RunServerlessChannelParams<unknown>,
   data: unknown
 ): Promise<unknown> => {
+  const singletonServices = getSingletonServices()
+  const createWireServices = getCreateWireServices()
   let wireServices: WireServices | undefined
   const { openingData, channelName, session } =
-    await params.channelStore.getChannelAndSession(params.channelId)
+    await channelStore.getChannelAndSession(channelId)
 
   const { channel, channelHandler, channelConfig } = getVariablesForChannel({
-    ...params,
+    channelId,
+    channelHandlerFactory,
     openingData,
     channelName,
   })
 
-  const userSession = new PikkuSessionService(
-    params.channelStore,
-    params.channelId
-  )
+  const userSession = new PikkuSessionService(channelStore, channelId)
   userSession.setInitial(session)
   const wire: PikkuWire = {
     channel,
     ...createMiddlewareSessionWireProps(userSession),
   }
 
-  if (params.createWireServices) {
-    wireServices = await params.createWireServices(singletonServices, wire)
+  if (createWireServices) {
+    wireServices = await createWireServices(singletonServices, wire)
   }
 
   const services = {

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

@@ -1,5 +1,5 @@
 import { pikkuState } from '../../../pikku-state.js'
-import { CorePikkuCLIRender, type CLIMeta } from '../cli.types.js'
+import type { CorePikkuCLIRender, CLIMeta } from '../cli.types.js'
 import { generateCommandHelp, parseCLIArguments } from '../command-parser.js'
 
 /**

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

@@ -1,7 +1,7 @@
 import { test, describe, beforeEach, afterEach } from 'node:test'
 import * as assert from 'assert'
 import { NotFoundError } from '../../errors/errors.js'
-import { CorePikkuMiddleware } from '../../types/core.types.js'
+import type { CorePikkuMiddleware } from '../../types/core.types.js'
 import { wireCLI, runCLICommand, pikkuCLIRender } from './cli-runner.js'
 import { pikkuState, resetPikkuState } from '../../pikku-state.js'
 import { addFunction } from '../../function/function-runner.js'