@pikku/core 0.12.67 → 0.12.69

package/CHANGELOG.md

@@ -1,3 +1,66 @@
+## 0.12.69
+
+### Patch Changes
+
+- 24252b8: Emit queue meta for workflow-only projects, so per-workflow orchestrator queues actually work.
+
+  Workflows synthesise their own `wf-orchestrator-*` / `wf-step-*` queue meta during
+  post-processing, and those entries have no declaring source file. The queue codegen
+  bailed early on `queueWorkers.files.size === 0`, so a project that uses workflows but
+  hand-declares no `wireQueueWorker` wrote no queue meta at all — and the generated
+  bootstrap therefore never imported it.
+
+  With `queue.meta` empty at runtime, `getOrchestratorQueueName()` never found a
+  per-workflow queue and every workflow silently fell back to the single shared
+  `pikku-workflow-orchestrator` queue. Nothing failed, but the isolation was gone: one
+  long-running workflow step head-of-line-blocked every other workflow queued behind it.
+
+  The codegen now gates on the meta alone. `@pikku/core` additionally warns at wiring
+  time when workflows are registered but no per-workflow orchestrator queue is present,
+  so this degradation can't recur silently.
+
+- e3d4454: Add job groups, so one shared queue can stay fair without splitting into one
+  queue per producer.
+
+  A job may now carry `group: { id, tier }`, and a worker may cap how many jobs
+  of any one group run at once via `groupConcurrency`. On pg-boss this maps to
+  `localGroupConcurrency`, which excludes at-capacity groups from the fetch query
+  itself, so a capped group costs nothing rather than being fetched and restored.
+  BullMQ declares it unsupported (groups are a BullMQ Pro feature) — being
+  push-based, it can simply use a queue per group at no polling cost.
+
+  Workflow services accept a `queueStrategy`. The default `'per-workflow'` is
+  unchanged: every workflow gets its own `wf-orchestrator-*` / `wf-step-*` queue,
+  which is also what lets serverless providers deploy one unit per workflow. The
+  new `'shared-groups'` routes every workflow through the shared
+  orchestrator/step-worker queues and isolates them by group instead, so a
+  monolith runs one set of pollers rather than one per workflow — on a
+  pull-based backend with dozens of workflows that is the difference between
+  hundreds of poll loops and twenty. It is for single-process runtimes only; a
+  per-unit serverless deploy still needs the per-workflow queues to route to its
+  units.
+
+## 0.12.68
+
+### Patch Changes
+
+- f11675f: Forward the parent run's `context` into delegated sub-agent invocations.
+
+  A supervisor agent's injected `context` (the "Current context" block holding the
+  authoritative identifiers — organizationId, project/stage ids) was appended only
+  to the supervisor's own instructions. When it delegated, the sub-agent tool's
+  input schema carries just `{ message, session }`, and `buildToolDefs` invoked the
+  sub-agent with `{ message, threadId, resourceId }` — dropping the context. The
+  sub-agent therefore never saw the real ids and depended on the model re-typing
+  them into the free-text `message`, which weaker models routinely botch, producing
+  schema-validation and permission rejections that the agent then retries — burning
+  steps and ballooning the transcript.
+
+  `buildToolDefs` now takes the parent `context` and forwards it (via the new
+  `buildSubAgentRunInput` helper) into both the streaming and non-streaming
+  sub-agent invocations, so a specialist inherits the same identifier block in its
+  instructions.
+
 ## 0.12.67
 
 ### Patch Changes

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 { WorkflowPlannedStep, WorkflowRun, WorkflowRunService, WorkflowRunWire, StepState, StepStatus, WorkflowStatus, WorkflowVersionStatus, WorkflowStepOptions } from '../wirings/workflow/workflow.types.js';
+import type { WorkflowPlannedStep, WorkflowQueueOptions, WorkflowRun, WorkflowRunService, WorkflowRunWire, StepState, StepStatus, WorkflowStatus, WorkflowVersionStatus, WorkflowStepOptions } from '../wirings/workflow/workflow.types.js';
 /**
  * In-memory implementation of WorkflowService for inline-only execution
  *
@@ -17,7 +17,7 @@ import type { WorkflowPlannedStep, WorkflowRun, WorkflowRunService, WorkflowRunW
  * ```
  */
 export declare class InMemoryWorkflowService extends PikkuWorkflowService implements WorkflowRunService {
-    constructor();
+    constructor(options?: WorkflowQueueOptions);
     private sleepTimers;
     private runs;
     private steps;

package/dist/services/in-memory-workflow-service.js

@@ -17,8 +17,8 @@ import { isExpectedError } from '../errors/error-handler.js';
  * ```
  */
 export class InMemoryWorkflowService extends PikkuWorkflowService {
-    constructor() {
-        super({ wireQueues: false });
+    constructor(options = {}) {
+        super({ ...options, wireQueues: false });
     }
     sleepTimers = new Set();
     runs = new Map();

package/dist/wirings/ai-agent/ai-agent-prepare.d.ts

@@ -168,7 +168,24 @@ export type ScopedChannel = AIStreamChannel & {
     }>;
 };
 export declare function createScopedChannel(parent: AIStreamChannel, agentName: string, session: string): ScopedChannel;
-export declare function buildToolDefs(params: RunAIAgentParams, agentSessionMap: Map<string, string>, resourceId: string, agentName: string, packageName: string | null, streamContext?: StreamContext, aiMiddlewares?: PikkuAIMiddlewareHooks[], agentMode?: 'delegate' | 'supervise'): Promise<{
+/**
+ * Build the run input for a delegated sub-agent.
+ *
+ * `context` is the PARENT run's identifier block (the "Current context" text
+ * with organizationId, project/stage ids). A sub-agent's tool-call schema only
+ * carries { message, session }, so unless the sub-agent inherits the parent's
+ * context it never sees the authoritative ids — it depends on the model
+ * re-typing them into `message`, which weak models botch, causing
+ * schema/permission rejections and retry loops. Forwarding it here is the
+ * regression this seam guards.
+ */
+export declare function buildSubAgentRunInput(message: string, threadId: string, resourceId: string, parentContext?: string): {
+    message: string;
+    threadId: string;
+    resourceId: string;
+    context?: string;
+};
+export declare function buildToolDefs(params: RunAIAgentParams, agentSessionMap: Map<string, string>, resourceId: string, agentName: string, packageName: string | null, streamContext?: StreamContext, aiMiddlewares?: PikkuAIMiddlewareHooks[], agentMode?: 'delegate' | 'supervise', parentContext?: string): Promise<{
     tools: AIAgentToolDef[];
     missingRpcs: string[];
 }>;

package/dist/wirings/ai-agent/ai-agent-prepare.js

@@ -325,7 +325,29 @@ export function createScopedChannel(parent, agentName, session) {
         clearState: () => parent.clearState(),
     };
 }
-export async function buildToolDefs(params, agentSessionMap, resourceId, agentName, packageName, streamContext, aiMiddlewares, agentMode) {
+/**
+ * Build the run input for a delegated sub-agent.
+ *
+ * `context` is the PARENT run's identifier block (the "Current context" text
+ * with organizationId, project/stage ids). A sub-agent's tool-call schema only
+ * carries { message, session }, so unless the sub-agent inherits the parent's
+ * context it never sees the authoritative ids — it depends on the model
+ * re-typing them into `message`, which weak models botch, causing
+ * schema/permission rejections and retry loops. Forwarding it here is the
+ * regression this seam guards.
+ */
+export function buildSubAgentRunInput(message, threadId, resourceId, parentContext) {
+    return { message, threadId, resourceId, context: parentContext };
+}
+export async function buildToolDefs(params, agentSessionMap, resourceId, agentName, packageName, streamContext, aiMiddlewares, agentMode, 
+// The parent run's `context` (the "Current context" identifier block). A
+// delegated sub-agent's tool-call input schema only carries { message,
+// session }, so without inheriting this the sub-agent never sees the
+// authoritative ids (organizationId, project/stage ids) — it depends on the
+// model re-typing them into `message`, which weak models botch, causing
+// schema/permission rejections and retry loops. Forward it so the sub-agent
+// gets the same context block in its instructions.
+parentContext) {
     const singletonServices = getSingletonServices();
     const tools = [];
     const missingRpcs = [];
@@ -505,7 +527,7 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                                     subChannel.send(event);
                                 },
                             };
-                        const resultText = await streamAIAgent(subAgentName, { message, threadId, resourceId }, effectiveChannel, params, agentSessionMap, streamContext.options);
+                        const resultText = await streamAIAgent(subAgentName, buildSubAgentRunInput(message, threadId, resourceId, parentContext), effectiveChannel, params, agentSessionMap, streamContext.options);
                         if (subChannel.approvals.length > 0) {
                             return {
                                 [APPROVAL_REQUIRED]: true,
@@ -525,7 +547,7 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                         return resultText;
                     }
                     // No stream context: sub-agent runs non-streaming
-                    const result = await runAIAgent(subAgentName, { message, threadId, resourceId }, params, agentSessionMap);
+                    const result = await runAIAgent(subAgentName, buildSubAgentRunInput(message, threadId, resourceId, parentContext), params, agentSessionMap);
                     if (result.status === 'suspended' &&
                         result.pendingApprovals?.length) {
                         return {
@@ -731,7 +753,7 @@ export async function prepareAgentRun(agentName, input, params, agentSessionMap,
     const allMessages = [...contextMessages, ...messages, userMessage];
     const trimmedMessages = trimMessages(allMessages);
     const aiMiddlewares = agent.aiMiddleware ?? [];
-    const { tools, missingRpcs } = await buildToolDefs(params, agentSessionMap, input.resourceId, resolvedName, packageName, streamContext, aiMiddlewares, agent.agentMode);
+    const { tools, missingRpcs } = await buildToolDefs(params, agentSessionMap, input.resourceId, resolvedName, packageName, streamContext, aiMiddlewares, agent.agentMode, input.context);
     let instructions = await buildInstructions(resolvedName, packageName);
     if (input.context) {
         instructions = `${instructions}\n\nCurrent context (use these identifiers directly in tool calls — do not ask the user for them):\n${input.context}`;

package/dist/wirings/queue/index.d.ts

@@ -1,4 +1,4 @@
-export type { ConfigValidationResult, CoreQueueWorker, JobOptions, PikkuJobConfig, PikkuWorkerConfig, PikkuQueue, QueueJob, QueueJobStatus, QueueService, QueueWorkers, QueueWorkersMeta, } from './queue.types.js';
+export type { ConfigValidationResult, CoreQueueWorker, GroupConcurrencyConfig, JobGroup, JobOptions, PikkuJobConfig, PikkuWorkerConfig, PikkuQueue, QueueJob, QueueJobStatus, QueueService, QueueWorkers, QueueWorkersMeta, } from './queue.types.js';
 export { wireQueueWorker, runQueueJob, getQueueWorkers, removeQueueWorker, QueueJobDiscardedError, QueueJobFailedError, } from './queue-runner.js';
 export { validateWorkerConfig } from './validate-worker-config.js';
 export type { QueueConfigMapping } from './validate-worker-config.js';

package/dist/wirings/queue/queue.types.d.ts

@@ -30,6 +30,34 @@ export interface PikkuWorkerConfig {
     maxStalledCount?: number;
     /** Condition to start processor at instance creation */
     autorun?: boolean;
+    /**
+     * Cap how many jobs of any one group ({@link JobOptions.group}) may run at
+     * once, so a single group can't occupy the whole worker. Lets one shared
+     * queue stay fair across producers instead of splitting it into one queue
+     * per producer — which multiplies polling cost on pull-based backends.
+     * Must not exceed {@link batchSize}.
+     */
+    groupConcurrency?: number | GroupConcurrencyConfig;
+}
+/**
+ * Per-group concurrency limits, optionally varied by tier so slow groups can
+ * be allowed more (or fewer) slots than the default.
+ */
+export interface GroupConcurrencyConfig {
+    /** Limit applied to any group without a matching tier */
+    default: number;
+    /** Per-tier overrides, keyed by {@link JobGroup.tier} */
+    tiers?: Record<string, number>;
+}
+/**
+ * Fairness key for a job. Jobs sharing an `id` count against the same
+ * {@link PikkuWorkerConfig.groupConcurrency} limit.
+ */
+export interface JobGroup {
+    /** Group this job belongs to (e.g. a workflow name) */
+    id: string;
+    /** Optional tier selecting a per-tier limit */
+    tier?: string;
 }
 /**
  * Configuration for individual jobs - how jobs behave
@@ -106,6 +134,8 @@ export interface JobOptions {
     jobId?: string;
     /** Pikku user ID to propagate to the queue worker for credential resolution */
     pikkuUserId?: string;
+    /** Fairness key — counts against the worker's {@link PikkuWorkerConfig.groupConcurrency} */
+    group?: JobGroup;
 }
 /**
  * Queue provider interface for job publishing operations

package/dist/wirings/workflow/index.d.ts

@@ -11,5 +11,5 @@ export { pikkuWorkflowGraph, type PikkuWorkflowGraphConfig, type PikkuWorkflowGr
 export { validateWorkflowWiring, computeEntryNodeIds, } from './graph/graph-validation.js';
 export { pikkuWorkflowWorkerFunc, pikkuWorkflowOrchestratorFunc, pikkuWorkflowSleeperFunc, } from './workflow-queue-workers.js';
 export type { WorkflowStepInput as WorkflowStepQueueInput, PikkuWorkflowOrchestratorInput, PikkuWorkflowSleeperInput, } from './workflow-queue-workers.js';
-export type { WorkflowService, WorkflowServiceConfig, WorkflowPlannedStep, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, StepStatus, WorkflowRun, WorkflowRunStatus, StepState, WorkflowRunService, WorkflowRunMirror, CoreWorkflow, PikkuWorkflow, ContextVariable, WorkflowContext, WorkflowsMeta, WorkflowRuntimeMeta, WorkflowsRuntimeMeta, WorkflowStepInput, WorkflowOrchestratorInput, WorkflowSleeperInput, } from './workflow.types.js';
+export type { WorkflowService, WorkflowQueueOptions, WorkflowServiceConfig, WorkflowPlannedStep, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, StepStatus, WorkflowRun, WorkflowRunStatus, StepState, WorkflowRunService, WorkflowRunMirror, CoreWorkflow, PikkuWorkflow, ContextVariable, WorkflowContext, WorkflowsMeta, WorkflowRuntimeMeta, WorkflowsRuntimeMeta, WorkflowStepInput, WorkflowOrchestratorInput, WorkflowSleeperInput, } from './workflow.types.js';
 export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, WorkflowWireApproval, WorkflowApprovalOptions, ApprovalOutcome, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchCase, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, ApprovalStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, PikkuScenarioWire, } from './workflow.types.js';

package/dist/wirings/workflow/pikku-workflow-service.d.ts

@@ -1,10 +1,10 @@
 import type { SerializedError } from '../../types/core.types.js';
-import type { ApprovalOutcome, PikkuScenarioWire, StepState, StepStatus, WorkflowPlannedStep, WorkflowRun, WorkflowRunMirror, WorkflowRunStatus, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, WorkflowStepOptions } from './workflow.types.js';
+import type { ApprovalOutcome, PikkuScenarioWire, StepState, StepStatus, WorkflowPlannedStep, WorkflowRun, WorkflowRunMirror, WorkflowRunStatus, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, WorkflowQueueOptions, WorkflowStepOptions } from './workflow.types.js';
 import type { WorkflowService } from '../../services/workflow-service.js';
 import type { ScenarioActors } from '../../services/scenario-actors-service.js';
 import { PikkuError } from '../../errors/error-handler.js';
 import { type RunTimeline, type ReconstructedRunState } from './run-timeline.js';
-import type { JobOptions } from '../queue/queue.types.js';
+import type { GroupConcurrencyConfig, JobGroup, JobOptions } from '../queue/queue.types.js';
 /**
  * Default number of retries for a workflow step when none is specified. The
  * workflow — not the queue — owns retry policy; a step inherits this unless it
@@ -98,10 +98,13 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
     private runActors;
     protected get logger(): import("../../services/logger.js").Logger;
     protected mirror?: WorkflowRunMirror;
+    protected readonly queueStrategy: 'per-workflow' | 'shared-groups';
+    protected readonly queueConcurrency: number;
+    protected readonly queueGroupConcurrency: number | GroupConcurrencyConfig;
     constructor(options?: {
         wireQueues?: boolean;
         mirror?: WorkflowRunMirror;
-    });
+    } & WorkflowQueueOptions);
     private safeMirror;
     /**
      * Wire the queue-based orchestrator/step/sleeper workers.
@@ -519,4 +522,14 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      */
     protected getOrchestratorQueueName(workflowName?: string): string;
     protected getStepWorkerQueueName(rpcName?: string): string;
+    /**
+     * Fairness key for a job on a shared queue. Under `'per-workflow'` the queue
+     * name already isolates workflows, so no group is needed — returning one
+     * anyway would cap a workflow inside its own dedicated queue.
+     *
+     * The tier repeats the id so a workflow can be given its own limit purely
+     * from config, with no per-workflow wiring; an unmatched tier falls back to
+     * the default limit.
+     */
+    protected getJobGroup(id?: string): JobGroup | undefined;
 }

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

@@ -186,9 +186,15 @@ export class PikkuWorkflowService {
         return getSingletonServices()?.logger;
     }
     mirror;
+    queueStrategy;
+    queueConcurrency;
+    queueGroupConcurrency;
     constructor(options = {}) {
         const wireQueues = options.wireQueues ?? true;
         this.mirror = options.mirror;
+        this.queueStrategy = options.queueStrategy ?? 'per-workflow';
+        this.queueConcurrency = options.queueConcurrency ?? 20;
+        this.queueGroupConcurrency = options.queueGroupConcurrency ?? 2;
         if (wireQueues) {
             this.wireQueueWorkers();
         }
@@ -226,21 +232,32 @@ export class PikkuWorkflowService {
             outputSchemaName: null,
         });
         const queueMeta = pikkuState(null, 'queue', 'meta');
-        const registerWorkflowFunc = (funcId, func, queueName) => {
+        const registerWorkflowFunc = (funcId, func, queueName, config) => {
             if (functions.has(funcId))
                 return;
             addFunction(funcId, func);
             if (!queueMeta[queueName]) {
                 queueMeta[queueName] = { pikkuFuncId: funcId, name: queueName };
             }
-            wireQueueWorker({ name: queueName, func });
+            wireQueueWorker({ name: queueName, func, config });
             if (!functionsMeta[funcId]) {
                 functionsMeta[funcId] = mkMeta(funcId);
             }
         };
+        // Under 'shared-groups' every workflow runs through these two queues and is
+        // kept from hogging them by the per-group cap, so the per-workflow queues
+        // below are left unconsumed — one set of pollers for the whole system
+        // instead of one per workflow.
+        const sharedGroups = this.queueStrategy === 'shared-groups';
+        const sharedQueueConfig = sharedGroups
+            ? {
+                batchSize: this.queueConcurrency,
+                groupConcurrency: this.queueGroupConcurrency,
+            }
+            : undefined;
         // Register shared queue workers for monolith deployments
-        registerWorkflowFunc('pikkuWorkflowOrchestrator', { func: pikkuWorkflowOrchestratorFunc }, 'pikku-workflow-orchestrator');
-        registerWorkflowFunc('pikkuWorkflowStepWorker', { func: pikkuWorkflowWorkerFunc }, 'pikku-workflow-step-worker');
+        registerWorkflowFunc('pikkuWorkflowOrchestrator', { func: pikkuWorkflowOrchestratorFunc }, 'pikku-workflow-orchestrator', sharedQueueConfig);
+        registerWorkflowFunc('pikkuWorkflowStepWorker', { func: pikkuWorkflowWorkerFunc }, 'pikku-workflow-step-worker', sharedQueueConfig);
         // Register per-workflow queue workers (root + addon packages)
         const registerQueueWorkers = (queueMeta) => {
             for (const [queueName, meta] of Object.entries(queueMeta)) {
@@ -254,16 +271,32 @@ export class PikkuWorkflowService {
                 }
             }
         };
-        registerQueueWorkers(pikkuState(null, 'queue', 'meta'));
-        const addons = pikkuState(null, 'addons', 'packages');
-        if (addons) {
-            for (const [, addon] of addons) {
-                const addonQueueMeta = pikkuState(addon.package, 'queue', 'meta');
-                if (addonQueueMeta) {
-                    registerQueueWorkers(addonQueueMeta);
+        if (!sharedGroups) {
+            registerQueueWorkers(pikkuState(null, 'queue', 'meta'));
+            const addons = pikkuState(null, 'addons', 'packages');
+            if (addons) {
+                for (const [, addon] of addons) {
+                    const addonQueueMeta = pikkuState(addon.package, 'queue', 'meta');
+                    if (addonQueueMeta) {
+                        registerQueueWorkers(addonQueueMeta);
+                    }
                 }
             }
         }
+        // Workflows exist but no per-workflow orchestrator queue was registered:
+        // the generated queue meta never reached the runtime (most often the
+        // bootstrap doesn't import the queue-workers meta, so `queue.meta` is
+        // empty). Everything still "works" — dispatch silently falls back to the
+        // single shared orchestrator queue — but the isolation is gone: one slow
+        // workflow step head-of-line-blocks every other workflow behind it. That
+        // is invisible until a queue starves, so say so loudly at wiring time.
+        const workflowCount = Object.keys(pikkuState(null, 'workflows', 'meta') ?? {}).length;
+        const perWorkflowQueues = Object.keys(queueMeta).filter((name) => name.startsWith('wf-orchestrator-')).length;
+        if (workflowCount > 0 && perWorkflowQueues === 0) {
+            this.logger?.warn?.(`[pikku] ${workflowCount} workflow(s) registered but no per-workflow orchestrator queues were found in queue meta. ` +
+                `All workflows will share a single orchestrator queue, where one slow step blocks every other workflow behind it. ` +
+                `Check that the generated bootstrap imports the queue-workers meta (pikku-queue-workers-wirings-meta.gen.js).`);
+        }
         if (!functions.has('pikkuWorkflowSleeper')) {
             addFunction('pikkuWorkflowSleeper', {
                 func: pikkuWorkflowSleeperFunc,
@@ -513,7 +546,10 @@ export class PikkuWorkflowService {
         // dispatch/infra failure recover: the job is rethrown and retried instead of
         // the run hanging. Passing `attempts` per-job overrides the queue default, so
         // this holds even when the orchestrator queue is configured `retry_limit 0`.
-        await queueService.add(this.getOrchestratorQueueName(workflowName), { runId }, this.resolveStepJobOptions());
+        await queueService.add(this.getOrchestratorQueueName(workflowName), { runId }, {
+            ...this.resolveStepJobOptions(),
+            group: this.getJobGroup(workflowName),
+        });
     }
     /**
      * Resolve a step's retry policy into queue job options. The workflow is the
@@ -538,7 +574,12 @@ export class PikkuWorkflowService {
     }
     async queueStepWorker(runId, stepName, rpcName, data, stepOptions, fromStepName) {
         const queueService = this.verifyQueueService();
-        await queueService.add(this.getStepWorkerQueueName(rpcName), JSON.parse(JSON.stringify({ runId, stepName, rpcName, data, fromStepName })), this.resolveStepJobOptions(stepOptions));
+        await queueService.add(this.getStepWorkerQueueName(rpcName), JSON.parse(JSON.stringify({ runId, stepName, rpcName, data, fromStepName })), {
+            ...this.resolveStepJobOptions(stepOptions),
+            // Group by step function, mirroring how per-step queues split them —
+            // one slow step function can't monopolise the shared step worker.
+            group: this.getJobGroup(rpcName),
+        });
     }
     /**
      * Execute a workflow sleep step completion
@@ -560,7 +601,12 @@ export class PikkuWorkflowService {
             const run = await this.getRun(runId);
             workflowName = run?.workflow;
         }
-        await queueService.add(this.getOrchestratorQueueName(workflowName), { runId }, retryDelay ? { delay: getDurationInMilliseconds(retryDelay) } : undefined);
+        await queueService.add(this.getOrchestratorQueueName(workflowName), { runId }, {
+            ...(retryDelay
+                ? { delay: getDurationInMilliseconds(retryDelay) }
+                : undefined),
+            group: this.getJobGroup(workflowName),
+        });
     }
     /**
      * Dispatch a workflow step to be executed asynchronously.
@@ -592,7 +638,10 @@ export class PikkuWorkflowService {
             throw new Error(`Workflow step '${stepName}' (function '${rpcName}') is marked 'workflowQueued: true' but no queue service is configured.`);
         }
         try {
-            await getSingletonServices().queueService.add(this.getStepWorkerQueueName(rpcName), JSON.parse(JSON.stringify({ runId, stepName, rpcName, data, fromStepName })), this.resolveStepJobOptions(stepOptions));
+            await getSingletonServices().queueService.add(this.getStepWorkerQueueName(rpcName), JSON.parse(JSON.stringify({ runId, stepName, rpcName, data, fromStepName })), {
+                ...this.resolveStepJobOptions(stepOptions),
+                group: this.getJobGroup(rpcName),
+            });
         }
         catch (cause) {
             // The queue is down/unreachable — NOT a step failure. Surface it as a
@@ -1430,7 +1479,11 @@ export class PikkuWorkflowService {
             const run = await this.getRun(runId);
             if (!run?.workflow)
                 return;
-            await queueService.add(this.getOrchestratorQueueName(run.workflow), { runId }, { ...this.resolveStepJobOptions(), delay });
+            await queueService.add(this.getOrchestratorQueueName(run.workflow), { runId }, {
+                ...this.resolveStepJobOptions(),
+                delay,
+                group: this.getJobGroup(run.workflow),
+            });
         }
         catch (error) {
             this.logger?.warn(`Failed to schedule approval expiry wake for run ${runId}; expiry will still resolve on the next replay`, error);
@@ -1712,7 +1765,7 @@ export class PikkuWorkflowService {
      * queues — but it produces to them — so registrations would miss them.
      */
     getOrchestratorQueueName(workflowName) {
-        if (workflowName) {
+        if (workflowName && this.queueStrategy !== 'shared-groups') {
             const perWorkflow = `wf-orchestrator-${toKebab(workflowName)}`;
             const meta = pikkuState(null, 'queue', 'meta');
             if (meta[perWorkflow]) {
@@ -1722,7 +1775,7 @@ export class PikkuWorkflowService {
         return this.getConfig().orchestratorQueueName;
     }
     getStepWorkerQueueName(rpcName) {
-        if (rpcName) {
+        if (rpcName && this.queueStrategy !== 'shared-groups') {
             const perStep = `wf-step-${toKebab(rpcName)}`;
             const meta = pikkuState(null, 'queue', 'meta');
             if (meta[perStep]) {
@@ -1731,4 +1784,19 @@ export class PikkuWorkflowService {
         }
         return this.getConfig().stepWorkerQueueName;
     }
+    /**
+     * Fairness key for a job on a shared queue. Under `'per-workflow'` the queue
+     * name already isolates workflows, so no group is needed — returning one
+     * anyway would cap a workflow inside its own dedicated queue.
+     *
+     * The tier repeats the id so a workflow can be given its own limit purely
+     * from config, with no per-workflow wiring; an unmatched tier falls back to
+     * the default limit.
+     */
+    getJobGroup(id) {
+        if (!id || this.queueStrategy !== 'shared-groups') {
+            return undefined;
+        }
+        return { id, tier: id };
+    }
 }

package/dist/wirings/workflow/workflow.types.d.ts

@@ -1,5 +1,6 @@
 import type { SerializedError, CommonWireMeta } from '../../types/core.types.js';
 import type { CorePikkuFunctionConfig } from '../../function/functions.types.js';
+import type { GroupConcurrencyConfig } from '../queue/queue.types.js';
 export type { WorkflowService } from '../../services/workflow-service.js';
 export type { WorkflowStepOptions, WorkflowExpectEventuallyOptions, WorkflowExpectErrorOptions, WorkflowExpectServiceOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, WorkflowWireApproval, WorkflowApprovalOptions, ApprovalOutcome, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchCase, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, ApprovalStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, PikkuScenarioWire, } from './dsl/workflow-dsl.types.js';
 import type { WorkflowStepMeta } from './dsl/workflow-dsl.types.js';
@@ -18,6 +19,43 @@ export interface WorkflowServiceConfig {
     stepWorkerQueueName: string;
     sleeperRPCName: string;
 }
+/**
+ * How a workflow service spreads its jobs across queues.
+ *
+ * Passed to the service constructor rather than read from `config.workflow`:
+ * the queues are wired during construction, before singleton services (and so
+ * before `config`) exist.
+ */
+export interface WorkflowQueueOptions {
+    /**
+     * - `'per-workflow'` (default) — each workflow gets its own
+     *   `wf-orchestrator-*` / `wf-step-*` queue. Complete isolation, and it's
+     *   what lets serverless providers deploy one unit per workflow. Costs one
+     *   set of pollers per queue, which adds up on pull-based backends.
+     * - `'shared-groups'` — every workflow shares the orchestrator/step-worker
+     *   queues and stays isolated via {@link queueGroupConcurrency}, so no
+     *   workflow can occupy more than its share. One set of pollers total.
+     *   Only for single-process (monolith) runtimes; a per-unit serverless
+     *   deploy needs the per-workflow queues to route to its units.
+     */
+    queueStrategy?: 'per-workflow' | 'shared-groups';
+    /**
+     * Total concurrent workflow jobs per node under `'shared-groups'`.
+     * Defaults to 20.
+     */
+    queueConcurrency?: number;
+    /**
+     * How many jobs of one workflow may run at once under `'shared-groups'`.
+     * Defaults to 2. Tiers are keyed by workflow name, so a specific workflow
+     * can be given its own limit without any extra wiring.
+     *
+     * Note tiers can only lower a workflow's limit, not raise it above
+     * `default`: the backend's pre-fetch exclusion is applied per group using
+     * `default` alone. To give one workflow more room, raise `default` and
+     * restrict the others by tier.
+     */
+    queueGroupConcurrency?: number | GroupConcurrencyConfig;
+}
 export interface WorkflowPlannedStep {
     /** Durable step key — matches the runtime step name stored in the DB */
     stepName: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.67",
+  "version": "0.12.69",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",

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

@@ -2,7 +2,7 @@ import { describe, test, beforeEach } from 'node:test'
 import assert from 'node:assert'
 import { InMemoryWorkflowService } from './in-memory-workflow-service.js'
 import { getQueueWorkers } from '../wirings/queue/queue-runner.js'
-import { pikkuState } from '../pikku-state.js'
+import { pikkuState, resetPikkuState } from '../pikku-state.js'
 
 let service: InMemoryWorkflowService
 
@@ -390,5 +390,54 @@ describe('InMemoryWorkflowService', () => {
       assert.strictEqual(getQueueWorkers().has(stepQueue), true)
       assert.strictEqual(getQueueWorkers().has(orchQueue), true)
     })
+
+    test('shared-groups leaves per-workflow queues unconsumed', () => {
+      const orchQueue = 'wf-orchestrator-shared-strategy-check'
+
+      const queueMeta = pikkuState(null, 'queue', 'meta')
+      queueMeta[orchQueue] = {
+        name: orchQueue,
+        pikkuFuncId: 'pikkuWorkflowOrchestrator:sharedStrategyCheck',
+      }
+
+      const ws = new InMemoryWorkflowService({
+        queueStrategy: 'shared-groups',
+      })
+      ws.wireQueueWorkers()
+
+      // The whole point: one set of pollers, not one per workflow.
+      assert.strictEqual(getQueueWorkers().has(orchQueue), false)
+      assert.strictEqual(
+        getQueueWorkers().has('pikku-workflow-orchestrator'),
+        true
+      )
+    })
+
+    test('shared-groups caps how much of the shared queue one workflow takes', () => {
+      // registerWorkflowFunc is first-write-wins, so start from clean state
+      // rather than inheriting the shared queues an earlier test registered.
+      resetPikkuState()
+      const ws = new InMemoryWorkflowService({
+        queueStrategy: 'shared-groups',
+        queueConcurrency: 20,
+        queueGroupConcurrency: 3,
+      })
+      ws.wireQueueWorkers()
+
+      const worker = getQueueWorkers().get('pikku-workflow-orchestrator')
+      assert.deepStrictEqual(worker?.config, {
+        batchSize: 20,
+        groupConcurrency: 3,
+      })
+    })
+
+    test('per-workflow (the default) leaves the shared queues unconstrained', () => {
+      resetPikkuState()
+      const ws = new InMemoryWorkflowService()
+      ws.wireQueueWorkers()
+
+      const worker = getQueueWorkers().get('pikku-workflow-orchestrator')
+      assert.strictEqual(worker?.config, undefined)
+    })
   })
 })

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

@@ -4,6 +4,7 @@ import { isExpectedError } from '../errors/error-handler.js'
 import type { SerializedError } from '../types/core.types.js'
 import type {
   WorkflowPlannedStep,
+  WorkflowQueueOptions,
   WorkflowRun,
   WorkflowRunService,
   WorkflowRunWire,
@@ -39,8 +40,8 @@ export class InMemoryWorkflowService
   extends PikkuWorkflowService
   implements WorkflowRunService
 {
-  constructor() {
-    super({ wireQueues: false })
+  constructor(options: WorkflowQueueOptions = {}) {
+    super({ ...options, wireQueues: false })
   }
 
   private sleepTimers = new Set<ReturnType<typeof setTimeout>>()