@pikku/core 0.11.2 → 0.12.1

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 } from './rpc-runner.js'
+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,8 +1,27 @@
-import { CoreServices, 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 { PikkuRPC, ResolvedFunction } from './rpc-types.js'
+import { PikkuError } from '../../errors/error-handler.js'
+import type { PikkuRPC, ResolvedFunction } from './rpc-types.js'
+import { parseVersionedId } from '../../version.js'
+import { encryptJSON } from '../../crypto-utils.js'
+
+export class RPCNotFoundError extends PikkuError {
+  public readonly rpcName: string
+  constructor(rpcName: string) {
+    super(`RPC function not found: ${rpcName}`)
+    this.rpcName = rpcName
+  }
+}
+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
@@ -19,23 +38,30 @@ const resolveNamespace = (
   const namespace = namespacedFunction.substring(0, colonIndex)
   const functionName = namespacedFunction.substring(colonIndex + 1)
 
-  const externalPackages = pikkuState(null, 'rpc', 'externalPackages')
-  const packageName = externalPackages.get(namespace)
-  if (!packageName) {
+  const addons = pikkuState(null, 'rpc', 'addons')
+  const pkgConfig = addons.get(namespace)
+  if (!pkgConfig) {
     return null
   }
 
   return {
-    package: packageName,
+    namespace,
+    package: pkgConfig.package,
     function: functionName,
   }
 }
 
 const getPikkuFunctionName = (rpcName: string): string => {
   const rpc = pikkuState(null, 'rpc', 'meta')
-  const rpcMeta = rpc[rpcName]
+  let rpcMeta = rpc[rpcName]
   if (!rpcMeta) {
-    throw new Error(`RPC function not found: ${rpcName}`)
+    const { baseName, version } = parseVersionedId(rpcName)
+    if (version !== null) {
+      rpcMeta = rpc[baseName]
+    }
+  }
+  if (!rpcMeta) {
+    throw new RPCNotFoundError(rpcName)
   }
   return rpcMeta
 }
@@ -47,11 +73,22 @@ export class ContextAwareRPCService {
     private wire: PikkuWire,
     private options: {
       requiresAuth?: boolean
+      sessionService?: SessionService<CoreUserSession>
     }
   ) {}
 
   public async rpcExposed(funcName: string, data: any): Promise<any> {
-    const functionMeta = pikkuState(null, 'function', 'meta')[funcName]
+    let functionMeta: any
+    if (funcName.includes(':')) {
+      const resolved = resolveNamespace(funcName)
+      if (resolved) {
+        functionMeta = pikkuState(resolved.package, 'function', 'meta')[
+          resolved.function
+        ]
+      }
+    } else {
+      functionMeta = pikkuState(null, 'function', 'meta')[funcName]
+    }
     if (!functionMeta) {
       throw new Error(`Function not found: ${funcName}`)
     }
@@ -79,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
@@ -93,8 +126,6 @@ export class ContextAwareRPCService {
       getPikkuFunctionName(funcName),
       {
         auth: this.options.requiresAuth,
-        // TODO: this is a hack since services have already been created
-        // but is valid since we don't want to keep creating new wire services
         singletonServices: this.services,
         data: () => data,
         wire: updatedWire,
@@ -103,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
@@ -118,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.pikkuFuncName || resolved.function
+    const funcName = funcMeta.pikkuFuncId || resolved.function
+
+    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 external package's state
-    // We use the parent services (this.services) since external packages share services
+    // 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,
     })
   }
 
@@ -183,17 +216,184 @@ export class ContextAwareRPCService {
 
   public async startWorkflow<In = any>(
     workflowName: string,
-    input: In
+    input: In,
+    options?: {
+      startNode?: string
+      wire?: { type: string; id?: string; parentRunId?: string }
+    }
   ): Promise<{ runId: string }> {
     if (!this.services.workflowService) {
       throw new Error('WorkflowService service not available')
     }
+    const parentRunId = this.wire.workflowStep?.runId ?? this.wire.graph?.runId
+    const wire = options?.wire ?? {
+      type: this.wire.wireType ?? 'unknown',
+      id: this.wire.wireId,
+      ...(parentRunId ? { parentRunId } : {}),
+    }
     return this.services.workflowService.startWorkflow(
       workflowName,
       input,
-      this
+      wire,
+      this,
+      options
     )
   }
+
+  public get agent() {
+    return {
+      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
+        )
+      },
+    }
+  }
+
+  public async remote<In = any, Out = any>(
+    funcName: string,
+    data: In
+  ): Promise<Out> {
+    let endpoint: string | undefined
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+    }
+
+    const colonIndex = funcName.indexOf(':')
+    if (colonIndex !== -1) {
+      const namespace = funcName.substring(0, colonIndex)
+      const addons = pikkuState(null, 'rpc', 'addons')
+      const pkgConfig = addons.get(namespace)
+      endpoint = pkgConfig?.rpcEndpoint
+    }
+
+    if (!endpoint && this.services.deploymentService) {
+      const deployments =
+        await this.services.deploymentService.findFunction(funcName)
+      if (deployments.length > 0) {
+        endpoint = deployments[0].endpoint
+      }
+    }
+
+    if (!endpoint) {
+      throw new Error(
+        `No endpoint configured for remote RPC: ${funcName}. ` +
+          `Configure rpcEndpoint in addons config or set up a DeploymentService.`
+      )
+    }
+
+    let secret: string | undefined
+    if (this.services.secrets) {
+      try {
+        secret = await this.services.secrets.getSecret('PIKKU_REMOTE_SECRET')
+      } catch {}
+    }
+    if (secret) {
+      if (!this.services.jwt) {
+        throw new Error(
+          'PIKKU_REMOTE_SECRET is set but JWT service is not available'
+        )
+      }
+      const session =
+        this.wire.getSession && typeof this.wire.getSession === 'function'
+          ? await this.wire.getSession()
+          : (this.wire as any).session
+      const sessionEnc = session
+        ? await encryptJSON(secret, { session })
+        : undefined
+      const token = await this.services.jwt.encode(
+        { value: 5, unit: 'minute' },
+        {
+          aud: 'pikku-remote',
+          fn: funcName,
+          iat: Date.now(),
+          session: sessionEnc,
+        }
+      )
+      headers.Authorization = `Bearer ${token}`
+    }
+
+    const url = `${endpoint}/rpc/${encodeURIComponent(funcName)}`
+    const timeoutMs = 30_000
+    const response = await fetch(url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({ data }),
+      signal: AbortSignal.timeout(timeoutMs),
+    })
+
+    if (!response.ok) {
+      let errorBody: string
+      try {
+        errorBody = JSON.stringify(await response.json())
+      } catch {
+        errorBody = await response.text()
+      }
+      throw new Error(
+        `Remote RPC call failed: ${response.status} ${response.statusText}. ${errorBody}`
+      )
+    }
+
+    try {
+      return (await response.json()) as Out
+    } catch {
+      const text = await response.text()
+      throw new Error(
+        `Remote RPC call returned non-JSON response: ${response.status} ${response.statusText}. ${text}`
+      )
+    }
+  }
 }
 
 // RPC Service class for the global interface
