@pikku/core 0.12.1 → 0.12.3

package/src/crypto-utils.ts

@@ -97,3 +97,117 @@ export const decryptJSON = async <T>(
   )
   return JSON.parse(decoder.decode(new Uint8Array(decrypted))) as T
 }
+
+/**
+ * Envelope encryption utilities.
+ *
+ * Each secret gets its own random DEK (data encryption key).
+ * The DEK is wrapped (encrypted) by a KEK (key encryption key) — typically an env var.
+ * The actual secret is encrypted with the DEK.
+ *
+ * KEK rotation only re-wraps the DEK, never touches the ciphertext.
+ */
+
+const importRawKey = async (rawBytes: Uint8Array): Promise<CryptoKey> => {
+  const subtle = getSubtle()
+  return subtle.importKey(
+    'raw',
+    rawBytes.buffer as ArrayBuffer,
+    { name: 'AES-GCM' },
+    true,
+    ['encrypt', 'decrypt']
+  )
+}
+
+export const generateDEK = async (): Promise<string> => {
+  const raw = globalThis.crypto.getRandomValues(new Uint8Array(32))
+  return toBase64Url(raw)
+}
+
+export const wrapDEK = async (
+  kek: string,
+  plaintextDEK: string
+): Promise<string> => {
+  return encryptJSON(kek, plaintextDEK)
+}
+
+export const unwrapDEK = async (
+  kek: string,
+  wrappedDEK: string
+): Promise<string> => {
+  return decryptJSON<string>(kek, wrappedDEK)
+}
+
+const encryptWithDEK = async (
+  dekBase64: string,
+  value: unknown
+): Promise<string> => {
+  const crypto = globalThis.crypto
+  const subtle = getSubtle()
+  const iv = crypto.getRandomValues(new Uint8Array(12))
+  const key = await importRawKey(fromBase64Url(dekBase64))
+  const plaintext = encoder.encode(JSON.stringify(value))
+  const encrypted = await subtle.encrypt(
+    { name: 'AES-GCM', iv },
+    key,
+    plaintext
+  )
+  const cipherBytes = new Uint8Array(encrypted)
+  const out = new Uint8Array(iv.length + cipherBytes.length)
+  out.set(iv, 0)
+  out.set(cipherBytes, iv.length)
+  return toBase64Url(out)
+}
+
+const decryptWithDEK = async <T>(
+  dekBase64: string,
+  token: string
+): Promise<T> => {
+  const subtle = getSubtle()
+  const data = fromBase64Url(token)
+  if (data.length < 13) {
+    throw new Error('Invalid encrypted payload')
+  }
+  const iv = data.slice(0, 12)
+  const ciphertext = data.slice(12)
+  const key = await importRawKey(fromBase64Url(dekBase64))
+  const decrypted = await subtle.decrypt(
+    { name: 'AES-GCM', iv },
+    key,
+    ciphertext
+  )
+  return JSON.parse(decoder.decode(new Uint8Array(decrypted))) as T
+}
+
+export interface EnvelopeEncryptResult {
+  ciphertext: string
+  wrappedDEK: string
+}
+
+export const envelopeEncrypt = async (
+  kek: string,
+  value: unknown
+): Promise<EnvelopeEncryptResult> => {
+  const dek = await generateDEK()
+  const ciphertext = await encryptWithDEK(dek, value)
+  const wrappedDEK = await wrapDEK(kek, dek)
+  return { ciphertext, wrappedDEK }
+}
+
+export const envelopeDecrypt = async <T>(
+  kek: string,
+  ciphertext: string,
+  wrappedDEK: string
+): Promise<T> => {
+  const dek = await unwrapDEK(kek, wrappedDEK)
+  return decryptWithDEK<T>(dek, ciphertext)
+}
+
+export const envelopeRewrap = async (
+  oldKEK: string,
+  newKEK: string,
+  wrappedDEK: string
+): Promise<string> => {
+  const dek = await unwrapDEK(oldKEK, wrappedDEK)
+  return wrapDEK(newKEK, dek)
+}

package/src/function/function-runner.ts

