@pikku/core 0.12.2 → 0.12.3

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 ## 0.12.0
 
+## 0.12.3
+
+### Patch Changes
+
+- 387b2ee: Add approval descriptions, rename requiresApproval to approvalRequired, export all service interfaces, add exposeErrors option to HTTP runner, promote addons to top-level state, add packageName to CommonWireMeta, add errors to function config, and improve agent runner streaming
+- 32ed003: Add envelope encryption utilities and database-backed secret services with KEK rotation support
+- 7d369f3: Fix agent sub-agent tool execution failures: use UUID for sub-agent thread IDs (was exceeding varchar(36) DB column), and synthesize error results for failed tool calls in non-streaming run() to prevent "Tool result is missing" cascading errors.
+- 508a796: Fix MCP server not exposing addon tools: resolve namespaced function IDs in MCP runner, load addon schemas after schema generation, and use resolveFunctionMeta for MCP JSON serialization
+- ffe83af: Add Web Response passthrough support and fix close() flushing
+
+  - HTTP runner detects when a function returns a Web `Response` object and applies it directly via `applyWebResponse()`, enabling seamless integration with libraries like Auth.js
+  - Add `send()` method to `PikkuHTTPResponse` for setting body without Content-Type headers
+  - Add `headers()` method to `PikkuHTTPRequest` for retrieving all headers as a record
+  - Add `toWebRequest()` and `applyWebResponse()` utilities for Web Request/Response conversion
+  - Fix `close()` in Express, Fastify, and UWS responses to flush buffered status/headers/body before ending the connection
+
+- c7ff141: Add WorkflowVersionStatus type with draft→active lifecycle for AI-generated workflows, type all DB status fields with proper unions instead of plain strings
+
 ## 0.12.2
 
 ### Patch Changes

package/dist/crypto-utils.d.ts

@@ -1,2 +1,12 @@
 export declare const encryptJSON: (secret: string, value: unknown) => Promise<string>;
 export declare const decryptJSON: <T>(secret: string, token: string) => Promise<T>;
+export declare const generateDEK: () => Promise<string>;
+export declare const wrapDEK: (kek: string, plaintextDEK: string) => Promise<string>;
+export declare const unwrapDEK: (kek: string, wrappedDEK: string) => Promise<string>;
+export interface EnvelopeEncryptResult {
+    ciphertext: string;
+    wrappedDEK: string;
+}
+export declare const envelopeEncrypt: (kek: string, value: unknown) => Promise<EnvelopeEncryptResult>;
+export declare const envelopeDecrypt: <T>(kek: string, ciphertext: string, wrappedDEK: string) => Promise<T>;
+export declare const envelopeRewrap: (oldKEK: string, newKEK: string, wrappedDEK: string) => Promise<string>;

package/dist/crypto-utils.js

@@ -76,3 +76,65 @@ export const decryptJSON = async (secret, token) => {
     const decrypted = await subtle.decrypt({ name: 'AES-GCM', iv }, key, ciphertext);
     return JSON.parse(decoder.decode(new Uint8Array(decrypted)));
 };
+/**
+ * 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) => {
+    const subtle = getSubtle();
+    return subtle.importKey('raw', rawBytes.buffer, { name: 'AES-GCM' }, true, ['encrypt', 'decrypt']);
+};
+export const generateDEK = async () => {
+    const raw = globalThis.crypto.getRandomValues(new Uint8Array(32));
+    return toBase64Url(raw);
+};
+export const wrapDEK = async (kek, plaintextDEK) => {
+    return encryptJSON(kek, plaintextDEK);
+};
+export const unwrapDEK = async (kek, wrappedDEK) => {
+    return decryptJSON(kek, wrappedDEK);
+};
+const encryptWithDEK = async (dekBase64, value) => {
+    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 (dekBase64, token) => {
+    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)));
+};
+export const envelopeEncrypt = async (kek, value) => {
+    const dek = await generateDEK();
+    const ciphertext = await encryptWithDEK(dek, value);
+    const wrappedDEK = await wrapDEK(kek, dek);
+    return { ciphertext, wrappedDEK };
+};
+export const envelopeDecrypt = async (kek, ciphertext, wrappedDEK) => {
+    const dek = await unwrapDEK(kek, wrappedDEK);
+    return decryptWithDEK(dek, ciphertext);
+};
+export const envelopeRewrap = async (oldKEK, newKEK, wrappedDEK) => {
+    const dek = await unwrapDEK(oldKEK, wrappedDEK);
+    return wrapDEK(newKEK, dek);
+};

package/dist/function/function-runner.js

@@ -50,7 +50,7 @@ export const getAllFunctionNames = () => {
     const functions = [];
     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)) {
@@ -166,12 +166,12 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
         // Validate and coerce data if schema is defined
         const inputSchemaName = funcMeta.inputSchemaName;
         if (inputSchemaName) {
-            // Validate request data against the defined schema, if any
-            await validateSchema(resolvedSingletonServices.logger, resolvedSingletonServices.schema, inputSchemaName, actualData, packageName);
-            // Coerce (top level) query string parameters or date objects if specified by the schema
+            // 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, resolvedSingletonServices.schema, inputSchemaName, actualData, packageName);
         }
         if (mergedInheritedPermissions.length > 0 ||
             wirePermissions ||

package/dist/function/functions.types.d.ts

@@ -1,5 +1,6 @@
 import type { CoreServices, CoreSingletonServices, CoreUserSession, CorePikkuMiddleware, PikkuWire, 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';
 /**
  * @deprecated Use StandardSchemaV1 from @standard-schema/spec instead.
@@ -103,6 +104,28 @@ export type CorePikkuPermissionFactory<In = any, Services extends CoreSingletonS
  * ```
  */
 export declare const pikkuPermissionFactory: <In = any>(factory: CorePikkuPermissionFactory<In>) => CorePikkuPermissionFactory<In>;
