@pikku/core 0.12.0 → 0.12.1

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

@@ -1,15 +1,11 @@
-import {
-  CoreServices,
-  CoreSingletonServices,
-  PikkuWire,
-} from '../../types/core.types.js'
+import type { CoreServices, PikkuWire } from '../../types/core.types.js'
 import type { SessionService } from '../../services/user-session-service.js'
 import type { CoreUserSession } from '../../types/core.types.js'
 import { runPikkuFunc } from '../../function/function-runner.js'
 import { pikkuState } from '../../pikku-state.js'
 import { ForbiddenError } from '../../errors/errors.js'
 import { PikkuError } from '../../errors/error-handler.js'
-import { PikkuRPC, ResolvedFunction } from './rpc-types.js'
+import type { PikkuRPC, ResolvedFunction } from './rpc-types.js'
 import { parseVersionedId } from '../../version.js'
 import { encryptJSON } from '../../crypto-utils.js'
 
@@ -21,7 +17,11 @@ export class RPCNotFoundError extends PikkuError {
   }
 }
 import type { AIAgentInput } from '../ai-agent/ai-agent.types.js'
+import type { AIStreamChannel } from '../ai-agent/ai-agent.types.js'
+import type { StreamAIAgentOptions } from '../ai-agent/ai-agent-prepare.js'
 import { runAIAgent } from '../ai-agent/ai-agent-runner.js'
+import { streamAIAgent, resumeAIAgent } from '../ai-agent/ai-agent-stream.js'
+import { approveAIAgent } from '../ai-agent/ai-agent-registry.js'
 
 /**
  * Resolve a namespaced function reference to package and function names
@@ -38,13 +38,14 @@ const resolveNamespace = (
   const namespace = namespacedFunction.substring(0, colonIndex)
   const functionName = namespacedFunction.substring(colonIndex + 1)
 
-  const externalPackages = pikkuState(null, 'rpc', 'externalPackages')
-  const pkgConfig = externalPackages.get(namespace)
+  const addons = pikkuState(null, 'rpc', 'addons')
+  const pkgConfig = addons.get(namespace)
   if (!pkgConfig) {
     return null
   }
 
   return {
+    namespace,
     package: pkgConfig.package,
     function: functionName,
   }
@@ -115,11 +116,7 @@ export class ContextAwareRPCService {
 
     // Check if it's a namespaced function call (e.g., 'stripe:createCharge')
     if (funcName.includes(':')) {
-      return this.invokeExternalPackageFunction<In, Out>(
-        funcName,
-        data,
-        updatedWire
-      )
+      return this.invokeAddonFunction<In, Out>(funcName, data, updatedWire)
     }
 
     // Main package function
@@ -137,12 +134,12 @@ export class ContextAwareRPCService {
   }
 
   /**
-   * Invoke a function from an external package
-   * External packages register their functions in pikkuState under their package name.
+   * Invoke a function from an addon package
+   * Addon packages register their functions in pikkuState under their package name.
    * The function is executed using the parent services (shared singleton services).
    * @private
    */
