@pikku/core 0.12.66 → 0.12.69

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.66",
+  "version": "0.12.69",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",

package/src/index.ts

@@ -2,6 +2,7 @@
  * @module @pikku/core
  */
 export type {
+  AuthInstance,
   CommonWireMeta,
   CoreConfig,
   CorePikkuMiddleware,
@@ -197,7 +198,7 @@ export {
   addGlobalMiddleware,
 } from './middleware-runner.js'
 export { addGlobalPermission, checkAuthPermissions } from './permissions.js'
-export { verifyScopes } from './scopes.js'
+export { hasScopes, verifyScopes } from './scopes.js'
 export {
   isSerializable,
   stopSingletonServices,

package/src/scopes.test.ts

@@ -1,6 +1,6 @@
 import { describe, test } from 'node:test'
 import * as assert from 'node:assert'
-import { verifyScopes } from './scopes.js'
+import { hasScopes, verifyScopes } from './scopes.js'
 import { MissingScopeError } from './errors/errors.js'
 import type { CoreUserSession } from './types/core.types.js'
 
@@ -165,3 +165,39 @@ describe('verifyScopes', () => {
     )
   })
 })
+
+describe('hasScopes', () => {
+  test('true on an exact match', () => {
+    assert.equal(hasScopes(['invoices:create'], ['invoices:create']), true)
+  })
+
+  test('false when the grant is unrelated', () => {
+    assert.equal(hasScopes(['invoices:create'], ['billing:read']), false)
+  })
+
+  test('shares the hierarchy rules with verifyScopes', () => {
+    assert.equal(hasScopes(['admin:impersonate'], ['admin']), true)
+    assert.equal(hasScopes(['admin:impersonate'], ['admin:*']), true)
+    assert.equal(hasScopes(['admin:impersonate'], ['*']), true)
+    assert.equal(hasScopes(['admin'], ['admin:impersonate']), false)
+  })
+
+  test('AND semantics: every required scope must be satisfied', () => {
+    assert.equal(hasScopes(['a:read', 'a:write'], ['a:read']), false)
+    assert.equal(hasScopes(['a:read', 'a:write'], ['a']), true)
+  })
+
+  test('fails closed on absent or empty grants', () => {
+    assert.equal(hasScopes(['invoices:create'], undefined), false)
+    assert.equal(hasScopes(['invoices:create'], []), false)
+  })
+
+  test('an empty requirement is satisfied by anything', () => {
+    assert.equal(hasScopes([], undefined), true)
+    assert.equal(hasScopes(undefined, undefined), true)
+  })
+
+  test('accepts a Set of held grants', () => {
+    assert.equal(hasScopes(['admin:impersonate'], new Set(['admin'])), true)
+  })
+})

package/src/scopes.ts