+/**
+ * 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 declare const pikkuApprovalDescription: <In = any, Services extends CoreSingletonServices = CoreSingletonServices>(fn: CorePikkuApprovalDescription<In, Services>) => CorePikkuApprovalDescription<In, Services>;
 export type CorePikkuAuth<Services extends CoreSingletonServices = CoreServices, Session extends CoreUserSession = CoreUserSession> = (services: Services, session: Session) => Promise<boolean> | boolean;
 export type CorePikkuAuthConfig<Services extends CoreSingletonServices = CoreServices, Session extends CoreUserSession = CoreUserSession> = {
     func: CorePikkuAuth<Services, Session>;
@@ -123,7 +146,8 @@ export type CorePikkuFunctionConfig<PikkuFunction extends CorePikkuFunction<any,
     remote?: boolean;
     mcp?: boolean;
     readonly?: boolean;
-    requiresApproval?: boolean;
+    approvalRequired?: boolean;
+    approvalDescription?: any;
     func: PikkuFunction;
     auth?: boolean;
     permissions?: CorePermissionGroup<PikkuPermission>;
@@ -131,4 +155,5 @@ export type CorePikkuFunctionConfig<PikkuFunction extends CorePikkuFunction<any,
     input?: InputSchema;
     output?: OutputSchema;
     node?: CoreNodeConfig;
+    errors?: Array<typeof PikkuError>;
 };

package/dist/function/functions.types.js

@@ -49,6 +49,22 @@ export const pikkuPermission = (permission) => {
 export const pikkuPermissionFactory = (factory) => {
     return factory;
 };
+/**
+ * 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 = (fn) => {
+    return fn;
+};
 export const pikkuAuth = (auth) => {
     const fn = typeof auth === 'function' ? auth : auth.func;
     const wrapper = async (services, _data, wire) => {

package/dist/handle-error.d.ts

@@ -11,4 +11,4 @@ import type { PikkuHTTP } from './wirings/http/http.types.js';
  * @param {boolean} respondWith404 - Whether to respond with 404 for NotFoundError
  * @param {boolean} bubbleError - Whether to throw the error after handling
  */
-export declare const handleHTTPError: (e: any, http: PikkuHTTP | undefined, trackerId: string | undefined, logger: Logger, logWarningsForStatusCodes: number[], respondWith404: boolean, bubbleError: boolean) => void;
+export declare const handleHTTPError: (e: any, http: PikkuHTTP | undefined, trackerId: string | undefined, logger: Logger, logWarningsForStatusCodes: number[], respondWith404: boolean, bubbleError: boolean, exposeErrors?: boolean) => void;

package/dist/handle-error.js

@@ -11,7 +11,7 @@ import { NotFoundError } from './errors/errors.js';
  * @param {boolean} respondWith404 - Whether to respond with 404 for NotFoundError
  * @param {boolean} bubbleError - Whether to throw the error after handling
  */
