@pikku/core 0.12.0 → 0.12.2

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

@@ -1,4 +1,4 @@
-import type { CoreServices, PikkuWire } from '../../types/core.types.js'
+import type { PikkuWire } from '../../types/core.types.js'
 import type { CoreQueueWorker, QueueJob, PikkuQueue } from './queue.types.js'
 import type {
   CorePikkuFunctionConfig,
@@ -6,9 +6,12 @@ import type {
 } from '../../function/functions.types.js'
 import { getErrorResponse, PikkuError } from '../../errors/error-handler.js'
 import { PikkuMissingMetaError } from '../../errors/errors.js'
-import { pikkuState } from '../../pikku-state.js'
+import {
+  getSingletonServices,
+  getCreateWireServices,
+  pikkuState,
+} from '../../pikku-state.js'
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
-import { CreateWireServices } from '../../types/core.types.js'
 
 /**
  * Error class for queue processor not found
@@ -100,16 +103,14 @@ export async function removeQueueWorker(name: string): Promise<void> {
  * Process a single queue job - this function is called by queue consumers
  */
 export async function runQueueJob({
-  singletonServices,
-  createWireServices,
   job,
   updateProgress,
 }: {
-  singletonServices: CoreServices
-  createWireServices?: CreateWireServices
   job: QueueJob
   updateProgress?: (progress: number | string | object) => Promise<void>
 }): Promise<void> {
+  const singletonServices = getSingletonServices()
+  const createWireServices = getCreateWireServices()
   const logger = singletonServices.logger
 
   const meta = pikkuState(null, 'queue', 'meta')
@@ -189,26 +190,3 @@ export async function runQueueJob({
     throw error
   }
 }
-
-export const createQueueJobRunner = ({
-  singletonServices,
-  createWireServices,
-}: {
-  singletonServices: CoreServices
-  createWireServices?: CreateWireServices
-}) => {
-  return async ({
-    job,
-    updateProgress,
-  }: {
-    job: QueueJob
-    updateProgress?: (progress: number | string | object) => Promise<void>
-  }) => {
-    await runQueueJob({
-      singletonServices,
-      createWireServices,
-      job,
-      updateProgress,
-    })
-  }
-}

package/src/wirings/queue/queue.types.ts

@@ -1,7 +1,6 @@
-import { CommonWireMeta } from '../../types/core.types.js'
-import { CorePikkuFunctionConfig } from '../../function/functions.types.js'
-import { QueueConfigMapping } from './validate-worker-config.js'
-import { Logger } from '../../services/logger.js'
+import type { CommonWireMeta } from '../../types/core.types.js'
+import type { CorePikkuFunctionConfig } from '../../function/functions.types.js'
+import type { QueueConfigMapping } from './validate-worker-config.js'
 
 /**
  * Configuration for queue workers - how jobs are processed
@@ -139,15 +138,6 @@ export interface QueueWorkers {
   /** Configuration mapping for validation */
   configMappings: QueueConfigMapping
 
-  /** Set runtime queue job runner callback and logger */
-  setJobRunner(
-    runJob: (params: {
-      job: QueueJob
-      updateProgress?: (progress: number | string | object) => Promise<void>
-    }) => Promise<void>,
-    logger: Logger
-  ): void
-
   /** Scan state and register all compatible processors */
   registerQueues(): Promise<Record<string, ConfigValidationResult[]>>
 }

package/src/wirings/queue/register-queue-helper.ts

@@ -1,10 +1,8 @@
 import type { ConfigValidationResult, CoreQueueWorker } from './queue.types.js'
 import { getQueueWorkers } from './queue-runner.js'
-import {
-  QueueConfigMapping,
-  validateWorkerConfig,
-} from './validate-worker-config.js'
-import { Logger } from '../../services/logger.js'
+import type { QueueConfigMapping } from './validate-worker-config.js'
+import { validateWorkerConfig } from './validate-worker-config.js'
+import type { Logger } from '../../services/logger.js'
 
 /**
  * Queue processor registration callback

package/src/wirings/queue/validate-worker-config.test.ts

@@ -0,0 +1,108 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert'
+import { validateWorkerConfig } from './validate-worker-config.js'
+import type { QueueConfigMapping } from './validate-worker-config.js'
+
+const createTestMapping = (): QueueConfigMapping => ({
+  supported: {
+    concurrency: {
+      queueProperty: 'concurrency',
+      description: 'Number of concurrent workers',
+    },
+    maxRetries: {
+      queueProperty: 'maxRetries',
+      description: 'Maximum retry attempts',
+    },
+  },
+  unsupported: {
+    rateLimitMax: {
+      reason: 'Not supported',
+      explanation: 'This queue does not support rate limiting',
+    },
+  },
+  fallbacks: {
+    retryDelay: {
+      reason: 'Partial support',
+      explanation: 'Uses fixed delay instead of exponential',
+      fallbackValue: '1000ms fixed',
+    },
+  },
+})
+
+describe('validateWorkerConfig', () => {
+  test('should return empty results for empty config', () => {
+    const mapping = createTestMapping()
+    const result = validateWorkerConfig(mapping, {})
+    assert.deepStrictEqual(result.applied, {})
+    assert.deepStrictEqual(result.ignored, {})
+    assert.deepStrictEqual(result.warnings, [])
+    assert.deepStrictEqual(result.fallbacks, {})
+  })
+
+  test('should return empty results for undefined config', () => {
+    const mapping = createTestMapping()
+    const result = validateWorkerConfig(mapping)
+    assert.deepStrictEqual(result.applied, {})
+    assert.deepStrictEqual(result.ignored, {})
+  })
+
+  test('should apply supported configurations', () => {
+    const mapping = createTestMapping()
+    const result = validateWorkerConfig(mapping, { concurrency: 5 } as any)
+    assert.deepStrictEqual(result.applied, { concurrency: 5 })
+    assert.deepStrictEqual(result.ignored, {})
+    assert.strictEqual(result.warnings.length, 0)
+  })
+
+  test('should ignore unsupported configurations with warning', () => {
+    const mapping = createTestMapping()
+    const result = validateWorkerConfig(mapping, { rateLimitMax: 100 } as any)
+    assert.deepStrictEqual(result.ignored, { rateLimitMax: 100 })
+    assert.strictEqual(result.warnings.length, 1)
+    assert.ok(result.warnings[0].includes('Not supported'))
+  })
+
+  test('should handle fallback configurations', () => {
+    const mapping = createTestMapping()
+    const result = validateWorkerConfig(mapping, { retryDelay: 2000 } as any)
+    assert.deepStrictEqual(result.applied, { retryDelay: 2000 })
+    assert.deepStrictEqual(result.fallbacks, { retryDelay: '1000ms fixed' })
+    assert.strictEqual(result.warnings.length, 1)
+    assert.ok(result.warnings[0].includes('Partial support'))
+  })
+
+  test('should warn about unknown configurations', () => {
+    const mapping = createTestMapping()
+    const result = validateWorkerConfig(mapping, {
+      unknownOption: 'val',
+    } as any)
+    assert.deepStrictEqual(result.ignored, { unknownOption: 'val' })
+    assert.strictEqual(result.warnings.length, 1)
+    assert.ok(result.warnings[0].includes('Unknown configuration'))
+  })
+
+  test('should skip undefined values', () => {
+    const mapping = createTestMapping()
+    const result = validateWorkerConfig(mapping, {
+      concurrency: undefined,
+    } as any)
+    assert.deepStrictEqual(result.applied, {})
+  })
+
+  test('should handle mixed supported and unsupported configs', () => {
+    const mapping = createTestMapping()
+    const result = validateWorkerConfig(mapping, {
+      concurrency: 3,
+      maxRetries: 5,
+      rateLimitMax: 100,
+      retryDelay: 1000,
+    } as any)
+    assert.deepStrictEqual(result.applied, {
+      concurrency: 3,
+      maxRetries: 5,
+      retryDelay: 1000,
+    })
+    assert.deepStrictEqual(result.ignored, { rateLimitMax: 100 })
+    assert.strictEqual(result.warnings.length, 2)
+  })
+})

package/src/wirings/queue/validate-worker-config.ts

@@ -1,4 +1,7 @@
-import { PikkuWorkerConfig, ConfigValidationResult } from './queue.types.js'
+import type {
+  PikkuWorkerConfig,
+  ConfigValidationResult,
+} from './queue.types.js'
 
 /**
  * Configuration mapping structure for queue implementations

package/src/wirings/rpc/index.ts

@@ -1,2 +1,4 @@
 export { PikkuRPCService, rpcService, RPCNotFoundError } from './rpc-runner.js'
 export type { PikkuRPC, RPCMeta } from './rpc-types.js'
+export { wireAddon } from './wire-addon.js'
+export type { WireAddonConfig } from './wire-addon.js'

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.