@@ -37,6 +37,51 @@ const satisfyingGrants = (scope: string): string[] => {
 const holds = (held: ReadonlySet<string>, scope: string): boolean =>
   satisfyingGrants(scope).some((grant) => held.has(grant))
 
+/**
+ * The first required scope a set of held grants does not satisfy, or `null`
+ * when every one is satisfied.
+ *
+ * Scopes are an AND gate: every entry in `required` must be satisfied. This is
+ * deliberately distinct from `permissions`, which OR together — a scope can
+ * only ever narrow access, so adding one to a function can never widen it.
+ *
+ * Fails closed: an absent `held` satisfies nothing.
+ */
+const firstUnsatisfied = (
+  required: readonly string[] | undefined,
+  held: Iterable<string> | undefined
+): string | null => {
+  if (!required || required.length === 0) {
+    return null
+  }
+
+  const grants = new Set(held ?? [])
+  for (const scope of required) {
+    if (!holds(grants, scope)) {
+      return scope
+    }
+  }
+  return null
+}
+
+/**
+ * Whether a set of held grants satisfies every required scope.
+ *
+ * The non-throwing counterpart to {@link verifyScopes}, for deciding rather
+ * than enforcing — an authorization gate that falls back to another check when
+ * it is not satisfied, rather than rejecting the request outright.
+ *
+ * Fails closed: an absent or empty `held` satisfies nothing. An empty
+ * `required` is satisfied by anything.
+ *
+ * @param required - Scopes to check for. Empty means no gate.
+ * @param held - The grants held, e.g. `session.scopes`. May be undefined.
+ */
+export const hasScopes = (
+  required: readonly string[] | undefined,
+  held: Iterable<string> | undefined
+): boolean => firstUnsatisfied(required, held) === null
+
 /**
  * Verifies that a session holds every required scope, throwing on the first
  * one it does not.
@@ -56,14 +101,8 @@ export const verifyScopes = (
   required: readonly string[] | undefined,
   session: CoreUserSession | undefined
 ): void => {
-  if (!required || required.length === 0) {
-    return
-  }
-
-  const held = new Set(session?.scopes ?? [])
-  for (const scope of required) {
-    if (!holds(held, scope)) {
-      throw new MissingScopeError(scope)
-    }
+  const missing = firstUnsatisfied(required, session?.scopes)
+  if (missing !== null) {
+    throw new MissingScopeError(missing)
   }
 }

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>>()

package/src/types/core.types.ts

@@ -269,6 +269,22 @@ export interface CoreUserSession {
   scopes?: string[]
 }
 
+/**
+ * The shape pikku needs from whatever auth library a project wires: something
+ * that can answer an HTTP request and expose its own endpoints as callable
+ * methods. Kept structural so core stays independent of any one auth package —
+ * `@pikku/better-auth`'s `BetterAuthInstance` is this type.
+ */
+export interface AuthInstance {
+  handler: (request: Request) => Promise<Response>
+  api: Record<string, any>
+  /**
+   * The auth library's resolved context. Optional because a hand-built instance
+   * may omit it.
+   */
+  $context?: Promise<any>
+}
+
 /**
  * Interface for core singleton services provided by Pikku.
  */
@@ -341,6 +357,13 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
    * better-auth's `mapSession`), never by the function runner.
    */
   scopeService?: ScopeService
+  /**
+   * The project's resolved auth instance, built once by the factory an auth
+   * package registers (e.g. `pikkuBetterAuth`) and injected by the generated
+   * `pikkuServices` wrapper — which is why service factories are forbidden from
+   * returning it themselves. Absent when the project wires no auth.
+   */
+  auth?: () => Promise<AuthInstance>
 }
 
 /**

package/src/wirings/ai-agent/ai-agent-prepare.test.ts

@@ -7,6 +7,7 @@ import {
   assertResourceOwner,
   canAccessThread,
   buildInstructions,
+  buildSubAgentRunInput,
   buildToolDefs,
   createScopedChannel,
   getAddonCredentialRequirements,
@@ -775,3 +776,31 @@ describe('C2 sessionScope + resume ownership', () => {
     )
   })
 })
+
+describe('buildSubAgentRunInput (parent context forwarding)', () => {
+  // A delegated sub-agent's tool-call schema only carries { message, session }.
+  // If its run input does not inherit the parent's `context` (the identifier
+  // block with organizationId / project ids), the sub-agent never sees the
+  // authoritative ids and depends on the model re-typing them into `message` —
+  // which weak models botch, causing schema/permission rejections and retry
+  // loops. These pin that the parent context is always forwarded.
+  test('forwards the parent context onto the sub-agent run input', () => {
+    const input = buildSubAgentRunInput(
+      'find failing functions',
+      'thread-1',
+      'org-uuid',
+      'organizationId: 11111111-1111-1111-1111-111111111111'
+    )
+    assert.deepEqual(input, {
+      message: 'find failing functions',
+      threadId: 'thread-1',
+      resourceId: 'org-uuid',
+      context: 'organizationId: 11111111-1111-1111-1111-111111111111',
+    })
+  })
+
+  test('context is undefined when the parent run had none (root agent)', () => {
+    const input = buildSubAgentRunInput('hi', 'thread-1', 'res-1')
+    assert.equal(input.context, undefined)
+  })
+})

package/src/wirings/ai-agent/ai-agent-prepare.ts

@@ -476,6 +476,26 @@ export function createScopedChannel(
   }
 }
 
+/**
+ * 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: string,
+  threadId: string,
+  resourceId: string,
+  parentContext?: string
+): { message: string; threadId: string; resourceId: string; context?: string } {
+  return { message, threadId, resourceId, context: parentContext }
+}
+
 export async function buildToolDefs(
   params: RunAIAgentParams,
   agentSessionMap: Map<string, string>,
@@ -484,7 +504,15 @@ export async function buildToolDefs(
   packageName: string | null,
   streamContext?: StreamContext,
   aiMiddlewares?: PikkuAIMiddlewareHooks[],
-  agentMode?: 'delegate' | 'supervise'
+  agentMode?: 'delegate' | 'supervise',
+  // 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?: string
 ): Promise<{ tools: AIAgentToolDef[]; missingRpcs: string[] }> {
   const singletonServices = getSingletonServices()
   const tools: AIAgentToolDef[] = []
@@ -716,7 +744,12 @@ export async function buildToolDefs(
                 }
             const resultText = await streamAIAgent(
               subAgentName,
-              { message, threadId, resourceId },
+              buildSubAgentRunInput(
+                message,
+                threadId,
+                resourceId,
+                parentContext
+              ),
               effectiveChannel,
               params,
               agentSessionMap,
@@ -744,7 +777,7 @@ export async function buildToolDefs(
           // No stream context: sub-agent runs non-streaming
           const result = await runAIAgent(
             subAgentName,
-            { message, threadId, resourceId },
+            buildSubAgentRunInput(message, threadId, resourceId, parentContext),
             params,
             agentSessionMap
           )
@@ -1017,7 +1050,8 @@ export async function prepareAgentRun(
     packageName,
     streamContext,
     aiMiddlewares,
-    agent.agentMode
+    agent.agentMode,
+    input.context
   )
 
   let instructions = await buildInstructions(resolvedName, packageName)

package/src/wirings/queue/index.ts

@@ -1,6 +1,8 @@
 export type {
   ConfigValidationResult,
   CoreQueueWorker,
+  GroupConcurrencyConfig,
+  JobGroup,
   JobOptions,
   PikkuJobConfig,
   PikkuWorkerConfig,