@pikku/core 0.12.42 → 0.12.45

package/CHANGELOG.md

@@ -1,3 +1,42 @@
+## 0.12.45
+
+### Patch Changes
+
+- e9a778f: feat(config): add optional `postgres` pool config to `CoreConfig`
+
+  Postgres is a first-class adapter, so its runtime pool tuning now lives in the
+  core config (sibling to `workflow`), typed via the new `PostgresConfig`:
+  `maxPool`, `connectTimeout`, `idleTimeout`, `maxLifetime`, `statementTimeout`,
+  `prepare`. The connection string itself stays the flat `postgresUrl`/`sqliteDb`
+  field the CLI db commands read; this block is purely runtime pool options.
+
+## 0.12.44
+
+### Patch Changes
+
+- 41ce2cb: Upgrade to TypeScript 6 and raise the minimum Node.js version to 22.
+
+  All packages now build against `typescript@^6.0.3` and declare `engines.node >= 22`. Internal tooling (`ts-json-schema-generator`, `zod-to-ts`) was bumped to TypeScript 6-compatible releases.
+
+## 0.12.43
+
+### Patch Changes
+
+- a8022e5: fix(workflow): scope the step advisory lock to the claim, not execution
+
+  `executeWorkflowStep` held the step's advisory lock — and, in the Postgres
+  workflow service, the pooled DB connection backing it — across the entire step
+  body, including the step's own network and DB work. Under concurrency >= the DB
+  pool size this self-deadlocks: every running step pins a connection on its lock
+  transaction while its inner queries wait for a connection that never frees, so
+  nothing makes progress and the API hangs.
+
+  The lock is only needed to atomically _claim_ a step (read state + mark it
+  `running`); once a step is `running`, the existing status guard already prevents
+  any concurrent worker from re-running it. The lock now covers only the claim;
+  execution and result persistence run with the lock released and the connection
+  back in the pool.
+
 ## 0.12.42
 
 ### Patch Changes

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * @module @pikku/core
  */
-export type { CommonWireMeta, CoreConfig, CorePikkuMiddleware, CorePikkuMiddlewareConfig, CorePikkuMiddlewareFactory, CorePikkuMiddlewareGroup, CoreServices, CoreSingletonServices, CoreUserSession, CreateConfig, ServerLifecycle, FunctionMeta, FunctionRuntimeMeta, FunctionServicesMeta, FunctionWiresMeta, FunctionsMeta, FunctionsRuntimeMeta, JSONPrimitive, JSONValue, MakeRequired, MiddlewareMetadata, MiddlewarePriority, PermissionMetadata, PickOptional, PickRequired, PikkuAIMiddlewareHooks, PikkuWire, PikkuRawWire, PikkuWiringTypes, RequireAtLeastOne, SerializedError, WireServices, } from './types/core.types.js';
+export type { CommonWireMeta, CoreConfig, CorePikkuMiddleware, CorePikkuMiddlewareConfig, CorePikkuMiddlewareFactory, CorePikkuMiddlewareGroup, CoreServices, CoreSingletonServices, CoreUserSession, CreateConfig, ServerLifecycle, FunctionMeta, FunctionRuntimeMeta, FunctionServicesMeta, FunctionWiresMeta, FunctionsMeta, FunctionsRuntimeMeta, JSONPrimitive, JSONValue, MakeRequired, MiddlewareMetadata, MiddlewarePriority, PermissionMetadata, PickOptional, PickRequired, PikkuAIMiddlewareHooks, PikkuWire, PikkuRawWire, PikkuWiringTypes, PostgresConfig, 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, CorePikkuApprovalDescription, CorePermissionGroup, ZodLike, } from './function/functions.types.js';
 export { pikkuAuth, pikkuPermission, pikkuPermissionFactory, pikkuApprovalDescription, } from './function/functions.types.js';

package/dist/middleware/auth-apikey.d.ts

@@ -21,4 +21,5 @@ export declare const authAPIKey: import("../types/core.types.js").CorePikkuMiddl
     logLevel?: import("../services/logger.js").LogLevel;
     secrets?: {};
     workflow?: import("../wirings/workflow/workflow.types.js").WorkflowServiceConfig;
+    postgres?: import("../types/core.types.js").PostgresConfig;
 }>, import("../types/core.types.js").CoreUserSession>;

package/dist/middleware/auth-bearer.d.ts

@@ -37,4 +37,5 @@ export declare const authBearer: import("../types/core.types.js").CorePikkuMiddl
     logLevel?: import("../services/logger.js").LogLevel;
     secrets?: {};
     workflow?: import("../wirings/workflow/workflow.types.js").WorkflowServiceConfig;
