@pikku/core 0.12.67 → 0.12.70

package/src/services/scenario-actors-service.ts

@@ -3,14 +3,154 @@ import type {
   ActorFlowVerdict,
 } from '../wirings/actor-flow/actor-flow.types.js'
 
+/**
+ * What the transport answered, for a step that treats the status as data.
+ *
+ * An HTTP response with its body already drained: the stream can only be read
+ * once, and a step's return value crosses into the run record, so the response
+ * object itself cannot travel. This is the shape every caller ends up with.
+ */
+export interface ScenarioHttpResponse<T = unknown> {
+  status: number
+  ok: boolean
+  /**
+   * The parsed JSON body — or, when the body was not JSON, the raw text it was
+   * parsed from, so an HTML error page is still readable rather than lost.
+   * `undefined` for an empty response.
+   *
+   * `T` is a claim the caller makes, not one the transport checked: a step that
+   * knows the route's payload names it here instead of casting at every use.
+   */
+  body: T
+  /**
+   * The whole body as text, so an assertion can search it without knowing the
+   * payload's shape — and so an error body that is HTML rather than JSON still
+   * says what went wrong.
+   */
+  serialized: string
+}
+
+/**
+ * Drain a response into the shape a step can carry: the parsed body (an empty
+ * one counting as no body at all) alongside the text it was parsed from.
+ *
+ * `invokeRaw` returns this, and a step that has to reach past an actor — a
+ * route with no RPC, an identity no actor can hold — reaches for this rather
+ * than writing the same record by hand.
+ */
+export const readScenarioHttpResponse = async <T = unknown>(
+  res: Response
+): Promise<ScenarioHttpResponse<T>> => {
+  const text = res.status === 204 ? '' : await res.text().catch(() => '')
+  return {
+    status: res.status,
+    ok: res.ok,
+    body: (text ? parseJsonBody(text) : undefined) as T,
+    serialized: text,
+  }
+}
+
+const parseJsonBody = (text: string): unknown => {
+  try {
+    return JSON.parse(text)
+  } catch {
+    return text
+  }
+}
+
+/** How to send one JSON request, for `postScenarioJson`. */
+export interface ScenarioJsonRequest {
+  /** Serialised as the JSON body. Omit for a request that carries none. */
+  body?: unknown
+  /** Sent alongside `content-type: application/json`, and may override it. */
+  headers?: Record<string, string>
+  /** Defaults to `POST` — the method every scenario route here answers. */
+  method?: string
+  /**
+   * The `fetch` to send it with. Pass a `ScenarioCookieJar`'s to keep the
+   * session; the global `fetch` otherwise, which is what a step asserting on a
+   * sessionless call wants.
+   */
+  fetch?: typeof fetch
+}
+
+/**
+ * POST JSON somewhere and report what came back, without throwing on a 4xx/5xx.
+ *
+ * Every scenario that reaches past an actor was writing this by hand — the same
+ * `content-type`, the same `JSON.stringify`, the same drain — and the copies had
+ * drifted: some returned `res.json()`, which loses the status and throws
+ * outright when the target answers an empty body or an HTML error page. A
+ * refusal is the expected outcome of a permissions scenario, so it has to
+ * survive as data.
+ */
+export const postScenarioJson = async <T = unknown>(
+  url: string,
+  {
+    body,
+    headers,
+    method = 'POST',
+    fetch: send = fetch,
+  }: ScenarioJsonRequest = {}
+): Promise<ScenarioHttpResponse<T>> =>
+  readScenarioHttpResponse<T>(
+    await send(url, {
+      method,
+      headers: { 'content-type': 'application/json', ...headers },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    })
+  )
+
+/** Per-call transport options. */
+export interface ScenarioInvokeOptions {
+  /**
+   * Headers to send alongside the actor's own session. This is how a step
+   * expresses an identity the actor registry cannot — an impersonation header,
+   * or one of the header-shim principals a credential scenario invents.
+   */
+  headers?: Record<string, string>
+}
+
+/**
+ * The RPC surface an actor can reach, as name → input/output. A project binds
+ * its generated exposed RPC map here; the default leaves every name open, which
+ * is what an actor built by hand (or by a third-party driver) gets.
+ */
+export type ScenarioRpcMap = Record<string, { input: any; output: any }>
+
+/**
+ * The actor a step wire carries, for a project whose actor registry is known.
+ * An empty registry keeps the open actor type rather than collapsing to
+ * `never` — a project may still build actors itself.
+ */
+export type ScenarioActorOf<TActors> = [keyof TActors] extends [never]
+  ? ScenarioActor
+  : TActors[keyof TActors]
+
 /** A synthetic user (a user row flagged `actor`) that workflow steps run as over the real transport */