-  private async invokeExternalPackageFunction<In = any, Out = any>(
+  private async invokeAddonFunction<In = any, Out = any>(
     namespacedFunction: string,
     data: In,
     wire: PikkuWire
@@ -152,36 +149,38 @@ export class ContextAwareRPCService {
     if (!resolved) {
       throw new Error(
         `Unknown namespace in function reference: ${namespacedFunction}. ` +
-          `Make sure the package is registered in externalPackages config.`
+          `Make sure the package is registered in addons config.`
       )
     }
 
-    // Get the function meta from the external package
-    // External packages use function meta, not RPC meta
-    const externalFunctionMeta = pikkuState(
-      resolved.package,
-      'function',
-      'meta'
-    )
-    const funcMeta = externalFunctionMeta[resolved.function]
+    // Get the function meta from the addon package
+    // Addon packages use function meta, not RPC meta
+    const addonFunctionMeta = pikkuState(resolved.package, 'function', 'meta')
+    const funcMeta = addonFunctionMeta[resolved.function]
     if (!funcMeta) {
       throw new Error(
         `Function '${resolved.function}' not found in package '${resolved.package}'. ` +
-          `Available functions: ${Object.keys(externalFunctionMeta).join(', ') || '(none)'}`
+          `Available functions: ${Object.keys(addonFunctionMeta).join(', ') || '(none)'}`
       )
     }
     const funcName = funcMeta.pikkuFuncId || resolved.function
 
-    // Execute the function using runPikkuFunc with the external package's state
-    // We use the parent services (this.services) since external packages share services
+    const addonConfig = pikkuState(null, 'rpc', 'addons').get(
+      resolved.namespace
+    )
+    const auth = addonConfig?.auth ?? this.options.requiresAuth
+    const tags = [...(addonConfig?.tags ?? []), ...(funcMeta.tags ?? [])]
+
+    // Execute the function using runPikkuFunc with the addon package's state
+    // We use the parent services (this.services) since addon packages share services
     // Pass the function's tags so tag-based middleware/permissions are applied
     return runPikkuFunc<In, Out>('rpc', namespacedFunction, funcName, {
-      auth: this.options.requiresAuth,
+      auth,
       singletonServices: this.services,
       data: () => data,
       wire,
       packageName: resolved.package,
-      tags: funcMeta.tags,
+      tags,
     })
   }
 
@@ -241,22 +240,64 @@ export class ContextAwareRPCService {
     )
   }
 
-  public async agent(
-    agentName: string,
-    input: AIAgentInput
-  ): Promise<{
-    runId: string
-    result: unknown
-    usage: { inputTokens: number; outputTokens: number }
-  }> {
-    const result = await runAIAgent(agentName, input, {
-      singletonServices: this.services as CoreSingletonServices,
-      sessionService: this.options.sessionService,
-    })
+  public get agent() {
     return {
-      runId: result.runId,
-      result: result.object ?? result.text,
-      usage: result.usage,
+      run: async (agentName: string, input: AIAgentInput) => {
+        const result = await runAIAgent(agentName, input, {
+          sessionService: this.options.sessionService,
+        })
+        return {
+          runId: result.runId,
+          result: result.object ?? result.text,
+          usage: result.usage,
+        }
+      },
+      stream: async (
+        agentName: string,
+        input:
+          | { message: string; threadId: string; resourceId: string }
+          | Record<string, unknown>,
+        options?: StreamAIAgentOptions
+      ) => {
+        const channel = this.wire.channel as unknown as AIStreamChannel
+        if (!channel) throw new Error('No channel available for streaming')
+        await streamAIAgent(
+          agentName,
+          input,
+          channel,
+          { sessionService: this.options.sessionService },
+          undefined,
+          options
+        )
+      },
+      resume: async (
+        runId: string,
+        input: { toolCallId: string; approved: boolean },
+        options?: StreamAIAgentOptions
+      ) => {
+        const channel = this.wire.channel as unknown as AIStreamChannel
+        if (!channel) throw new Error('No channel available for streaming')
+        await resumeAIAgent(
+          { runId, ...input },
+          channel,
+          { sessionService: this.options.sessionService },
+          options
+        )
+      },
+      approve: async (
+        runId: string,
+        approvals: { toolCallId: string; approved: boolean }[],
+        expectedAgentName?: string
+      ) => {
+        if (!this.services.aiRunState)
+          throw new Error('AIRunStateService not available')
+        return approveAIAgent(
+          this.services.aiRunState,
+          runId,
+          approvals,
+          expectedAgentName
+        )
+      },
     }
   }
 
@@ -272,8 +313,8 @@ export class ContextAwareRPCService {
     const colonIndex = funcName.indexOf(':')
     if (colonIndex !== -1) {
       const namespace = funcName.substring(0, colonIndex)
-      const externalPackages = pikkuState(null, 'rpc', 'externalPackages')
-      const pkgConfig = externalPackages.get(namespace)
+      const addons = pikkuState(null, 'rpc', 'addons')
+      const pkgConfig = addons.get(namespace)
       endpoint = pkgConfig?.rpcEndpoint
     }
 
@@ -288,7 +329,7 @@ export class ContextAwareRPCService {
     if (!endpoint) {
       throw new Error(
         `No endpoint configured for remote RPC: ${funcName}. ` +
-          `Configure rpcEndpoint in externalPackages config or set up a DeploymentService.`
+          `Configure rpcEndpoint in addons config or set up a DeploymentService.`
       )
     }
 
@@ -386,7 +427,9 @@ export class PikkuRPCService<
       remote: serviceRPC.remote.bind(serviceRPC),
       exposed: serviceRPC.rpcExposed.bind(serviceRPC),
       startWorkflow: serviceRPC.startWorkflow.bind(serviceRPC),
-      agent: serviceRPC.agent.bind(serviceRPC),
+      get agent() {
+        return serviceRPC.agent
+      },
       rpcWithWire: serviceRPC.rpcWithWire.bind(serviceRPC),
     } as any
   }

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

@@ -2,7 +2,8 @@ export type PikkuRPC<
   Invoke extends Function = any,
   Remote extends Function = any,
   startWorkflow extends Function = any,
-  Agent extends Function = any,
+  AgentRun extends Function = any,
+  AgentStream extends Function = any,
 > = {
   depth: number
   global: boolean
@@ -10,7 +11,20 @@ export type PikkuRPC<
   remote: Remote
   exposed: (name: string, data: any) => Promise<any>
   startWorkflow: startWorkflow
-  agent: Agent
+  agent: {
+    run: AgentRun
+    stream: AgentStream
+    resume: (
+      runId: string,
+      input: { toolCallId: string; approved: boolean },
+      options?: any
+    ) => Promise<void>
+    approve: (
+      runId: string,
+      approvals: { toolCallId: string; approved: boolean }[],
+      expectedAgentName?: string
+    ) => Promise<any>
+  }
 }
 
 export type RPCMeta = {
@@ -31,6 +45,7 @@ export interface RPCHandler<Input, Output> {
  * Resolved function reference from namespace
  */
 export interface ResolvedFunction {
+  namespace: string
   package: string
   function: string
 }

package/src/wirings/rpc/wire-addon.ts

@@ -0,0 +1,20 @@
+import { pikkuState } from '../../pikku-state.js'
+
+export type WireAddonConfig = {
+  name: string
+  package: string
+  rpcEndpoint?: string
+  auth?: boolean
+  tags?: string[]
+  secretOverrides?: Record<string, string>
+  variableOverrides?: Record<string, string>
+}
+
+export const wireAddon = (config: WireAddonConfig): void => {
+  pikkuState(null, 'rpc', 'addons').set(config.name, {
+    package: config.package,
+    rpcEndpoint: config.rpcEndpoint,
+    auth: config.auth,
+    tags: config.tags,
+  })
+}

package/src/wirings/scheduler/index.ts

@@ -1,6 +1,5 @@
 export {
   runScheduledTask,
-  createSchedulerRuntimeHandlers,
   wireScheduler,
   getScheduledTasks,
 } from './scheduler-runner.js'

package/src/wirings/scheduler/log-schedulers.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 scheduled tasks.

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

@@ -4,11 +4,10 @@ import {
   wireScheduler,
   runScheduledTask,
   getScheduledTasks,
-  createSchedulerRuntimeHandlers,
 } from './scheduler-runner.js'
 import { resetPikkuState, pikkuState } from '../../pikku-state.js'
-import { CoreScheduledTask } from './scheduler.types.js'
-import { CoreUserSession } from '../../types/core.types.js'
+import type { CoreScheduledTask } from './scheduler.types.js'
+import type { CoreUserSession } from '../../types/core.types.js'
 
 beforeEach(() => {
   resetPikkuState()
@@ -168,9 +167,11 @@ describe('runScheduledTask', () => {
     wireScheduler(mockTask)
 
     const mockLogger = createMockLogger()
+    pikkuState(null, 'package', 'singletonServices', {
+      logger: mockLogger,
+    } as any)
     await runScheduledTask({
       name: 'simple-task',
-      singletonServices: { logger: mockLogger } as any,
     })
 
     assert.equal(taskExecuted, true)
@@ -208,12 +209,14 @@ describe('runScheduledTask', () => {
     wireScheduler(mockTask)
 
     const mockLogger = createMockLogger()
+    pikkuState(null, 'package', 'singletonServices', {
+      logger: mockLogger,
+    } as any)
     const session: CoreUserSession = { userId: 'user123' }
 
     await runScheduledTask({
       name: 'task-with-session',
       session,
-      singletonServices: { logger: mockLogger } as any,
     })
 
     assert.deepEqual(receivedSession, session)
@@ -221,12 +224,14 @@ describe('runScheduledTask', () => {
 
   test('should throw ScheduledTaskNotFoundError when task not found', async () => {
     const mockLogger = createMockLogger()
+    pikkuState(null, 'package', 'singletonServices', {
+      logger: mockLogger,
+    } as any)
 
     await assert.rejects(
       async () => {
         await runScheduledTask({
           name: 'non-existent-task',
-          singletonServices: { logger: mockLogger } as any,
         })
       },
       (error: any) => {
@@ -250,12 +255,14 @@ describe('runScheduledTask', () => {
     pikkuState(null, 'scheduler', 'tasks').set('task-without-meta', mockTask)
 
     const mockLogger = createMockLogger()
+    pikkuState(null, 'package', 'singletonServices', {
+      logger: mockLogger,
+    } as any)
 
     await assert.rejects(
       async () => {
         await runScheduledTask({
           name: 'task-without-meta',
-          singletonServices: { logger: mockLogger } as any,
         })
       },
       (error: any) => {
@@ -290,12 +297,14 @@ describe('runScheduledTask', () => {
     wireScheduler(mockTask)
 
     const mockLogger = createMockLogger()
+    pikkuState(null, 'package', 'singletonServices', {
+      logger: mockLogger,
+    } as any)
 
     await assert.rejects(
       async () => {
         await runScheduledTask({
           name: 'skipped-task',
-          singletonServices: { logger: mockLogger } as any,
         })
       },
       (error: any) => {
@@ -333,12 +342,14 @@ describe('runScheduledTask', () => {
     wireScheduler(mockTask)
 
     const mockLogger = createMockLogger()
+    pikkuState(null, 'package', 'singletonServices', {
+      logger: mockLogger,
+    } as any)
 
     await assert.rejects(
       async () => {
         await runScheduledTask({
           name: 'skipped-task-no-reason',
-          singletonServices: { logger: mockLogger } as any,
         })
       },
       (error: any) => {
@@ -379,10 +390,12 @@ describe('runScheduledTask', () => {
     wireScheduler(mockTask)
 
     const mockLogger = createMockLogger()
+    pikkuState(null, 'package', 'singletonServices', {
+      logger: mockLogger,
+    } as any)
 
     await runScheduledTask({
       name: 'wire-task',
-      singletonServices: { logger: mockLogger } as any,
     })
 
     assert.equal(capturedWire.scheduledTask.name, 'wire-task')
@@ -417,14 +430,18 @@ describe('runScheduledTask', () => {
     wireScheduler(mockTask)
 
     const mockLogger = createMockLogger()
-
-    await runScheduledTask({
-      name: 'session-services-task',
-      singletonServices: { logger: mockLogger } as any,
+    pikkuState(null, 'package', 'singletonServices', {
+      logger: mockLogger,
+    } as any)
+    pikkuState(null, 'package', 'factories', {
       createWireServices: async () => {
         createWireServicesCalled = true
         return mockWireService as any
       },
+    } as any)
+
+    await runScheduledTask({
+      name: 'session-services-task',
     })
 
     assert.equal(createWireServicesCalled, true)
@@ -462,11 +479,15 @@ describe('runScheduledTask', () => {
     wireScheduler(mockTask)
 
     const mockLogger = createMockLogger()
+    pikkuState(null, 'package', 'singletonServices', {
+      logger: mockLogger,
+    } as any)
+    pikkuState(null, 'package', 'factories', {
+      createWireServices: async () => mockWireService as any,
+    } as any)
 
     await runScheduledTask({
       name: 'cleanup-task',
-      singletonServices: { logger: mockLogger } as any,
-      createWireServices: async () => mockWireService as any,
     })
 
     assert.equal(closeCalled, true)
@@ -506,12 +527,16 @@ describe('runScheduledTask', () => {
     wireScheduler(mockTask)
 
     const mockLogger = createMockLogger()
+    pikkuState(null, 'package', 'singletonServices', {
+      logger: mockLogger,
+    } as any)
+    pikkuState(null, 'package', 'factories', {
+      createWireServices: async () => mockWireService as any,
+    } as any)
 
     await assert.rejects(async () => {
       await runScheduledTask({
         name: 'error-cleanup-task',
-        singletonServices: { logger: mockLogger } as any,
-        createWireServices: async () => mockWireService as any,
       })
     })
 
@@ -543,11 +568,13 @@ describe('runScheduledTask', () => {
     wireScheduler(mockTask)
 
     const mockLogger = createMockLogger()
+    pikkuState(null, 'package', 'singletonServices', {
+      logger: mockLogger,
+    } as any)
 
     await assert.rejects(async () => {
       await runScheduledTask({
         name: 'error-task',
-        singletonServices: { logger: mockLogger } as any,
       })
     })
 
@@ -590,10 +617,12 @@ describe('runScheduledTask', () => {
     wireScheduler(mockTask)
 
     const mockLogger = createMockLogger()
+    pikkuState(null, 'package', 'singletonServices', {
+      logger: mockLogger,
+    } as any)
 
     await runScheduledTask({
       name: 'middleware-task',
-      singletonServices: { logger: mockLogger } as any,
     })
 
     assert.deepEqual(executionOrder, ['middleware', 'task'])
@@ -629,43 +658,3 @@ describe('getScheduledTasks', () => {
     assert.equal(tasks.size, 0)
   })
 })
-
-describe('createSchedulerRuntimeHandlers', () => {
-  test('invokes RPC with optional session and runs scheduled task callback', async () => {
-    const calls: Array<{ type: string; value: any }> = []
-    const logger = createMockLogger()
-    const singletonServices = { logger } as any
-
-    const handlers = createSchedulerRuntimeHandlers({
-      singletonServices,
-    })
-
-    const originalGetContextRPCService = (await import('../rpc/rpc-runner.js'))
-      .rpcService.getContextRPCService
-    ;(await import('../rpc/rpc-runner.js')).rpcService.getContextRPCService = ((
-      _services: any,
-      wire: any
-    ) => {
-      calls.push({ type: 'wire', value: wire })
-      return {
-        invoke: async (rpcName: string, data: any) => {
-          calls.push({ type: 'invoke', value: { rpcName, data } })
-        },
-      } as any
-    }) as any
-
-    try {
-      await handlers.invokeRPC('testRpc', { value: 1 }, { userId: 'u1' } as any)
-    } finally {
-      ;(await import('../rpc/rpc-runner.js')).rpcService.getContextRPCService =
-        originalGetContextRPCService
-    }
-
-    assert.equal(calls[0]?.type, 'wire')
-    assert.deepEqual(calls[0]?.value, { session: { userId: 'u1' } })
-    assert.deepEqual(calls[1]?.value, {
-      rpcName: 'testRpc',
-      data: { value: 1 },
-    })
-  })
-})

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

@@ -1,36 +1,25 @@
-import {
-  PikkuWire,
-  type CoreServices,
-  type CoreSingletonServices,
-  type CoreUserSession,
-  type CreateWireServices,
-} from '../../types/core.types.js'
+import type { PikkuWire, CoreUserSession } from '../../types/core.types.js'
 import type { CoreScheduledTask } from './scheduler.types.js'
 import { getErrorResponse, PikkuError } from '../../errors/error-handler.js'
 import { PikkuMissingMetaError } from '../../errors/errors.js'
-import { closeWireServices } from '../../utils.js'
-import { pikkuState } from '../../pikku-state.js'
+import {
+  getSingletonServices,
+  getCreateWireServices,
+  pikkuState,
+} from '../../pikku-state.js'
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
 import {
   PikkuSessionService,
   createMiddlewareSessionWireProps,
 } from '../../services/user-session-service.js'
-import {
+import type {
   CorePikkuFunctionConfig,
   CorePikkuFunctionSessionless,
 } from '../../function/functions.types.js'
-import { rpcService } from '../rpc/rpc-runner.js'
-import { SchedulerRuntimeHandlers } from '../../services/scheduler-service.js'
 
 export type RunScheduledTasksParams = {
   name: string
   session?: CoreUserSession
-  singletonServices: CoreSingletonServices
-  createWireServices?: CreateWireServices<
-    CoreSingletonServices,
-    CoreServices<CoreSingletonServices>,
-    CoreUserSession
-  >
 }
 
 export const wireScheduler = <
@@ -80,10 +69,9 @@ class ScheduledTaskSkippedError extends PikkuError {
 export async function runScheduledTask({
   name,
   session,
-  singletonServices,
-  createWireServices,
 }: RunScheduledTasksParams): Promise<void> {
-  let wireServices: any
+  const singletonServices = getSingletonServices()
+  const createWireServices = getCreateWireServices()
   const task = pikkuState(null, 'scheduler', 'tasks').get(name)
   const meta = pikkuState(null, 'scheduler', 'meta')[name]
 
@@ -136,44 +124,9 @@ export async function runScheduledTask({
       singletonServices.logger.error(e)
     }
     throw e
-  } finally {
-    if (wireServices) {
-      await closeWireServices(singletonServices.logger, wireServices)
-    }
   }
 }
 
 export const getScheduledTasks = () => {
   return pikkuState(null, 'scheduler', 'tasks')
 }
-
-export const createSchedulerRuntimeHandlers = ({
-  singletonServices,
-  createWireServices,
-}: {
-  singletonServices: CoreSingletonServices
-  createWireServices?: CreateWireServices<
-    CoreSingletonServices,
-    CoreServices<CoreSingletonServices>,
-    CoreUserSession
-  >
-}): SchedulerRuntimeHandlers => {
-  return {
-    logger: singletonServices.logger,
-    invokeRPC: async (
-      rpcName: string,
-      data?: any,
-      session?: CoreUserSession
-    ) => {
-      const wire = session ? ({ session } as PikkuWire) : ({} as PikkuWire)
-      const rpc = rpcService.getContextRPCService(singletonServices, wire)
-      await rpc.invoke(rpcName, data)
-    },
-    runScheduledTask: async (name: string) =>
-      runScheduledTask({
-        name,
-        singletonServices,
-        createWireServices,
-      }),
-  }
-}

package/src/wirings/scheduler/scheduler.types.ts

@@ -1,9 +1,9 @@
-import {
+import type {
   CoreUserSession,
   CorePikkuMiddleware,
   CommonWireMeta,
 } from '../../types/core.types.js'
-import {
+import type {
   CorePikkuFunctionConfig,
   CorePikkuFunctionSessionless,
 } from '../../function/functions.types.js'