@pikku/core 0.12.63 → 0.12.64

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

@@ -0,0 +1,305 @@
+import { randomUUID } from './ai-agent-utils.js';
+function resultToString(result) {
+    if (typeof result === 'string')
+        return result;
+    try {
+        return JSON.stringify(result, (_key, val) => typeof val === 'bigint' ? val.toString() : val);
+    }
+    catch {
+        return String(result);
+    }
+}
+export function wrapChannelWithAGUI(inner, options) {
+    const threadId = options?.threadId ?? randomUUID();
+    let runId = options?.runId ?? null;
+    function resolveRunId() {
+        if (!runId) {
+            runId = options?.getRunId?.() ?? randomUUID();
+        }
+        return runId;
+    }
+    let textMessageId = null;
+    let thinkingMessageId = null;
+    let openStepName = null;
+    let stepSeq = 0;
+    let runStartedSent = false;
+    let terminal = false;
+    let sawUsage = false;
+    let usageModel;
+    const usageTotals = { input: 0, output: 0 };
+    // The AG-UI client rejects any event arriving before RUN_STARTED, so the
+    // run is opened lazily with the first translated event.
+    function send(event) {
+        if (!runStartedSent) {
+            runStartedSent = true;
+            inner.send({
+                type: 'RUN_STARTED',
+                threadId,
+                runId: resolveRunId(),
+            });
+        }
+        inner.send(event);
+    }
+    function endTextMessage() {
+        if (textMessageId) {
+            send({ type: 'TEXT_MESSAGE_END', messageId: textMessageId });
+            textMessageId = null;
+        }
+    }
+    function endThinkingMessage() {
+        if (thinkingMessageId) {
+            send({ type: 'THINKING_TEXT_MESSAGE_END', messageId: thinkingMessageId });
+            send({ type: 'THINKING_END' });
+            thinkingMessageId = null;
+        }
+    }
+    function endStep() {
+        if (openStepName) {
+            send({ type: 'STEP_FINISHED', stepName: openStepName });
+            openStepName = null;
+        }
+    }
+    function ensureTextMessage() {
+        if (!textMessageId) {
+            textMessageId = randomUUID();
+            send({ type: 'TEXT_MESSAGE_START', messageId: textMessageId });
+        }
+        return textMessageId;
+    }
+    function ensureThinkingMessage() {
+        if (!thinkingMessageId) {
+            thinkingMessageId = randomUUID();
+            send({ type: 'THINKING_START' });
+            send({
+                type: 'THINKING_TEXT_MESSAGE_START',
+                messageId: thinkingMessageId,
+            });
+        }
+        return thinkingMessageId;
+    }
+    // The AG-UI client treats RUN_FINISHED as terminal and rejects everything
+    // after it, so it is emitted exactly once — on 'done' — with the usage
+    // accumulated across all steps (per-step 'usage' events must NOT finish
+    // the run: on multi-step tool runs later steps would arrive after
+    // RUN_FINISHED and the client would drop the whole stream).
+    function finishRun() {
+        endTextMessage();
+        endThinkingMessage();
+        endStep();
+        send({
+            type: 'RUN_FINISHED',
+            threadId,
+            runId: resolveRunId(),
+            ...(usageModel ? { model: usageModel } : {}),
+            ...(sawUsage
+                ? {
+                    usage: {
+                        promptTokens: usageTotals.input,
+                        completionTokens: usageTotals.output,
+                        totalTokens: usageTotals.input + usageTotals.output,
+                    },
+                }
+                : {}),
+        });
+        terminal = true;
+    }
+    return {
+        channelId: inner.channelId,
+        openingData: inner.openingData,
+        get state() {
+            return inner.state;
+        },
+        setState: (s) => inner.setState(s),
+        getState: () => inner.getState(),
+        clearState: () => inner.clearState(),
+        sendBinary: (data) => inner.sendBinary(data),
+        close: () => inner.close(),
+        send: (event) => {
+            if (terminal)
+                return;
+            switch (event.type) {
+                case 'text-delta': {
+                    endThinkingMessage();
+                    const id = ensureTextMessage();
+                    send({
+                        type: 'TEXT_MESSAGE_CONTENT',
+                        messageId: id,
+                        delta: event.text,
+                    });
+                    break;
+                }
+                case 'reasoning-delta': {
+                    endTextMessage();
+                    const id = ensureThinkingMessage();
+                    send({
+                        type: 'THINKING_TEXT_MESSAGE_CONTENT',
+                        messageId: id,
+                        delta: event.text,
+                    });
+                    break;
+                }
+                case 'tool-call': {
+                    endTextMessage();
+                    endThinkingMessage();
+                    send({
+                        type: 'TOOL_CALL_START',
+                        toolCallId: event.toolCallId,
+                        toolCallName: event.toolName,
+                    });
+                    send({
+                        type: 'TOOL_CALL_ARGS',
+                        toolCallId: event.toolCallId,
+                        delta: resultToString(event.args) || '{}',
+                    });
+                    send({
+                        type: 'TOOL_CALL_END',
+                        toolCallId: event.toolCallId,
+                        toolCallName: event.toolName,
+                    });
+                    break;
+                }
+                case 'tool-result': {
+                    send({
+                        type: 'TOOL_CALL_RESULT',
+                        messageId: randomUUID(),
+                        toolCallId: event.toolCallId,
+                        role: 'tool',
+                        content: resultToString(event.result),
+                    });
+                    break;
+                }
+                case 'usage': {
+                    endTextMessage();
+                    endThinkingMessage();
+                    sawUsage = true;
+                    usageTotals.input += event.tokens.input;
+                    usageTotals.output += event.tokens.output;
+                    if (event.model)
+                        usageModel = event.model;
+                    break;
+                }
+                case 'error': {
+                    endTextMessage();
+                    endThinkingMessage();
+                    endStep();
+                    send({ type: 'RUN_ERROR', message: event.message });
+                    terminal = true;
+                    break;
+                }
+                case 'done': {
+                    finishRun();
+                    break;
+                }
+                // Step names must be unique among active steps on the client and
+                // sub-agents reuse step numbers on the shared channel, so each
+                // step-start closes the previous step and gets a sequential name.
+                case 'step-start': {
+                    endTextMessage();
+                    endThinkingMessage();
+                    endStep();
+                    stepSeq += 1;
+                    openStepName = `${event.agent ?? 'step'}#${stepSeq}`;
+                    send({ type: 'STEP_STARTED', stepName: openStepName });
+                    break;
+                }
+                case 'approval-request': {
+                    endTextMessage();
+                    endThinkingMessage();
+                    send({
+                        type: 'CUSTOM',
+                        name: 'pikku:approval-request',
+                        value: {
+                            toolCallId: event.toolCallId,
+                            toolName: event.toolName,
+                            args: event.args,
+                            reason: event.reason,
+                            runId: event.runId,
+                            agent: event.agent,
+                            session: event.session,
+                        },
+                    });
+                    break;
+                }
+                case 'credential-request': {
+                    endTextMessage();
+                    endThinkingMessage();
+                    send({
+                        type: 'CUSTOM',
+                        name: 'pikku:credential-request',
+                        value: {
+                            toolCallId: event.toolCallId,
+                            toolName: event.toolName,
+                            args: event.args,
+                            credentialName: event.credentialName,
+                            credentialType: event.credentialType,
+                            connectUrl: event.connectUrl,
+                            runId: event.runId,
+                            agent: event.agent,
+                            session: event.session,
+                        },
+                    });
+                    break;
+                }
+                case 'generative-ui': {
+                    send({
+                        type: 'CUSTOM',
+                        name: 'pikku:generative-ui',
+                        value: { spec: event.spec },
+                    });
+                    break;
+                }
+                case 'data': {
+                    send({
+                        type: 'CUSTOM',
+                        name: 'pikku:data',
+                        value: { name: event.name, data: event.data },
+                    });
+                    break;
+                }
+                case 'workflow-created': {
+                    send({
+                        type: 'CUSTOM',
+                        name: 'pikku:workflow-created',
+                        value: { workflowName: event.workflowName, graph: event.graph },
+                    });
+                    break;
+                }
+                case 'agent-call': {
+                    send({
+                        type: 'CUSTOM',
+                        name: 'pikku:agent-call',
+                        value: {
+                            agentName: event.agentName,
+                            session: event.session,
+                            input: event.input,
+                        },
+                    });
+                    break;
+                }
+                case 'agent-result': {
+                    send({
+                        type: 'CUSTOM',
+                        name: 'pikku:agent-result',
+                        value: {
+                            agentName: event.agentName,
+                            session: event.session,
+                            result: event.result,
+                        },
+                    });
+                    break;
+                }
+                case 'suspended': {
+                    send({
+                        type: 'CUSTOM',
+                        name: 'pikku:suspended',
+                        value: { reason: event.reason, missingRpcs: event.missingRpcs },
+                    });
+                    break;
+                }
+                case 'audio-delta':
+                case 'audio-done':
+                    break;
+            }
+        },
+    };
+}

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