@@ -205,18 +405,31 @@ export class PikkuRPCService<
   getContextRPCService(
     services: Services,
     wire: PikkuWire,
-    requiresAuth?: boolean | undefined,
+    requiresAuthOrOptions?:
+      | boolean
+      | {
+          requiresAuth?: boolean
+          sessionService?: SessionService<CoreUserSession>
+        }
+      | undefined,
     depth: number = 0
   ): TypedRPC {
-    const serviceRPC = new ContextAwareRPCService(services, wire, {
-      requiresAuth,
-    })
+    const options =
+      typeof requiresAuthOrOptions === 'object' &&
+      requiresAuthOrOptions !== null
+        ? requiresAuthOrOptions
+        : { requiresAuth: requiresAuthOrOptions }
+    const serviceRPC = new ContextAwareRPCService(services, wire, options)
     return {
       depth,
       global: false,
       invoke: serviceRPC.rpc.bind(serviceRPC),
-      invokeExposed: serviceRPC.rpc.bind(serviceRPC),
+      remote: serviceRPC.remote.bind(serviceRPC),
+      exposed: serviceRPC.rpcExposed.bind(serviceRPC),
       startWorkflow: serviceRPC.startWorkflow.bind(serviceRPC),
+      get agent() {
+        return serviceRPC.agent
+      },
       rpcWithWire: serviceRPC.rpcWithWire.bind(serviceRPC),
     } as any
   }

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

@@ -1,13 +1,36 @@
-export type PikkuRPC<invoke extends Function = any> = {
+export type PikkuRPC<
+  Invoke extends Function = any,
+  Remote extends Function = any,
+  startWorkflow extends Function = any,
+  AgentRun extends Function = any,
+  AgentStream extends Function = any,
+> = {
   depth: number
   global: boolean
-  invoke: invoke
+  invoke: Invoke
+  remote: Remote
+  exposed: (name: string, data: any) => Promise<any>
+  startWorkflow: startWorkflow
+  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 = {
-  pikkuFuncName: string
+  pikkuFuncId: string
   expose: boolean
-  internal?: boolean
+  remote?: boolean
 }
 
 /**
@@ -22,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,9 +1,11 @@
-export * from './scheduler.types.js'
-
 export {
   runScheduledTask,
   wireScheduler,
   getScheduledTasks,
 } from './scheduler-runner.js'
-
-export * from './log-schedulers.js'
+export { logSchedulers } from './log-schedulers.js'
+export type {
+  CoreScheduledTask,
+  ScheduledTasksMeta,
+  PikkuScheduledTask,
+} from './scheduler.types.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.