+    postgres?: import("../types/core.types.js").PostgresConfig;
 }>, CoreUserSession>;

package/dist/middleware/auth-cookie.d.ts

@@ -36,4 +36,5 @@ export declare const authCookie: import("../types/core.types.js").CorePikkuMiddl
     logLevel?: import("../services/logger.js").LogLevel;
     secrets?: {};
     workflow?: import("../wirings/workflow/workflow.types.js").WorkflowServiceConfig;
+    postgres?: import("../types/core.types.js").PostgresConfig;
 }>, import("../types/core.types.js").CoreUserSession>;

package/dist/middleware/cors.d.ts

@@ -43,4 +43,5 @@ export declare const cors: import("../types/core.types.js").CorePikkuMiddlewareF
     logLevel?: import("../services/logger.js").LogLevel;
     secrets?: {};
     workflow?: import("../wirings/workflow/workflow.types.js").WorkflowServiceConfig;
+    postgres?: import("../types/core.types.js").PostgresConfig;
 }>, import("../types/core.types.js").CoreUserSession>;

package/dist/middleware/remote-auth.d.ts

@@ -2,4 +2,5 @@ export declare const pikkuRemoteAuthMiddleware: import("../types/core.types.js")
     logLevel?: import("../services/logger.js").LogLevel;
     secrets?: {};
     workflow?: import("../wirings/workflow/workflow.types.js").WorkflowServiceConfig;
+    postgres?: import("../types/core.types.js").PostgresConfig;
 }>, import("../types/core.types.js").CoreUserSession>;

package/dist/middleware/telemetry.d.ts

@@ -21,6 +21,7 @@ export declare const telemetryOuter: import("../types/core.types.js").CorePikkuM
     logLevel?: import("../services/logger.js").LogLevel;
     secrets?: {};
     workflow?: import("../wirings/workflow/workflow.types.js").WorkflowServiceConfig;
+    postgres?: import("../types/core.types.js").PostgresConfig;
 }>, import("../types/core.types.js").CoreUserSession>;
 /**
  * Inner telemetry middleware that captures function execution duration and user context.
@@ -44,4 +45,5 @@ export declare const telemetryInner: import("../types/core.types.js").CorePikkuM
     logLevel?: import("../services/logger.js").LogLevel;
     secrets?: {};
     workflow?: import("../wirings/workflow/workflow.types.js").WorkflowServiceConfig;
+    postgres?: import("../types/core.types.js").PostgresConfig;
 }>, import("../types/core.types.js").CoreUserSession>;

package/dist/middleware/timeout.d.ts

@@ -4,4 +4,5 @@ export declare const timeout: () => import("../types/core.types.js").CorePikkuMi
     logLevel?: import("../services/logger.js").LogLevel;
     secrets?: {};
     workflow?: import("../wirings/workflow/workflow.types.js").WorkflowServiceConfig;
+    postgres?: import("../types/core.types.js").PostgresConfig;
 }>, import("../types/core.types.js").CoreUserSession>;

package/dist/types/core.types.d.ts

@@ -137,6 +137,36 @@ export type PickOptional<T, K extends keyof T> = Partial<T> & Pick<T, K>;
 export type RequireAtLeastOne<T> = {
     [K in keyof T]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<keyof T, K>>>;
 }[keyof T];
+/**
+ * Runtime options for the Postgres adapter (@pikku/kysely-postgres).
+ * The connection string itself stays the flat `postgresUrl` config field (the
+ * contract the CLI's db commands read); this block is purely runtime pool
+ * tuning that the CLI never touches.
+ */
+export interface PostgresConfig {
+    /** Max connections in the postgres.js pool. Defaults to postgres.js's 10. */
+    maxPool?: number;
+    /** Seconds to wait establishing a new connection before failing. */
+    connectTimeout?: number;
+    /** Close a pooled connection after it has been idle this many seconds. */
+    idleTimeout?: number;
+    /**
+     * Recycle a connection after this many seconds. Guards against stale TCP
+     * connections silently dropped by load balancers / proxies.
+     */
+    maxLifetime?: number;
+    /**
+     * Server-side `statement_timeout` in milliseconds. A query running longer is
+     * cancelled, freeing its connection — defense against a runaway query pinning
+     * a pooled connection and exhausting the pool.
+     */
+    statementTimeout?: number;
+    /**
+     * Set `false` behind a transaction-mode connection pooler (pgBouncer,
+     * Supabase pooler) that cannot use prepared statements.
+     */
+    prepare?: boolean;
+}
 /**
  * Interface for the core configuration settings of Pikku.
  */