@@ -1,5 +1,5 @@
 import type { CoreUserSession } from '../../types/core.types.js';
-import type { CoreAIAgent, AIAgentInput, AIAgentToolDef, AIMessage, AIStreamChannel, PikkuAIMiddlewareHooks } from './ai-agent.types.js';
+import type { CoreAIAgent, AIAgentInput, AIAgentToolDef, AIMessage, AIStreamChannel, PikkuAIMiddlewareHooks, SessionScope } from './ai-agent.types.js';
 import type { AIAgentRunnerParams } from '../../services/ai-agent-runner-service.js';
 import { PikkuError } from '../../errors/error-handler.js';
 import type { SessionService } from '../../services/user-session-service.js';
@@ -8,9 +8,48 @@ export type RunAIAgentParams = {
     /** Credential accessor for the current request — used to read per-user overrides (e.g. AI_API_KEY). */
     getCredential?: <T = unknown>(name: string) => T | null | Promise<T | null>;
 };
+/**
+ * The ownership key for a thread/run: the trusted principal (the authenticated
+ * `session.userId` for `'user'` scope, or `session.orgId` for `'org'` scope)
+ * composed with the client-supplied `resourceId` as a sub-partition —
+ * `principal:resourceId`. Because the principal is always the prefix, a client
+ * `resourceId` can sub-divide within the caller's own boundary but can never
+ * widen access to another user's or org's threads.
+ *
+ * Idempotent: a value that is already within the caller's namespace (top-level
+ * re-entry, sub-agent recursion, or resume, which all pass an already-composite
+ * `resourceId`) is returned unchanged rather than double-composed.
+ *
+ * `'org'` scope with no session org throws {@link ForbiddenError} — falling back
+ * to a bare/shared key would leak across organizations. Sessionless `'user'`
+ * wirings have no trusted principal and fall back to the requested `resourceId`
+ * as a best-effort partition key.
+ */
+export declare function resolveOwnerResourceId(params: RunAIAgentParams, sessionScope: SessionScope | undefined, requestedResourceId: string): string;
+/** The declared {@link SessionScope} for an agent, defaulting to `'user'`. */
+export declare function agentSessionScope(agentName: string): SessionScope;
+/**
+ * Enforce that a stored thread/run belongs to the caller's owner resource,
+ * throwing {@link ForbiddenError} (without echoing the id, to avoid an
+ * existence oracle) on a mismatch.
+ */
+export declare function assertResourceOwner(ownerResourceId: string, storedResourceId: string, kind: 'thread' | 'run'): void;
 export type StreamAIAgentOptions = {
     requiresToolApproval?: 'all' | 'explicit' | false;
+    /**
+     * Invoked as soon as the run's AIRunStateService id exists, so transport
+     * wrappers (e.g. the AG-UI bridge) can stamp the real runId on RUN_STARTED.
+     */
+    onRunCreated?: (runId: string) => void;
 };