@@ -95,7 +95,7 @@ export const getAllFunctionNames = (): string[] => {
   const mainFunctionsMeta = pikkuState(null, 'function', 'meta')
   functions.push(...Object.keys(mainFunctionsMeta))
 
-  const addons = pikkuState(null, 'rpc', 'addons')
+  const addons = pikkuState(null, 'addons', 'packages')
   for (const [namespace, config] of addons) {
     const packageFunctionsMeta = pikkuState(config.package, 'function', 'meta')
     for (const funcName of Object.keys(packageFunctionsMeta)) {
@@ -280,6 +280,10 @@ export const runPikkuFunc = async <In = any, Out = any>(
     // Validate and coerce data if schema is defined
     const inputSchemaName = funcMeta.inputSchemaName
     if (inputSchemaName) {
+      // Coerce (top level) data types before validation (e.g. string→array, string→date)
+      if (coerceDataFromSchema) {
+        coerceTopLevelDataFromSchema(inputSchemaName, actualData, packageName)
+      }
       // Validate request data against the defined schema, if any
       await validateSchema(
         resolvedSingletonServices.logger,
@@ -288,10 +292,6 @@ export const runPikkuFunc = async <In = any, Out = any>(
         actualData,
         packageName
       )
-      // Coerce (top level) query string parameters or date objects if specified by the schema
-      if (coerceDataFromSchema) {
-        coerceTopLevelDataFromSchema(inputSchemaName, actualData, packageName)
-      }
     }
 
     if (

package/src/function/functions.types.ts

@@ -7,6 +7,7 @@ import type {
   PickRequired,
 } from '../types/core.types.js'
 import type { StandardSchemaV1 } from '@standard-schema/spec'
+import type { PikkuError } from '../errors/error-handler.js'
 import type { CoreNodeConfig } from '../wirings/node/node.types.js'
 
 /**
@@ -194,6 +195,40 @@ export const pikkuPermissionFactory = <In = any>(
   return factory
 }
 
+/**
+ * A function that generates a human-readable description of a pending approval action.
+ * Used by AI agents to show meaningful approval prompts instead of raw tool arguments.
+ *
+ * @template In - The input type (same as the function it describes).
+ * @template Services - The services type, defaults to `CoreSingletonServices`.
+ */
+export type CorePikkuApprovalDescription<
+  In = any,
+  Services extends CoreSingletonServices = CoreSingletonServices,
+> = (services: Services, data: In) => Promise<string>
+
+/**
+ * Factory function for creating approval description functions with tree-shaking support.
+ *
+ * @example
+ * ```typescript
+ * export const deleteTodoApproval = pikkuApprovalDescription(
+ *   async ({ todoStore }, { id }) => {
+ *     const todo = await todoStore.get(id)
+ *     return `Delete todo: "${todo.title}"`
+ *   }
+ * )
+ * ```
+ */
+export const pikkuApprovalDescription = <
+  In = any,
+  Services extends CoreSingletonServices = CoreSingletonServices,
+>(
+  fn: CorePikkuApprovalDescription<In, Services>
+): CorePikkuApprovalDescription<In, Services> => {
+  return fn
+}
+
 export type CorePikkuAuth<
   Services extends CoreSingletonServices = CoreServices,
   Session extends CoreUserSession = CoreUserSession,
@@ -256,7 +291,8 @@ export type CorePikkuFunctionConfig<
   remote?: boolean
   mcp?: boolean
   readonly?: boolean
-  requiresApproval?: boolean
+  approvalRequired?: boolean
+  approvalDescription?: any
   func: PikkuFunction
   auth?: boolean
   permissions?: CorePermissionGroup<PikkuPermission>
@@ -264,4 +300,5 @@ export type CorePikkuFunctionConfig<
   input?: InputSchema
   output?: OutputSchema
   node?: CoreNodeConfig
+  errors?: Array<typeof PikkuError>
 }

package/src/handle-error.test.ts

@@ -267,7 +267,7 @@ describe('handleHTTPError', () => {
     // Should not throw
   })
 
-  test('should call response.close when available', () => {
+  test('should not call response.close automatically', () => {
     const logger = createMockLogger()
     const http = createMockHTTP()
     const error = new BadRequestError('bad')
@@ -282,7 +282,7 @@ describe('handleHTTPError', () => {
       false
     )
 
-    assert.strictEqual(http._state.closed, true)
+    assert.strictEqual(http._state.closed, false)
   })
 
   test('should handle undefined http gracefully', () => {
@@ -335,6 +335,69 @@ describe('handleHTTPError', () => {
     assert.ok(errors.some((e) => e.args[0] === 'just a string error'))
   })
 
+  test('should include message and stack when exposeErrors is true', () => {
+    const logger = createMockLogger()
+    const http = createMockHTTP()
+    const error = new Error('something unexpected')
+
+    handleHTTPError(
+      error,
+      http as any,
+      'tracker-expose',
+      logger as any,
+      [],
+      true,
+      false,
+      true
+    )
+
+    assert.strictEqual(http._state.statusCode, 500)
+    assert.strictEqual(http._state.jsonBody.errorId, 'tracker-expose')
+    assert.strictEqual(http._state.jsonBody.message, 'something unexpected')
+    assert.ok(typeof http._state.jsonBody.stack === 'string')
+  })
+
+  test('should not include message and stack when exposeErrors is false', () => {
+    const logger = createMockLogger()
+    const http = createMockHTTP()
+    const error = new Error('something unexpected')
+
+    handleHTTPError(
+      error,
+      http as any,
+      'tracker-no-expose',
+      logger as any,
+      [],
+      true,
+      false,
+      false
+    )
+
+    assert.strictEqual(http._state.statusCode, 500)
+    assert.deepStrictEqual(http._state.jsonBody, {
+      errorId: 'tracker-no-expose',
+    })
+  })
+
+  test('should not expose details for non-Error objects even when exposeErrors is true', () => {
+    const logger = createMockLogger()
+    const http = createMockHTTP()
+
+    handleHTTPError(
+      'string error',
+      http as any,
+      'tracker-str',
+      logger as any,
+      [],
+      true,
+      false,
+      true
+    )
+
+    assert.strictEqual(http._state.statusCode, 500)
+    assert.deepStrictEqual(http._state.jsonBody, { errorId: 'tracker-str' })
+  })
+
   test('should handle warning log without trackerId', () => {
     const logger = createMockLogger()
     const http = createMockHTTP()

package/src/handle-error.ts

@@ -21,7 +21,8 @@ export const handleHTTPError = (
   logger: Logger,
   logWarningsForStatusCodes: number[],
   respondWith404: boolean,
-  bubbleError: boolean
+  bubbleError: boolean,
+  exposeErrors: boolean = false
 ) => {
   // Skip 404 handling if configured to do so
   if (e instanceof NotFoundError && !respondWith404) {
@@ -53,13 +54,16 @@ export const handleHTTPError = (
 
     if (trackerId) {
       logger.warn(`Error id: ${trackerId}`)
-      http?.response?.json({ errorId: trackerId })
+      const errorBody: Record<string, unknown> = { errorId: trackerId }
+      if (exposeErrors && e instanceof Error) {
+        errorBody.message = e.message
+        errorBody.stack = e.stack
+      }
+      http?.response?.json(errorBody)
     }
   }
 
   if (bubbleError) {
     throw e
   }
-
-  http?.response?.close?.()
 }

package/src/index.ts

@@ -47,6 +47,7 @@ export type {
   CorePikkuPermission,
   CorePikkuPermissionConfig,
   CorePikkuPermissionFactory,
+  CorePikkuApprovalDescription,
   CorePermissionGroup,
   ZodLike,
 } from './function/functions.types.js'
@@ -54,6 +55,7 @@ export {
   pikkuAuth,
   pikkuPermission,
   pikkuPermissionFactory,
+  pikkuApprovalDescription,
 } from './function/functions.types.js'
 export { addFunction, getAllFunctionNames } from './function/index.js'
 export { PikkuRequest } from './pikku-request.js'
@@ -86,6 +88,18 @@ export { NotFoundError } from './errors/errors.js'
 export type { EventHubService } from './wirings/channel/eventhub-service.js'
 export type { QueueService } from './wirings/queue/queue.types.js'
 export type { JWTService } from './services/jwt-service.js'
+export type { SecretService } from './services/secret-service.js'
+export type { VariablesService } from './services/variables-service.js'
+export type { ContentService } from './services/content-service.js'
+export type { DeploymentService } from './services/deployment-service.js'
+export type { WorkflowService } from './services/workflow-service.js'
+export type { GatewayService } from './services/gateway-service.js'
+export type { TriggerService } from './services/trigger-service.js'
+export type { SchemaService } from './services/schema-service.js'
+export type { SessionService } from './services/user-session-service.js'
+export type { AIAgentRunnerService } from './services/ai-agent-runner-service.js'
+export type { AIRunStateService } from './services/ai-run-state-service.js'
+export type { AIStorageService } from './services/ai-storage-service.js'
 export type { HTTPMethod } from './wirings/http/http.types.js'
 export type { GraphNodeConfig } from './wirings/workflow/graph/workflow-graph.types.js'
 export { createGraph } from './wirings/workflow/graph/graph-node.js'

package/src/middleware-runner.ts

@@ -121,6 +121,7 @@ const middlewareCache: Record<
   agent: {},
   cli: {},
   workflow: {},
+  gateway: {},
 }
 
 /**

package/src/permissions.ts

@@ -130,6 +130,7 @@ const combinedPermissionsCache: Record<
   agent: {},
   cli: {},
   workflow: {},
+  gateway: {},
 }
 
 /**

package/src/pikku-state.ts

@@ -10,6 +10,7 @@ import type {
   MCPPromptMeta,
 } from './wirings/mcp/mcp.types.js'
 import type { AIAgentMeta } from './wirings/ai-agent/ai-agent.types.js'
+import type { GatewaysMeta } from './wirings/gateway/gateway.types.js'
 import type { ScheduledTasksMeta } from './wirings/scheduler/scheduler.types.js'
 import type { TriggerMeta } from './wirings/trigger/trigger.types.js'
 
@@ -71,7 +72,9 @@ const createEmptyPackageState = (): PikkuPackageState => ({
   rpc: {
     meta: {},
     files: new Map(),
-    addons: new Map(),
+  },
+  addons: {
+    packages: new Map(),
   },
   http: {
     middleware: new Map(),
@@ -121,6 +124,10 @@ const createEmptyPackageState = (): PikkuPackageState => ({
     agents: new Map(),
     agentsMeta: {} as AIAgentMeta,
   },
+  gateway: {
+    gateways: new Map(),
+    meta: {} as GatewaysMeta,
+  },
   cli: {
     meta: { programs: {}, renderers: {} },
     programs: {},

package/src/schema.ts

@@ -146,6 +146,6 @@ export const validateSchema = async (
       )
     }
     await schemaService.compileSchema(key, schema)
-    await schemaService.validateSchema(key, data)
+    await schemaService.validateSchema(key, data ?? {})
   }
 }

package/src/services/gateway-service.ts

@@ -0,0 +1,20 @@
+/**
+ * Abstract GatewayService interface.
+ *
+ * Implementations manage listener gateway lifecycle — initializing adapters
+ * and delivering messages to handler functions.
+ *
+ * A `LocalGatewayService` starts all listeners unconditionally;
+ * a distributed implementation could check leader election first.
+ */
+export interface GatewayService {
+  /**
+   * Start all listener gateways
+   */
+  start(): Promise<void>
+
+  /**
+   * Stop all listener gateways
+   */
+  stop(): Promise<void>
+}

package/src/services/in-memory-workflow-service.ts

@@ -6,6 +6,7 @@ import type {
   WorkflowRunWire,
   StepState,
   WorkflowStatus,
+  WorkflowVersionStatus,
   WorkflowStepOptions,
 } from '../wirings/workflow/workflow.types.js'
 
@@ -40,7 +41,10 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
   >() // keyed by runId
   private runState = new Map<string, Record<string, unknown>>() // keyed by runId
   private branchKeys = new Map<string, string>() // keyed by stepId
-  private workflowVersions = new Map<string, { graph: any; source: string }>() // keyed by `${name}:${graphHash}`
+  private workflowVersions = new Map<
+    string,
+    { graph: any; source: string; status: WorkflowVersionStatus }
+  >() // keyed by `${name}:${graphHash}`
 
   async createRun(
     workflowName: string,
@@ -376,14 +380,28 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
     name: string,
     graphHash: string,
     graph: any,
-    source: string
+    source: string,
+    status?: WorkflowVersionStatus
   ): Promise<void> {
     this.workflowVersions.set(`${name}:${graphHash}`, {
       graph,
       source,
+      status: status ?? 'active',
     })
   }
 
+  async updateWorkflowVersionStatus(
+    name: string,
+    graphHash: string,
+    status: WorkflowVersionStatus
+  ): Promise<void> {
+    const key = `${name}:${graphHash}`
+    const version = this.workflowVersions.get(key)
+    if (version) {
+      version.status = status
+    }
+  }
+
   async getWorkflowVersion(
     name: string,
     graphHash: string
@@ -392,4 +410,29 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
     if (!version) return null
     return { graph: version.graph, source: version.source }
   }
+
+  async getAIGeneratedWorkflows(
+    agentName?: string
+  ): Promise<Array<{ workflowName: string; graphHash: string; graph: any }>> {
+    const results: Array<{
+      workflowName: string
+      graphHash: string
+      graph: any
+    }> = []
+    const prefix = agentName ? `ai:${agentName}:` : 'ai:'
+    for (const [key, value] of this.workflowVersions) {
+      if (value.source !== 'ai-agent' || value.status !== 'active') continue
+      const separatorIdx = key.lastIndexOf(':')
+      const wfName = key.substring(0, separatorIdx)
+      const hash = key.substring(separatorIdx + 1)
+      if (wfName.startsWith(prefix)) {
+        results.push({
+          workflowName: wfName,
+          graphHash: hash,
+          graph: value.graph,
+        })
+      }
+    }
+    return results
+  }
 }

package/src/services/index.ts

@@ -17,6 +17,7 @@ export { ConsoleLogger } from './logger-console.js'
 export { InMemoryWorkflowService } from './in-memory-workflow-service.js'
 export { InMemoryTriggerService } from './in-memory-trigger-service.js'
 export { InMemoryAIRunStateService } from './in-memory-ai-run-state-service.js'
+export { LocalGatewayService } from './local-gateway-service.js'
 export type { ContentService } from './content-service.js'
 export type { JWTService } from './jwt-service.js'
 export type { Logger } from './logger.js'
@@ -30,6 +31,7 @@ export type {
   SchedulerService,
 } from './scheduler-service.js'
 export type { TriggerService } from './trigger-service.js'
+export type { GatewayService } from './gateway-service.js'
 export type {
   DeploymentService,
   DeploymentConfig,

package/src/services/local-gateway-service.ts

@@ -0,0 +1,62 @@
+import type { GatewayService } from './gateway-service.js'
+import type { GatewayAdapter } from '../wirings/gateway/gateway.types.js'
+import { pikkuState, getSingletonServices } from '../pikku-state.js'
+import { createListenerMessageHandler } from '../wirings/gateway/gateway-runner.js'
+
+/**
+ * Local GatewayService implementation.
+ *
+ * Starts all registered listener gateways unconditionally (single-process).
+ * For distributed deployments, implement `GatewayService` with leader
+ * election or similar coordination.
+ *
+ * @example
+ * ```typescript
+ * const gatewayService = new LocalGatewayService()
+ * await gatewayService.start()
+ *
+ * // On shutdown
+ * await gatewayService.stop()
+ * ```
+ */
+export class LocalGatewayService implements GatewayService {
+  private activeAdapters = new Map<string, GatewayAdapter>()
+
+  async start(): Promise<void> {
+    const singletonServices = getSingletonServices()
+    const gateways = pikkuState(null, 'gateway', 'gateways')
+
+    for (const [name, config] of gateways) {
+      if (config.type !== 'listener') continue
+      if (this.activeAdapters.has(name)) continue
+
+      const handleMessage = createListenerMessageHandler(
+        name,
+        config,
+        singletonServices
+      )
+
+      await config.adapter.init(handleMessage)
+      this.activeAdapters.set(name, config.adapter)
+      singletonServices.logger.info(`Started listener gateway: ${name}`)
+    }
+  }
+
+  async stop(): Promise<void> {
+    for (const [name, adapter] of this.activeAdapters) {
+      try {
+        await adapter.close()
+      } catch (e: any) {
+        try {
+          getSingletonServices().logger.error(
+            `Error closing listener gateway '${name}':`,
+            e
+          )
+        } catch {
+          // logger may not be available during shutdown
+        }
+      }
+    }
+    this.activeAdapters.clear()
+  }
+}

package/src/services/workflow-service.ts

@@ -4,6 +4,7 @@ import type {
   WorkflowRunWire,
   StepState,
   WorkflowStatus,
+  WorkflowVersionStatus,
 } from '../wirings/workflow/workflow.types.js'
 
 /**
@@ -75,10 +76,20 @@ export interface WorkflowService {
     name: string,
     graphHash: string,
     graph: any,
-    source: string
+    source: string,
+    status?: WorkflowVersionStatus
+  ): Promise<void>
+  updateWorkflowVersionStatus(
+    name: string,
+    graphHash: string,
+    status: WorkflowVersionStatus
   ): Promise<void>
   getWorkflowVersion(
     name: string,
     graphHash: string
   ): Promise<{ graph: any; source: string } | null>
+
+  getAIGeneratedWorkflows(
+    agentName?: string
+  ): Promise<Array<{ workflowName: string; graphHash: string; graph: any }>>
 }

package/src/testing/index.ts

@@ -0,0 +1,2 @@
+export { defineServiceTests } from './service-tests.js'
+export type { ServiceTestConfig } from './service-tests.js'