@@ -146,6 +176,8 @@ export type CoreConfig<Config extends Record<string, unknown> = {}> = {
     /** Secrets used by the application (optional). */
     secrets?: {};
     workflow?: WorkflowServiceConfig;
+    /** Runtime Postgres adapter options (pool sizing). */
+    postgres?: PostgresConfig;
 } & Config;
 /**
  * Represents a core user session, which can be extended for more specific session information.

package/dist/wirings/ai-agent/voice-input.d.ts

@@ -6,4 +6,5 @@ export declare const voiceInput: (config?: {
     logLevel?: import("../../services/logger.js").LogLevel;
     secrets?: {};
     workflow?: import("../workflow/workflow.types.js").WorkflowServiceConfig;
+    postgres?: import("../../types/core.types.js").PostgresConfig;
 }>>;

package/dist/wirings/ai-agent/voice-output.d.ts

@@ -12,5 +12,6 @@ export declare const voiceOutput: (config?: {
     logLevel?: import("../../services/logger.js").LogLevel;
     secrets?: {};
     workflow?: import("../workflow/workflow.types.js").WorkflowServiceConfig;
+    postgres?: import("../../types/core.types.js").PostgresConfig;
 }>>;
 export {};

package/dist/wirings/rpc/rpc-runner.d.ts

@@ -103,4 +103,5 @@ export declare const rpcService: PikkuRPCService<import("../../types/core.types.
     logLevel?: import("../../services/logger.js").LogLevel;
     secrets?: {};
     workflow?: import("../workflow/workflow.types.js").WorkflowServiceConfig;
+    postgres?: import("../../types/core.types.js").PostgresConfig;
 }>, PikkuRPC>;

package/dist/wirings/workflow/pikku-workflow-service.js

@@ -882,114 +882,120 @@ export class PikkuWorkflowService {
      * Handles idempotency, RPC execution, result storage, retry logic, and orchestrator triggering
      */
     async executeWorkflowStep(runId, stepName, rpcName, data, rpcService) {
-        // Use step-level lock to prevent concurrent execution of same step
-        await this.withStepLock(runId, stepName, async () => {
-            // Get step state
-            let stepState = await this.getStepState(runId, stepName);
-            // Idempotency - if already succeeded, nothing to do
-            if (stepState.status === 'succeeded') {
-                return;
-            }
-            // Log warning if already running (race condition)
-            if (stepState.status === 'running') {
-                return;
+        // Claim the step under the lock ONLY (atomic check-and-mark-running). Do NOT
+        // hold the advisory lock — and its pooled connection — across execution: once
+        // a step is 'running' the guard below makes any concurrent worker return
+        // early, so the work + result persistence run with the lock released. Holding
+        // the lock across executeGraphStep (network I/O + more pool queries) let
+        // concurrent steps exhaust the connection pool and self-deadlock.
+        const claimed = await this.withStepLock(runId, stepName, async () => {
+            const stepState = await this.getStepState(runId, stepName);
+            // Already succeeded, or already claimed by another worker — nothing to do.
+            if (stepState.status === 'succeeded' || stepState.status === 'running') {
+                return null;
             }
-            // If status is 'failed', this is a retry - create new attempt history
+            // A 'failed' status means this is a retry — start a fresh 'running' attempt.
             if (stepState.status === 'failed') {
-                stepState = await this.createRetryAttempt(stepState.stepId, 'running');
+                return this.createRetryAttempt(stepState.stepId, 'running');
             }
             if (stepState.status === 'pending' || stepState.status === 'scheduled') {
                 await this.setStepRunning(stepState.stepId);
             }
-            try {
-                let result;
-                const run = await this.getRun(runId);
-                if (!run) {
-                    throw new Error(`Workflow run not found: ${runId}`);
-                }
-                const meta = pikkuState(null, 'workflows', 'meta');
-                const workflowMeta = meta[run.workflow];
-                const isGraphWorkflow = workflowMeta?.source === 'graph' ||
-                    workflowMeta?.source === 'dynamic-workflow';
-                // Map the physical step key back to its logical node: a revisit instance
-                // is `node#N` (ordinal), which isn't a literal key in `nodes`.
-                let graphNodeId;
-                if (isGraphWorkflow && workflowMeta?.nodes) {
-                    if (stepName in workflowMeta.nodes) {
-                        graphNodeId = stepName;
-                    }
-                    else {
-                        const hash = stepName.lastIndexOf('#');
-                        const base = hash > 0 ? stepName.slice(0, hash) : undefined;
-                        if (base && base in workflowMeta.nodes)
-                            graphNodeId = base;
-                    }
-                }
-                if (graphNodeId) {
-                    result = await executeGraphStep(this, rpcService, runId, stepState.stepId, graphNodeId, rpcName, data, run.workflow);
+            return stepState;
+        });
+        // Nothing to execute: already succeeded, or another worker owns this step.
+        if (!claimed) {
+            return;
+        }
+        const stepState = claimed;
+        try {
+            let result;
+            const run = await this.getRun(runId);
+            if (!run) {
+                throw new Error(`Workflow run not found: ${runId}`);
+            }
+            const meta = pikkuState(null, 'workflows', 'meta');
+            const workflowMeta = meta[run.workflow];
+            const isGraphWorkflow = workflowMeta?.source === 'graph' ||
+                workflowMeta?.source === 'dynamic-workflow';
+            // Map the physical step key back to its logical node: a revisit instance
+            // is `node#N` (ordinal), which isn't a literal key in `nodes`.
+            let graphNodeId;
+            if (isGraphWorkflow && workflowMeta?.nodes) {
+                if (stepName in workflowMeta.nodes) {
+                    graphNodeId = stepName;
                 }
                 else {
-                    // Check if rpcName refers to a sub-workflow
-                    const subWorkflowMeta = meta[rpcName];
-                    if (subWorkflowMeta) {
-                        const childWire = {
-                            type: 'workflow',
-                            id: rpcName,
-                            parentRunId: runId,
-                            parentStepId: stepState.stepId,
-                            pikkuUserId: rpcService.wire?.pikkuUserId,
-                        };
-                        const shouldInline = !getSingletonServices()?.queueService;
-                        const { runId: childRunId } = await this.startWorkflow(rpcName, data, childWire, rpcService, { inline: shouldInline });
-                        await this.setStepChildRunId(stepState.stepId, childRunId);
-                        if (shouldInline) {
-                            const childRun = await this.getRun(childRunId);
-                            if (childRun?.status === 'failed') {
-                                throw new Error(childRun.error?.message || 'Sub-workflow failed');
-                            }
-                            if (childRun?.status === 'cancelled') {
-                                throw new Error('Sub-workflow was cancelled');
-                            }
-                            result = childRun?.output;
+                    const hash = stepName.lastIndexOf('#');
+                    const base = hash > 0 ? stepName.slice(0, hash) : undefined;
+                    if (base && base in workflowMeta.nodes)
+                        graphNodeId = base;
+                }
+            }
+            if (graphNodeId) {
+                result = await executeGraphStep(this, rpcService, runId, stepState.stepId, graphNodeId, rpcName, data, run.workflow);
+            }
+            else {
+                // Check if rpcName refers to a sub-workflow
+                const subWorkflowMeta = meta[rpcName];
+                if (subWorkflowMeta) {
+                    const childWire = {
+                        type: 'workflow',
+                        id: rpcName,
+                        parentRunId: runId,
+                        parentStepId: stepState.stepId,
+                        pikkuUserId: rpcService.wire?.pikkuUserId,
+                    };
+                    const shouldInline = !getSingletonServices()?.queueService;
+                    const { runId: childRunId } = await this.startWorkflow(rpcName, data, childWire, rpcService, { inline: shouldInline });
+                    await this.setStepChildRunId(stepState.stepId, childRunId);
+                    if (shouldInline) {
+                        const childRun = await this.getRun(childRunId);
+                        if (childRun?.status === 'failed') {
+                            throw new Error(childRun.error?.message || 'Sub-workflow failed');
                         }
-                        else {
-                            throw new ChildWorkflowStartedException(runId, stepState.stepId, childRunId);
+                        if (childRun?.status === 'cancelled') {
+                            throw new Error('Sub-workflow was cancelled');
                         }
+                        result = childRun?.output;
                     }
                     else {
-                        result = await this.invokeStepRpc(runId, stepName, stepState, rpcName, data, rpcService);
+                        throw new ChildWorkflowStartedException(runId, stepState.stepId, childRunId);
                     }
                 }
-                // Store result and mark succeeded
-                await this.setStepResult(stepState.stepId, result);
-                // Resume orchestrator to continue workflow
-                await this.resumeWorkflow(runId);
-            }
-            catch (error) {
-                if (error instanceof ChildWorkflowStartedException) {
-                    this.logger?.debug(`Workflow step '${stepName}': child workflow ${error.childRunId} started, waiting for completion`);
-                    return;
-                }
-                if (error instanceof RPCNotFoundError) {
-                    await this.setStepError(stepState.stepId, error);
-                    await this.updateRunStatus(runId, 'suspended', undefined, {
-                        message: `RPC '${rpcName}' not found. Deploy the missing function and resume.`,
-                        code: 'RPC_NOT_FOUND',
-                    });
-                    return;
+                else {
+                    result = await this.invokeStepRpc(runId, stepName, stepState, rpcName, data, rpcService);
                 }
-                // Store error and mark failed
+            }
+            // Store result and mark succeeded
+            await this.setStepResult(stepState.stepId, result);
+            // Resume orchestrator to continue workflow
+            await this.resumeWorkflow(runId);
+        }
+        catch (error) {
+            if (error instanceof ChildWorkflowStartedException) {
+                this.logger?.debug(`Workflow step '${stepName}': child workflow ${error.childRunId} started, waiting for completion`);
+                return;
+            }
+            if (error instanceof RPCNotFoundError) {
                 await this.setStepError(stepState.stepId, error);
-                const maxAttempts = (stepState.retries ?? DEFAULT_STEP_RETRIES) + 1;
-                const retriesExhausted = stepState.attemptCount >= maxAttempts;
-                if (retriesExhausted) {
-                    // No more retries - resume orchestrator to mark workflow as failed
-                    await this.resumeWorkflow(runId);
-                }
-                // Always throw so queue knows the job failed and can retry if needed
-                throw error;
+                await this.updateRunStatus(runId, 'suspended', undefined, {
+                    message: `RPC '${rpcName}' not found. Deploy the missing function and resume.`,
+                    code: 'RPC_NOT_FOUND',
+                });
+                return;
             }
-        });
+            // Store error and mark failed
+            await this.setStepError(stepState.stepId, error);
+            const maxAttempts = (stepState.retries ?? DEFAULT_STEP_RETRIES) + 1;
+            const retriesExhausted = stepState.attemptCount >= maxAttempts;
+            if (retriesExhausted) {
+                // No more retries - resume orchestrator to mark workflow as failed
+                await this.resumeWorkflow(runId);
+            }
+            // Always throw so queue knows the job failed and can retry if needed
+            throw error;
+        }
     }
     /**
      * Orchestrate workflow execution (called by orchestrator)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.42",
+  "version": "0.12.45",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",
@@ -63,9 +63,9 @@
   "devDependencies": {
     "@types/node": "^24.11.0",
     "tsx": "^4.21.0",
-    "typescript": "^5.9"
+    "typescript": "^6.0.3"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   }
 }

package/src/index.ts

@@ -31,6 +31,7 @@ export type {
   PikkuWire,
   PikkuRawWire,
   PikkuWiringTypes,
+  PostgresConfig,
   RequireAtLeastOne,
   SerializedError,
   WireServices,

package/src/types/core.types.ts

@@ -192,6 +192,37 @@ export type RequireAtLeastOne<T> = {
   [K in keyof T]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<keyof T, K>>>
 }[keyof T]
 
+/**
+ * Runtime options for the Postgres adapter (@pikku/kysely-postgres).
+ * The connection string itself stays the flat `postgresUrl` config field (the
+ * contract the CLI's db commands read); this block is purely runtime pool
+ * tuning that the CLI never touches.
+ */
+export interface PostgresConfig {
+  /** Max connections in the postgres.js pool. Defaults to postgres.js's 10. */
+  maxPool?: number
+  /** Seconds to wait establishing a new connection before failing. */
+  connectTimeout?: number
+  /** Close a pooled connection after it has been idle this many seconds. */
+  idleTimeout?: number
+  /**
+   * Recycle a connection after this many seconds. Guards against stale TCP
+   * connections silently dropped by load balancers / proxies.
+   */
+  maxLifetime?: number
+  /**
+   * Server-side `statement_timeout` in milliseconds. A query running longer is
+   * cancelled, freeing its connection — defense against a runaway query pinning
+   * a pooled connection and exhausting the pool.
+   */
+  statementTimeout?: number
+  /**
+   * Set `false` behind a transaction-mode connection pooler (pgBouncer,
+   * Supabase pooler) that cannot use prepared statements.
+   */
+  prepare?: boolean
+}
+
 /**
  * Interface for the core configuration settings of Pikku.
  */
@@ -202,6 +233,8 @@ export type CoreConfig<Config extends Record<string, unknown> = {}> = {
   secrets?: {}
 
   workflow?: WorkflowServiceConfig
+  /** Runtime Postgres adapter options (pool sizing). */
+  postgres?: PostgresConfig
 } & Config
 
 /**