+/**
+ * Non-forgeable brand for the sub-agent approval marker. Only framework code
+ * (the delegating sub-agent tools below) sets this Symbol on a tool result; a
+ * sub-agent's LLM-shaped `result.object` — plain JSON — cannot carry a Symbol,
+ * so `checkForApprovals` trusts the brand rather than the `__approvalRequired`
+ * string key to decide an approval must be surfaced.
+ */
+export declare const APPROVAL_REQUIRED: unique symbol;
 export declare class ToolApprovalRequired extends PikkuError {
     readonly toolCallId: string;
     readonly toolName: string;
@@ -60,6 +99,7 @@ export type ScopedChannel = AIStreamChannel & {
         toolCallId: string;
         toolName: string;
         args: unknown;
+        reason?: string;
         runId: string;
     }>;
 };

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

@@ -1,14 +1,75 @@
 import { PikkuError } from '../../errors/error-handler.js';
 import { checkAuthPermissions } from '../../permissions.js';
 import { AIProviderNotConfiguredError } from '../../errors/errors.js';
+import { ForbiddenError } from '../../errors/errors.js';
 import { pikkuState, getSingletonServices } from '../../pikku-state.js';
 import { createMiddlewareSessionWireProps } from '../../services/user-session-service.js';
 import { randomUUID } from './ai-agent-utils.js';
 import { streamAIAgent } from './ai-agent-stream.js';
 import { runAIAgent } from './ai-agent-runner.js';
 import { resolveNamespace, ContextAwareRPCService, } from '../../wirings/rpc/rpc-runner.js';