-export const handleHTTPError = (e, http, trackerId, logger, logWarningsForStatusCodes, respondWith404, bubbleError) => {
+export const handleHTTPError = (e, http, trackerId, logger, logWarningsForStatusCodes, respondWith404, bubbleError, exposeErrors = false) => {
     // Skip 404 handling if configured to do so
     if (e instanceof NotFoundError && !respondWith404) {
         return;
@@ -40,11 +40,15 @@ export const handleHTTPError = (e, http, trackerId, logger, logWarningsForStatus
         http?.response?.status(500);
         if (trackerId) {
             logger.warn(`Error id: ${trackerId}`);
-            http?.response?.json({ errorId: trackerId });
+            const errorBody = { 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/dist/index.d.ts

@@ -3,8 +3,8 @@
  */
 export type { CommonWireMeta, CoreConfig, CorePikkuMiddleware, CorePikkuMiddlewareConfig, CorePikkuMiddlewareFactory, CorePikkuMiddlewareGroup, CoreServices, CoreSingletonServices, CoreUserSession, CreateConfig, FunctionMeta, FunctionRuntimeMeta, FunctionServicesMeta, FunctionWiresMeta, FunctionsMeta, FunctionsRuntimeMeta, JSONPrimitive, JSONValue, MakeRequired, MiddlewareMetadata, PermissionMetadata, PickOptional, PickRequired, PikkuAIMiddlewareHooks, PikkuWire, PikkuWiringTypes, RequireAtLeastOne, SerializedError, WireServices, } from './types/core.types.js';
 export { pikkuAIMiddleware, pikkuChannelMiddleware, pikkuChannelMiddlewareFactory, pikkuMiddleware, pikkuMiddlewareFactory, } from './types/core.types.js';
-export type { CorePikkuAuth, CorePikkuAuthConfig, CorePikkuFunction, CorePikkuFunctionConfig, CorePikkuPermission, CorePikkuPermissionConfig, CorePikkuPermissionFactory, CorePermissionGroup, ZodLike, } from './function/functions.types.js';
-export { pikkuAuth, pikkuPermission, pikkuPermissionFactory, } from './function/functions.types.js';
+export type { CorePikkuAuth, CorePikkuAuthConfig, CorePikkuFunction, CorePikkuFunctionConfig, CorePikkuPermission, CorePikkuPermissionConfig, CorePikkuPermissionFactory, CorePikkuApprovalDescription, CorePermissionGroup, ZodLike, } from './function/functions.types.js';
+export { pikkuAuth, pikkuPermission, pikkuPermissionFactory, pikkuApprovalDescription, } from './function/functions.types.js';
 export { addFunction, getAllFunctionNames } from './function/index.js';
 export { PikkuRequest } from './pikku-request.js';
 export { getRelativeTimeOffsetFromNow, parseDurationString, } from './time-utils.js';
@@ -21,6 +21,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/dist/index.js

@@ -1,5 +1,5 @@
 export { pikkuAIMiddleware, pikkuChannelMiddleware, pikkuChannelMiddlewareFactory, pikkuMiddleware, pikkuMiddlewareFactory, } from './types/core.types.js';
-export { pikkuAuth, pikkuPermission, pikkuPermissionFactory, } from './function/functions.types.js';
+export { pikkuAuth, pikkuPermission, pikkuPermissionFactory, pikkuApprovalDescription, } from './function/functions.types.js';
 export { addFunction, getAllFunctionNames } from './function/index.js';
 export { PikkuRequest } from './pikku-request.js';
 export { getRelativeTimeOffsetFromNow, parseDurationString, } from './time-utils.js';

package/dist/pikku-state.js

@@ -42,7 +42,9 @@ const createEmptyPackageState = () => ({
     rpc: {
         meta: {},
         files: new Map(),
-        addons: new Map(),
+    },
+    addons: {
+        packages: new Map(),
     },
     http: {
         middleware: new Map(),

package/dist/schema.js

@@ -104,6 +104,6 @@ export const validateSchema = async (logger, schemaService, schemaName, data, pa
             throw new MissingSchemaError(`Schema '${schemaName}' not found. Ensure schema generation has been run.`);
         }
         await schemaService.compileSchema(key, schema);
-        await schemaService.validateSchema(key, data);
+        await schemaService.validateSchema(key, data ?? {});
     }
 };

package/dist/services/in-memory-workflow-service.d.ts

@@ -1,6 +1,6 @@
 import { PikkuWorkflowService } from '../wirings/workflow/pikku-workflow-service.js';
 import type { SerializedError } from '../types/core.types.js';
-import type { WorkflowRun, WorkflowRunWire, StepState, WorkflowStatus, WorkflowStepOptions } from '../wirings/workflow/workflow.types.js';
+import type { WorkflowRun, WorkflowRunWire, StepState, WorkflowStatus, WorkflowVersionStatus, WorkflowStepOptions } from '../wirings/workflow/workflow.types.js';
 /**
  * In-memory implementation of WorkflowService for inline-only execution
  *
@@ -51,9 +51,15 @@ export declare class InMemoryWorkflowService extends PikkuWorkflowService {
     setBranchTaken(stepId: string, branchKey: string): Promise<void>;
     updateRunState(runId: string, name: string, value: unknown): Promise<void>;
     getRunState(runId: string): Promise<Record<string, unknown>>;
-    upsertWorkflowVersion(name: string, graphHash: string, graph: any, source: string): Promise<void>;
+    upsertWorkflowVersion(name: string, graphHash: string, graph: any, 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/dist/services/in-memory-workflow-service.js

@@ -272,16 +272,43 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
     async getRunState(runId) {
         return this.runState.get(runId) || {};
     }
-    async upsertWorkflowVersion(name, graphHash, graph, source) {
+    async upsertWorkflowVersion(name, graphHash, graph, source, status) {
         this.workflowVersions.set(`${name}:${graphHash}`, {
             graph,
             source,
+            status: status ?? 'active',
         });
     }
+    async updateWorkflowVersionStatus(name, graphHash, status) {
+        const key = `${name}:${graphHash}`;
+        const version = this.workflowVersions.get(key);
+        if (version) {
+            version.status = status;
+        }
+    }
     async getWorkflowVersion(name, graphHash) {
         const version = this.workflowVersions.get(`${name}:${graphHash}`);
         if (!version)
             return null;
         return { graph: version.graph, source: version.source };
     }
+    async getAIGeneratedWorkflows(agentName) {
+        const results = [];
+        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/dist/services/workflow-service.d.ts

@@ -1,5 +1,5 @@
 import type { SerializedError } from '../types/core.types.js';
-import type { WorkflowRun, WorkflowRunWire, StepState, WorkflowStatus } from '../wirings/workflow/workflow.types.js';
+import type { WorkflowRun, WorkflowRunWire, StepState, WorkflowStatus, WorkflowVersionStatus } from '../wirings/workflow/workflow.types.js';
 /**
  * Interface for workflow orchestration
  * Handles workflow execution, replay, orchestration logic, and run-level state
@@ -34,9 +34,15 @@ export interface WorkflowService {
     setStepError(stepId: string, error: Error): Promise<void>;
     createRetryAttempt(stepId: string, status: 'pending' | 'running'): Promise<StepState>;
     executeWorkflowStep(runId: string, stepName: string, rpcName: string | null, data: any, rpcService: any): Promise<void>;
-    upsertWorkflowVersion(name: string, graphHash: string, graph: any, source: string): Promise<void>;
+    upsertWorkflowVersion(name: string, graphHash: string, graph: any, 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/dist/testing/index.d.ts

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

package/dist/testing/index.js

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

package/dist/testing/service-tests.d.ts

@@ -0,0 +1,31 @@
+import type { ChannelStore } from '../wirings/channel/channel-store.js';
+import type { EventHubStore } from '../wirings/channel/eventhub-store.js';
+import type { PikkuWorkflowService } from '../wirings/workflow/pikku-workflow-service.js';
+import type { WorkflowRunService } from '../wirings/workflow/workflow.types.js';
+import type { DeploymentService } from '../services/deployment-service.js';
+import type { AIStorageService } from '../services/ai-storage-service.js';
+import type { AIRunStateService } from '../services/ai-run-state-service.js';
+import type { SecretService } from '../services/secret-service.js';
+import type { AgentRunService } from '../wirings/ai-agent/ai-agent.types.js';
+export interface ServiceTestConfig {
+    name: string;
+    services: {
+        channelStore?: () => Promise<ChannelStore>;
+        eventHubStore?: () => Promise<EventHubStore<Record<string, any>>>;
+        workflowService?: () => Promise<PikkuWorkflowService>;
+        workflowRunService?: () => Promise<WorkflowRunService>;
+        deploymentService?: () => Promise<DeploymentService & {
+            stop(): Promise<void>;
+        }>;
+        aiStorageService?: () => Promise<AIStorageService & AIRunStateService>;
+        agentRunService?: () => Promise<AgentRunService>;
+        secretService?: (config: {
+            key: string;
+            keyVersion?: number;
+            previousKey?: string;
+        }) => Promise<SecretService & {
+            rotateKEK?(): Promise<number>;
+        }>;
+    };
+}
+export declare function defineServiceTests(config: ServiceTestConfig): void;