-export interface ScenarioActor<TAgentName extends string = string> {
+export interface ScenarioActor<
+  TAgentName extends string = string,
+  TRpcMap extends ScenarioRpcMap = ScenarioRpcMap,
+> {
   /** Stable actor name (the key in pikku.config.json's actor registry). */
   readonly name: string
   /** The actor's user email — flows use it for invites/lookups. */
   readonly email: string
   /** Invoke an exposed RPC as this actor over the real transport. */
-  invoke(rpcName: string, data: unknown): Promise<unknown>
+  invoke<TName extends keyof TRpcMap & string>(
+    rpcName: TName,
+    data: TRpcMap[TName]['input']
+  ): Promise<TRpcMap[TName]['output']>
+  /**
+   * The same call, reporting what the transport answered rather than throwing.
+   * A refusal is the expected outcome of a permissions or scopes scenario, and
+   * `invoke`'s error truncates the body that names which scope was missing.
+   */
+  invokeRaw<TName extends keyof TRpcMap & string>(
+    rpcName: TName,
+    data: TRpcMap[TName]['input'],
+    options?: ScenarioInvokeOptions
+  ): Promise<ScenarioHttpResponse>
   /** Converse with a Pikku AI agent in this actor's persona and return its verdict */
   converse(options: ConverseOptions<TAgentName>): Promise<ActorFlowVerdict>
 }
@@ -21,6 +161,21 @@ export interface ScenarioActorConfig {
   name?: string
   jobTitle?: string
   personality?: string
+  /**
+   * The persona this body is one of — the KIND of person, declared in
+   * `scenarios.personas`. Most personas have exactly one actor and it is
+   * materialised for them; a second body of the same persona is what tenant
+   * isolation and peer-sharing scenarios are made of.
+   */
+  persona?: string
+  /**
+   * Scopes this actor holds, granted directly rather than through a role, and
+   * the roles it belongs to. Pikku carries them; it never applies them — which
+   * scope store exists and which roles have been created is the app's own, so
+   * the app's seed reads these back off `scenarioActorConfigs` and grants them.
+   */
+  scopes?: readonly string[]
+  roles?: readonly string[]
 }
 
 /** The injected `actors` service: actor name → actor. */

package/src/types/core.types.ts

@@ -22,6 +22,10 @@ import type {
   WorkflowServiceConfig,
   WorkflowStepWire,
 } from '../wirings/workflow/workflow.types.js'
+import type {
+  PikkuBrowserWire,
+  PikkuScenarioStepWire,
+} from '../wirings/workflow/scenario-step.types.js'
 import type { PikkuGraphWire } from '../wirings/workflow/graph/workflow-graph.types.js'
 import type { PikkuTrigger } from '../wirings/trigger/trigger.types.js'
 import type { PikkuGateway } from '../wirings/gateway/gateway.types.js'
@@ -30,7 +34,10 @@ import type { DeploymentService } from '../services/deployment-service.js'
 import type { AIStorageService } from '../services/ai-storage-service.js'
 
 import type { ContentService } from '../services/content-service.js'
-import type { ScenarioActors } from '../services/scenario-actors-service.js'
+import type {
+  ScenarioActorOf,
+  ScenarioActors,
+} from '../services/scenario-actors-service.js'
 import type { AIAgentRunnerService } from '../services/ai-agent-runner-service.js'
 import type { AIEmbeddingService } from '../services/ai-embedding-service.js'
 import type { AIRunStateService } from '../services/ai-run-state-service.js'
@@ -123,6 +130,15 @@ export type FunctionRuntimeMeta = {
   scopes?: string[]
   expose?: boolean
   remote?: boolean
+  /**
+   * A step RPC: a name dispatched by a scenario run and refused everywhere
+   * else. It sits alongside `expose` (public) and `remote` as a kind of RPC
+   * rather than a separate concept — a step is invoked by name exactly as an
+   * RPC is, which is why a run records the step function in its `rpcName`.
+   * What makes it its own kind is that it is never network-callable: a step
+   * may drive a browser or assert against fixtures.
+   */
+  scenarioStep?: boolean
   mcp?: boolean
   readonly?: boolean
   deploy?: 'serverless' | 'server' | 'auto'
@@ -133,6 +149,10 @@ export type FunctionRuntimeMeta = {
   workflowRetries?: number
   /** Timeout when this function is used as a workflow step (e.g. '30s', '5m'). */
   workflowTimeout?: string
+  /** Scenario steps only: this step drives a browser, so the runner must provision one and an actor is mandatory. */
+  scenarioStepBrowser?: boolean
+  /** Scenario steps only: the prose a reporter renders, with `{placeholders}` filled from the step's recorded input. */
+  scenarioStepTemplate?: string
   version?: number
   approvalRequired?: boolean
   approvalDescription?: string
@@ -380,6 +400,7 @@ export type PikkuWire<
   TypedWorkflow extends PikkuWorkflowWire | never = PikkuWorkflowWire,
   TriggerOutput = unknown,
   TypedScenario extends PikkuScenarioWire | never = PikkuScenarioWire,
+  TypedActors extends ScenarioActors = ScenarioActors,
 > = {
   /** Always present — lazily initialised on first access for every function invocation */
   rpc: TypedRPC
@@ -402,7 +423,11 @@ export type PikkuWire<
   cli: PikkuCLI
   workflow: TypedWorkflow
   scenario: TypedScenario
-  actors: ScenarioActors
+  actors: TypedActors
+  /** Present on every scenario step invocation */
+  scenarioStep: PikkuScenarioStepWire<ScenarioActorOf<TypedActors>>
+  /** Present only when the runner provisioned a browser for this step */
+  browser: PikkuBrowserWire
   workflowStep: WorkflowStepWire
   graph: PikkuGraphWire
   trigger: PikkuTrigger<TriggerOutput>

package/src/types/state.types.ts

@@ -40,6 +40,7 @@ import type {
 } from '../wirings/scheduler/scheduler.types.js'
 import type {
   CoreWorkflow,
+  CoreFeature,
   WorkflowsRuntimeMeta,
 } from '../wirings/workflow/workflow.types.js'
 import type {
@@ -129,6 +130,8 @@ export interface PikkuPackageState {
   }
   workflows: {
     registrations: Map<string, CoreWorkflow>
+    /** Scenario groups declared with `pikkuFeature`, keyed by export name. */
+    features: Map<string, CoreFeature>
     meta: WorkflowsRuntimeMeta
   }
   trigger: {

package/src/wirings/actor-flow/actor-flow.types.ts

@@ -21,7 +21,7 @@ export interface ConverseOptions<TAgentName extends string = string> {
   evaluate: string
   /** How the actor answers the agent's tool-approval requests. Default `'in-persona'`. */
   approvals?: ActorFlowApprovalPolicy
-  /** Model the persona uses for its own turns/decisions. Falls back to the actor service default. */
+  /** Model the actor uses for its own turns/decisions. Falls back to the actor service default. */
   model?: string
   /** Hard cap on conversation turns before forcing evaluation. Default 12. */
   maxTurns?: number

package/src/wirings/actor-flow/index.ts

@@ -18,5 +18,5 @@ export type {
 export {
   runConversation,
   type RunConversationParams,
-  type PersonaLLM,
+  type ActorLLM,
 } from './run-conversation.js'

package/src/wirings/actor-flow/run-conversation.test.ts

@@ -1,7 +1,7 @@
 import { describe, test } from 'node:test'
 import assert from 'node:assert/strict'
 
-import { runConversation, type PersonaLLM } from './run-conversation.js'
+import { runConversation, type ActorLLM } from './run-conversation.js'
 import type {
   TargetAgentDriver,
   TargetAgentReply,
@@ -23,10 +23,10 @@ const scriptedLLM = (script: {
   turns: Array<{ message: string; done: boolean }>
   decisions: Array<{ toolCallId: string; approved: boolean }>
   evaluation: { passed: boolean; reasoning: string }
-}): { llm: PersonaLLM; calls: string[] } => {
+}): { llm: ActorLLM; calls: string[] } => {
   let turn = 0
   const calls: string[] = []
-  const llm: PersonaLLM = async (params) => {
+  const llm: ActorLLM = async (params) => {
     const props =
       (params.outputSchema as { properties?: Record<string, unknown> })
         ?.properties ?? {}
@@ -109,8 +109,8 @@ const alwaysSuspendingTarget = (): {
 }
 
 const base = {
-  persona: { email: 'pm@example.com', name: 'Priya', personality: 'concise' },
-  personaName: 'Priya',
+  actor: { email: 'pm@example.com', name: 'Priya', personality: 'concise' },
+  actorName: 'Priya',
   agentName: 'todoBot',
   task: 'Get a todo created',
   evaluate: 'A todo now exists',
@@ -168,7 +168,13 @@ describe('runConversation', () => {
     const { target, approveCalls } = alwaysSuspendingTarget()
 
     await assert.rejects(
-      runConversation({ ...base, approvals: 'always', maxApprovalRounds: 3, llm, target }),
+      runConversation({
+        ...base,
+        approvals: 'always',
+        maxApprovalRounds: 3,
+        llm,
+        target,
+      }),
       /approval rounds/
     )
     assert.equal(approveCalls(), 3)

package/src/wirings/actor-flow/run-conversation.ts

@@ -11,8 +11,8 @@ import type {
   AIAgentStepResult,
 } from '../../services/ai-agent-runner-service.js'
 
-/** One turn the persona takes: the message to send and whether it's finished. */
-const PERSONA_TURN_SCHEMA = {
+/** One turn the actor takes: the message to send and whether it's finished. */
+const ACTOR_TURN_SCHEMA = {
   type: 'object',
   properties: {
     message: { type: 'string' },
@@ -21,7 +21,7 @@ const PERSONA_TURN_SCHEMA = {
   required: ['message', 'done'],
 } as const
 
-/** The persona's approve/deny decision for each pending tool request. */
+/** The actor's approve/deny decision for each pending tool request. */
 const APPROVAL_DECISION_SCHEMA = {
   type: 'object',
   properties: {
@@ -41,7 +41,7 @@ const APPROVAL_DECISION_SCHEMA = {
   required: ['decisions'],
 } as const
 
-/** The persona's final verdict on whether the task was accomplished. */
+/** The actor's final verdict on whether the task was accomplished. */
 const EVALUATION_SCHEMA = {
   type: 'object',
   properties: {
@@ -55,23 +55,23 @@ const DEFAULT_MAX_TURNS = 12
 
 const DEFAULT_MAX_APPROVAL_ROUNDS = 16
 
-/** The LLM call the persona uses for its own turns/decisions/evaluation. */
-export type PersonaLLM = (
+/** The LLM call the actor uses for its own turns/decisions/evaluation. */
+export type ActorLLM = (
   params: AIAgentRunnerParams
 ) => Promise<AIAgentStepResult>
 
 export interface RunConversationParams {
-  /** Persona config (personality/jobTitle/name) that shapes how the actor talks. */
-  persona: ScenarioActorConfig
-  /** Stable persona name (for transcript labelling). */
-  personaName: string
+  /** The actor's own config (personality/jobTitle/name), which shapes how it talks. */
+  actor: ScenarioActorConfig
+  /** Stable actor name (for transcript labelling). */
+  actorName: string
   /** What the actor is trying to get the target agent to accomplish. */
   task: string
   /** Natural-language success criterion the actor evaluates at the end. */
   evaluate: string
   /** How the actor answers the target agent's tool-approval requests. */
   approvals?: ActorFlowApprovalPolicy
-  /** Model the persona uses for its own turns/decisions. */
+  /** Model the actor uses for its own turns/decisions. */
   model: string
   /** Hard cap on conversation turns. Default 12. */
   maxTurns?: number
@@ -79,8 +79,8 @@ export interface RunConversationParams {
   maxApprovalRounds?: number
   /** Transport that drives the target agent (HTTP in production). */
   target: TargetAgentDriver
-  /** The persona's own LLM. */
-  llm: PersonaLLM
+  /** The actor's own LLM. */
+  llm: ActorLLM
   /** Display name of the target agent (transcript labelling). */
   agentName: string
 }
@@ -109,16 +109,13 @@ function readObject<T>(result: { object?: unknown; text?: string }): T | null {
   return null
 }
 
-function personaInstructions(
-  persona: ScenarioActorConfig,
-  task: string
-): string {
+function actorInstructions(actor: ScenarioActorConfig, task: string): string {
   return [
     `You are role-playing a real user interacting with an AI assistant. Stay in character at all times — you are the user, not the assistant.`,
-    persona.name ? `Your name is ${persona.name}.` : '',
-    persona.jobTitle ? `Your role: ${persona.jobTitle}.` : '',
-    persona.personality
-      ? `Your personality and communication style: ${persona.personality}. Match this tone, vocabulary, and level of detail exactly.`
+    actor.name ? `Your name is ${actor.name}.` : '',
+    actor.jobTitle ? `Your role: ${actor.jobTitle}.` : '',
+    actor.personality
+      ? `Your personality and communication style: ${actor.personality}. Match this tone, vocabulary, and level of detail exactly.`
       : '',
     `Your goal in this conversation: ${task}.`,
     `Send one message at a time. Set "done" to true only once your goal is clearly accomplished, or clearly impossible.`,
@@ -127,7 +124,7 @@ function personaInstructions(
     .join('\n')
 }
 
-/** Route the target agent's pending tool approvals through the persona. */
+/** Route the target agent's pending tool approvals through the actor. */
 async function decideApprovals(
   params: RunConversationParams,
   instructions: string,
@@ -150,7 +147,7 @@ async function decideApprovals(
 
   const result = await params.llm({
     model: params.model,
-    instructions: `${instructions}\nThe assistant is asking permission to run tools on your behalf. Decide whether YOU, as this persona, would allow each one.`,
+    instructions: `${instructions}\nThe assistant is asking permission to run tools on your behalf. Decide whether YOU, as this actor, would allow each one.`,
     messages: [
       msg(
         'user',
@@ -178,7 +175,7 @@ async function decideApprovals(
   })
 }
 
-/** Drive the target to a non-suspended reply, routing approvals to the persona. */
+/** Drive the target to a non-suspended reply, routing approvals to the actor. */
 async function converseWithTarget(
   params: RunConversationParams,
   instructions: string,
@@ -209,7 +206,7 @@ async function converseWithTarget(
 }
 
 /**
- * Run a conversation: an LLM-driven persona holds a real multi-turn exchange
+ * Run a conversation: an LLM-driven actor holds a real multi-turn exchange
  * with a target agent (driven via the injected transport), answers the target's
  * tool-approval requests in-persona, then evaluates whether the task was met.
  * Deterministic checks are the caller's responsibility.
@@ -218,11 +215,11 @@ export async function runConversation(
   params: RunConversationParams
 ): Promise<ActorFlowVerdict> {
   const maxTurns = params.maxTurns ?? DEFAULT_MAX_TURNS
-  const instructions = personaInstructions(params.persona, params.task)
-  // Seed a kickoff so the very first persona turn has a non-empty message list
-  // (providers reject an empty prompt). It's an instruction TO the persona, so
+  const instructions = actorInstructions(params.actor, params.task)
+  // Seed a kickoff so the very first actor turn has a non-empty message list
+  // (providers reject an empty prompt). It's an instruction TO the actor, so
   // it never appears in the transcript.
-  const personaMessages: AIMessage[] = [
+  const actorMessages: AIMessage[] = [
     msg(
       'user',
       'Begin the conversation now — send your first message to the assistant to work towards your goal.'
@@ -231,29 +228,27 @@ export async function runConversation(
   const transcript: string[] = []
 
   for (let turn = 0; turn < maxTurns; turn++) {
-    const personaResult = await params.llm({
+    const actorResult = await params.llm({
       model: params.model,
       instructions,
-      messages: personaMessages,
+      messages: actorMessages,
       tools: [],
       maxSteps: 1,
       toolChoice: 'none',
-      outputSchema: PERSONA_TURN_SCHEMA as unknown as Record<string, unknown>,
+      outputSchema: ACTOR_TURN_SCHEMA as unknown as Record<string, unknown>,
     })
 
-    const turnData = readObject<{ message: string; done: boolean }>(
-      personaResult
-    )
-    const personaMessage = turnData?.message?.trim()
-    if (!personaMessage) {
+    const turnData = readObject<{ message: string; done: boolean }>(actorResult)
+    const actorMessage = turnData?.message?.trim()
+    if (!actorMessage) {
       break
     }
 
-    personaMessages.push(msg('assistant', personaMessage))
-    transcript.push(`${params.personaName}: ${personaMessage}`)
+    actorMessages.push(msg('assistant', actorMessage))
+    transcript.push(`${params.actorName}: ${actorMessage}`)
 
-    const reply = await converseWithTarget(params, instructions, personaMessage)
-    personaMessages.push(msg('user', reply.text ?? ''))
+    const reply = await converseWithTarget(params, instructions, actorMessage)
+    actorMessages.push(msg('user', reply.text ?? ''))
     transcript.push(`${params.agentName}: ${reply.text ?? ''}`)
 
     if (turnData?.done) {

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)