+import { getOrCreatePackageSingletonServices } from '../../wirings/rpc/addon-runner.js';
 import { resolveMemoryServices, loadContextMessages, trimMessages, } from './ai-agent-memory.js';
 import { resolveModelConfig } from './ai-agent-model-config.js';
+/**
+ * The ownership key for a thread/run: the trusted principal (the authenticated
+ * `session.userId` for `'user'` scope, or `session.orgId` for `'org'` scope)
+ * composed with the client-supplied `resourceId` as a sub-partition —
+ * `principal:resourceId`. Because the principal is always the prefix, a client
+ * `resourceId` can sub-divide within the caller's own boundary but can never
+ * widen access to another user's or org's threads.
+ *
+ * Idempotent: a value that is already within the caller's namespace (top-level
+ * re-entry, sub-agent recursion, or resume, which all pass an already-composite
+ * `resourceId`) is returned unchanged rather than double-composed.
+ *
+ * `'org'` scope with no session org throws {@link ForbiddenError} — falling back
+ * to a bare/shared key would leak across organizations. Sessionless `'user'`
+ * wirings have no trusted principal and fall back to the requested `resourceId`
+ * as a best-effort partition key.
+ */
+export function resolveOwnerResourceId(params, sessionScope, requestedResourceId) {
+    const session = params.sessionService?.get();
+    let principal;
+    if ((sessionScope ?? 'user') === 'org') {
+        if (!session?.orgId) {
+            throw new ForbiddenError('This agent is org-scoped but the session has no organization');
+        }
+        principal = session.orgId;
+    }
+    else {
+        principal = session?.userId;
+    }
+    if (!principal)
+        return requestedResourceId;
+    if (requestedResourceId === principal ||
+        requestedResourceId.startsWith(`${principal}:`)) {
+        return requestedResourceId;
+    }
+    return `${principal}:${requestedResourceId}`;
+}
+/** The declared {@link SessionScope} for an agent, defaulting to `'user'`. */
+export function agentSessionScope(agentName) {
+    return resolveAgent(agentName).agent.sessionScope ?? 'user';
+}
+/**
+ * Enforce that a stored thread/run belongs to the caller's owner resource,
+ * throwing {@link ForbiddenError} (without echoing the id, to avoid an
+ * existence oracle) on a mismatch.
+ */
+export function assertResourceOwner(ownerResourceId, storedResourceId, kind) {
+    if (storedResourceId !== ownerResourceId) {
+        throw new ForbiddenError(`Not authorized to access this ${kind}`);
+    }
+}
+/**
+ * Non-forgeable brand for the sub-agent approval marker. Only framework code
+ * (the delegating sub-agent tools below) sets this Symbol on a tool result; a
+ * sub-agent's LLM-shaped `result.object` — plain JSON — cannot carry a Symbol,
+ * so `checkForApprovals` trusts the brand rather than the `__approvalRequired`
+ * string key to decide an approval must be surfaced.
+ */
+export const APPROVAL_REQUIRED = Symbol('pikku.ai.approvalRequired');
 export class ToolApprovalRequired extends PikkuError {
     toolCallId;
     toolName;
@@ -112,7 +173,7 @@ export async function buildInstructions(agentName, packageName) {
     if (meta?.goal)
         parts.push(meta.goal);
     let instructions = parts.join('\n\n');
-    if (meta?.tools?.length) {
+    if (meta?.tools?.length || meta?.workflows?.length) {
         instructions +=
             '\n\nTool usage rules:\n' +
                 '- Act immediately with the information given. Do NOT ask clarifying questions unless a required field is truly missing.\n' +
@@ -151,6 +212,7 @@ export function createScopedChannel(parent, agentName, session) {
                     toolCallId: event.toolCallId,
                     toolName: event.toolName,
                     args: event.args,
+                    ...(event.reason !== undefined ? { reason: event.reason } : {}),
                     runId: event.runId,
                 });
                 return;
@@ -244,13 +306,22 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                 if (funcConfig?.approvalDescription) {
                     const descFn = funcConfig.approvalDescription;
                     const capturedPkg = resolvedPkg;
+                    const capturedAddonConfig = resolved?.addonConfig;
+                    const capturedNamespace = toolName.includes(':')
+                        ? toolName.slice(0, toolName.indexOf(':'))
+                        : null;
                     approvalDescriptionFn = async (input) => {
                         let services = singletonServices;
                         if (capturedPkg) {
-                            const pkgServices = pikkuState(capturedPkg, 'package', 'singletonServices');
-                            if (pkgServices) {
-                                services = pkgServices;
-                            }
+                            const addonInstance = capturedNamespace
+                                ? {
+                                    namespace: capturedNamespace,
+                                    secretOverrides: capturedAddonConfig?.secretOverrides,
+                                    variableOverrides: capturedAddonConfig?.variableOverrides,
+                                    credentialOverrides: capturedAddonConfig?.credentialOverrides,
+                                }
+                                : undefined;
+                            services = await getOrCreatePackageSingletonServices(capturedPkg, singletonServices, addonInstance);
                         }
                         return descFn(services, input);
                     };
@@ -291,6 +362,7 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
             tools.push({
                 name: subAgentName,
                 description: subMeta.description,
+                forwardsApproval: true,
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -339,6 +411,7 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                         const resultText = await streamAIAgent(subAgentName, { message, threadId, resourceId }, effectiveChannel, params, agentSessionMap, streamContext.options);
                         if (subChannel.approvals.length > 0) {
                             return {
+                                [APPROVAL_REQUIRED]: true,
                                 __approvalRequired: true,
                                 toolName: subAgentName,
                                 args: toolInput,
@@ -359,6 +432,7 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                     if (result.status === 'suspended' &&
                         result.pendingApprovals?.length) {
                         return {
+                            [APPROVAL_REQUIRED]: true,
                             __approvalRequired: true,
                             toolName: subAgentName,
                             args: toolInput,
@@ -367,6 +441,7 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                                 toolCallId: a.toolCallId,
                                 toolName: a.toolName,
                                 args: a.args,
+                                reason: a.reason,
                                 runId: a.runId,
                             })),
                         };
@@ -376,6 +451,64 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
             });
         }
     }
+    const metaWorkflows = meta.workflows;
+    if (metaWorkflows?.length) {
+        const workflowMetaMap = pikkuState(null, 'workflows', 'meta');
+        const functionMeta = pikkuState(null, 'function', 'meta');
+        const schemas = pikkuState(null, 'misc', 'schemas');
+        for (const workflowName of metaWorkflows) {
+            const wfMeta = workflowMetaMap[workflowName];
+            if (!wfMeta) {
+                missingRpcs.push(workflowName);
+                continue;
+            }
+            const inputSchemaName = wfMeta.pikkuFuncId
+                ? functionMeta[wfMeta.pikkuFuncId]?.inputSchemaName
+                : undefined;
+            let inputSchema = inputSchemaName
+                ? schemas.get(inputSchemaName)
+                : undefined;
+            if (!inputSchema ||
+                (typeof inputSchema === 'object' &&
+                    inputSchema.type === 'object' &&
+                    !inputSchema.properties)) {
+                inputSchema = { type: 'object', properties: {} };
+            }
+            tools.push({
+                name: workflowName,
+                description: wfMeta.description || workflowName,
+                inputSchema,
+                execute: async (toolInput) => {
+                    const workflowService = singletonServices.workflowService;
+                    if (!workflowService) {
+                        throw new Error(`workflowService is not configured — cannot run workflow tool '${workflowName}'`);
+                    }
+                    const wire = params.sessionService
+                        ? { ...createMiddlewareSessionWireProps(params.sessionService) }
+                        : {};
+                    const rpcService = new ContextAwareRPCService(singletonServices, wire, { sessionService: params.sessionService });
+                    return workflowService.runToCompletion(workflowName, toolInput, rpcService, { wire: { type: 'internal' } });
+                },
+            });
+        }
+    }
+    // A tool's execute() can throw (bad input, RPC failure, DB error, ...). The AI
+    // SDK catches that at the tool-call boundary and turns it into a conversational
+    // "tool error" reply — without this, the exception never reaches pikku's own
+    // logger, so a failing tool is undiagnosable server-side. Log unconditionally,
+    // even when no aiMiddleware afterToolCall hook is registered to see it.
+    for (const tool of tools) {
+        const originalExecute = tool.execute;
+        tool.execute = async (toolInput) => {
+            try {
+                return await originalExecute(toolInput);
+            }
+            catch (err) {
+                singletonServices.logger.error(`AI agent tool '${tool.name}' threw during execute()`, err);
+                throw err;
+            }
+        };
+    }
     const hasToolHooks = aiMiddlewares?.some((mw) => mw.beforeToolCall || mw.afterToolCall);
     if (hasToolHooks) {
         for (const tool of tools) {
@@ -458,10 +591,17 @@ export async function prepareAgentRun(agentName, input, params, agentSessionMap,
         ? pikkuState(packageName, 'misc', 'schemas').get(workingMemorySchemaName)
         : undefined;
     if (storage) {
+        let thread = null;
         try {
-            await storage.getThread(threadId);
+            thread = await storage.getThread(threadId);
         }
         catch {
+            thread = null;
+        }
+        if (thread) {
+            assertResourceOwner(input.resourceId, thread.resourceId, 'thread');
+        }
+        else {
             await storage.createThread(input.resourceId, { threadId });
         }
     }

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

@@ -1,5 +1,5 @@
 import { saveMessages, resolveMemoryServices, loadContextMessages, trimMessages, getWorkingMemoryMiddleware, } from './ai-agent-memory.js';
-import { prepareAgentRun, resolveAgent, buildInstructions, buildToolDefs, } from './ai-agent-prepare.js';
+import { prepareAgentRun, resolveAgent, buildInstructions, buildToolDefs, resolveOwnerResourceId, agentSessionScope, assertResourceOwner, } from './ai-agent-prepare.js';
 import { checkForApprovals, appendStepMessages } from './ai-agent-stream.js';
 import { pikkuState, getSingletonServices } from '../../pikku-state.js';
 import { resolveModelConfig } from './ai-agent-model-config.js';
@@ -32,6 +32,10 @@ function extractStructuredAssistantOutput(object) {
 }
 export async function runAIAgent(agentName, input, params, agentSessionMap) {
     const sessionMap = agentSessionMap ?? new Map();
+    input = {
+        ...input,
+        resourceId: resolveOwnerResourceId(params, agentSessionScope(agentName), input.resourceId),
+    };
     const { agent, agentRunner, storage, memoryConfig, threadId, userMessage, runnerParams, maxSteps, missingRpcs, workingMemorySchemaName, } = await prepareAgentRun(agentName, input, params, sessionMap);
     runnerParams.agentId = agentName;
     const singletonServices = getSingletonServices();
@@ -281,6 +285,7 @@ export async function resumeAIAgentSync(runId, approvals, params, expectedAgentN
     const run = await aiRunState.getRun(runId);
     if (!run)
         throw new Error(`No run found for runId ${runId}`);
+    assertResourceOwner(resolveOwnerResourceId(params, agentSessionScope(run.agentName), run.resourceId), run.resourceId, 'run');
     if (expectedAgentName && run.agentName !== expectedAgentName) {
         throw new Error(`Run ${runId} belongs to agent '${run.agentName}', not '${expectedAgentName}'`);
     }