@pikku/core 0.12.63 → 0.12.66

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

@@ -1,14 +1,123 @@
 import { PikkuError } from '../../errors/error-handler.js';
-import { checkAuthPermissions } from '../../permissions.js';
+import { checkAuthPermissions, runPermissions } from '../../permissions.js';
 import { AIProviderNotConfiguredError } from '../../errors/errors.js';
+import { ForbiddenError } from '../../errors/errors.js';
+import { verifyScopes } from '../../scopes.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}`);
+    }
+}
+/** A session's trusted principals, in the order they may be read as. */
+export function sessionPrincipals(session) {
+    return [session?.userId, session?.orgId].filter((principal) => Boolean(principal));
+}
+/**
+ * Whether `storedResourceId` belongs to `principal` under the composition
+ * {@link resolveOwnerResourceId} performs — either the bare principal or one of
+ * its `principal:` sub-partitions. The `:` is required so that `alice` does not
+ * match a `alice-evil:…` lookalike.
+ */
+export function isOwnedByPrincipal(storedResourceId, principal) {
+    return (storedResourceId === principal ||
+        storedResourceId.startsWith(`${principal}:`));
+}
+/**
+ * The `owners` constraint to pass to `AgentRunService.listThreads` for a caller.
+ *
+ * Returns `undefined` — not `[]` — for a session with no principal, because an
+ * empty list means "match nothing" whereas a sessionless deployment (agent
+ * `no-auth`) has no ownership model to constrain by. Keeping that carve-out here
+ * rather than at each call site stops it from being re-derived inconsistently.
+ */
+export function threadOwnerConstraint(session) {
+    const principals = sessionPrincipals(session);
+    return principals.length > 0 ? principals : undefined;
+}
+/**
+ * Whether a stored thread/run may be read by the caller. Shaped as a predicate
+ * so it can back a `pikkuPermission` — authorization belongs in a function's
+ * `permissions` field, never in its body.
+ *
+ * Unlike {@link assertResourceOwner}, which compares against a single composed
+ * owner key on the run path, this guards the thread-management reads where the
+ * caller supplies only a `threadId` — so ownership has to be derived from the
+ * session rather than from the request.
+ *
+ * A session with no principal means the deployment opted out of authorization
+ * (agent `no-auth`), so there is no ownership model to enforce and access is not
+ * gated — mirroring {@link resolveOwnerResourceId}'s sessionless fallback to a
+ * bare resourceId.
+ */
+export function canAccessThread(storedResourceId, session) {
+    const principals = sessionPrincipals(session);
+    if (principals.length === 0)
+        return true;
+    return principals.some((principal) => isOwnedByPrincipal(storedResourceId, principal));
+}
+/**
+ * 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;
@@ -102,6 +211,47 @@ export const resolveAgent = (agentName) => {
     }
     throw new Error(`AI agent not found: ${agentName}`);
 };
+/**
+ * Enforces an agent's own authorization before it runs: session presence
+ * (`auth`), then `scopes`, then `permissions`.
+ *
+ * The ordering mirrors the function runner — scopes are an AND gate checked
+ * first, so they can only ever narrow access, and a missing scope short-circuits
+ * before any permission function does I/O.
+ *
+ * `auth` follows `pikkuSessionlessFunc` rather than `pikkuFunc`: a session is
+ * required only when `auth: true` is set explicitly. An agent is normally
+ * reached from a function that has already enforced its own auth, and agents are
+ * also run from genuinely sessionless contexts (crons, queue workers), so
+ * requiring a session by default would reject those without adding a meaningful
+ * gate. `scopes` and `permissions` are always enforced when declared.
+ *
+ * Globals are evaluated here too (via {@link runPermissions}) rather than being
+ * assumed to have already run: an agent is reachable from entry points that do
+ * not go through the function runner, and re-evaluating an AND gate of
+ * side-effect-free predicates is idempotent.
+ */
+export async function assertAgentAuthorized(agent, params, packageName) {
+    const session = params.sessionService
+        ? await params.sessionService.get()
+        : undefined;
+    if (agent.auth === true && !session) {
+        throw new ForbiddenError('Authentication required');
+    }
+    verifyScopes(agent.scopes, session);
+    const singletonServices = getSingletonServices();
+    const wire = params.sessionService
+        ? createMiddlewareSessionWireProps(params.sessionService)
+        : { session: undefined };
+    await runPermissions({
+        funcPermissions: agent.permissions,
+        services: singletonServices,
+        wire: wire,
+        data: {},
+        packageName,
+        label: 'agent',
+    });
+}
 export async function buildInstructions(agentName, packageName) {
     const meta = pikkuState(packageName, 'agent', 'agentsMeta')[agentName];
     const parts = [];
@@ -112,7 +262,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 +301,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;
@@ -217,11 +368,17 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                 missingRpcs.push(toolName);
                 continue;
             }
-            // Filter out tools the user doesn't have auth for
+            // Filter out tools the user doesn't have auth for. The `pikkuAuth` brand
+            // only survives on the live permission objects in the function config, so
+            // the check reads those rather than the metadata (whose by-name registry
+            // is never populated, which would let every gated tool through).
             if (fnMeta.permissions?.length) {
                 if (!session)
                     continue;
-                const allowed = await checkAuthPermissions(fnMeta.permissions, session, singletonServices, resolvedPkg);
+                const funcConfig = pikkuFuncId
+                    ? pikkuState(resolvedPkg, 'function', 'functions').get(pikkuFuncId)
+                    : undefined;
+                const allowed = await checkAuthPermissions(funcConfig?.permissions, session, singletonServices, resolvedPkg);
                 if (!allowed)
                     continue;
             }
@@ -244,13 +401,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);
                     };
@@ -280,17 +446,20 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                 singletonServices.logger.warn(`Sub-agent '${subAgentName}' not found in agent registry`);
                 continue;
             }
-            // Filter out sub-agents the user doesn't have auth for
+            // Filter out sub-agents the user doesn't have auth for, reading the live
+            // agent config for the same reason the tool path does.
             if (subMeta.permissions?.length) {
                 if (!session)
                     continue;
-                const allowed = await checkAuthPermissions(subMeta.permissions, session, singletonServices);
+                const subAgent = pikkuState(null, 'agent', 'agents').get(subAgentName);
+                const allowed = await checkAuthPermissions(subAgent?.permissions, session, singletonServices);
                 if (!allowed)
                     continue;
             }
             tools.push({
                 name: subAgentName,
                 description: subMeta.description,
+                forwardsApproval: true,
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -339,6 +508,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 +529,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 +538,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 +548,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) {
@@ -434,6 +664,7 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
 export async function prepareAgentRun(agentName, input, params, agentSessionMap, streamContext) {
     const singletonServices = getSingletonServices();
     const { agent, packageName, resolvedName } = resolveAgent(agentName);
+    await assertAgentAuthorized(agent, params, packageName);
     let agentRunner = singletonServices.aiAgentRunner;
     if (!agentRunner) {
         throw new AIProviderNotConfiguredError();
@@ -458,10 +689,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, assertAgentAuthorized, } 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}'`);
     }
@@ -288,6 +293,10 @@ export async function resumeAIAgentSync(runId, approvals, params, expectedAgentN
         throw new Error(`Run ${runId} is not suspended (status: ${run.status})`);
     }
     const { agent, packageName, resolvedName } = resolveAgent(run.agentName);
+    // Resuming re-runs the agent, so it re-runs the agent's gate. Run ownership
+    // alone is not enough: a grant revoked while the run was suspended must stop
+    // the caller from approving its pending tool calls.
+    await assertAgentAuthorized(agent, params, packageName);
     const { storage } = resolveMemoryServices(agent, singletonServices);
     const memoryConfig = agent.memory;
     const agentRunner = singletonServices.aiAgentRunner;

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

@@ -3,9 +3,9 @@ import { AIProviderNotConfiguredError } from '../../errors/errors.js';
 import { randomUUID } from './ai-agent-utils.js';
 import { combineChannelMiddleware, wrapChannelWithMiddleware, } from '../channel/channel-middleware-runner.js';
 import { resolveMemoryServices, loadContextMessages, trimMessages, getWorkingMemoryMiddleware, } from './ai-agent-memory.js';
-import { prepareAgentRun, resolveAgent, buildInstructions, buildToolDefs, createScopedChannel, ToolApprovalRequired, ToolCredentialRequired, } from './ai-agent-prepare.js';
+import { prepareAgentRun, resolveAgent, buildInstructions, buildToolDefs, createScopedChannel, resolveOwnerResourceId, agentSessionScope, assertResourceOwner, assertAgentAuthorized, ToolApprovalRequired, ToolCredentialRequired, APPROVAL_REQUIRED, } from './ai-agent-prepare.js';
 import { resolveModelConfig } from './ai-agent-model-config.js';
-function createPersistingChannel(parent, storage, threadId) {
+function createPersistingChannel(parent, storage, threadId, logger) {
     let fullText = '';
     let stepText = '';
     let stepGenerativeUI = null;
@@ -51,6 +51,22 @@ function createPersistingChannel(parent, storage, threadId) {
             await storage.saveMessages(threadId, messages);
         }
     };
+    /**
+     * `send` is synchronous and so cannot await the flush. A rejection would have
+     * nothing to propagate to and would take the process down as an unhandled
+     * rejection — a model reusing a toolCallId, which is a primary key in AI
+     * storage, is enough to trigger it. Persistence from inside `send` is
+     * therefore best-effort: the run carries on, and the awaited `flush()` on the
+     * suspend paths still surfaces failures to its caller.
+     */
+    const flushDetached = () => {
+        void flushStep().catch((error) => {
+            logger?.error('Failed to persist agent messages', {
+                threadId,
+                error,
+            });
+        });
+    };
     const channel = {
         channelId: parent.channelId,
         openingData: parent.openingData,
@@ -97,10 +113,10 @@ function createPersistingChannel(parent, storage, threadId) {
                         totalUsage.outputTokens += event.tokens.output;
                         if (event.model)
                             totalUsage.model = event.model;
-                        flushStep();
+                        flushDetached();
                         break;
                     case 'done':
-                        flushStep();
+                        flushDetached();
                         break;
                 }
             }
@@ -213,14 +229,23 @@ export function checkForApprovals(stepResult, tools, runId) {
             approvals.push(new ToolApprovalRequired(tc.toolCallId, tc.toolName, tc.args));
             continue;
         }
+        // The approval marker is only trusted from a framework tool declared with
+        // `forwardsApproval` (the sub-agent delegating tools) AND carrying the
+        // non-forgeable `APPROVAL_REQUIRED` Symbol brand. A plain tool's output — or
+        // a delegating tool's LLM-shaped `result.object`, which an attacker can
+        // influence — is plain JSON and can never carry the Symbol, so it can never
+        // forge an approval/suspension.
+        if (!toolDef?.forwardsApproval) {
+            continue;
+        }
         const tr = stepResult.toolResults.find((r) => r.toolCallId === tc.toolCallId);
         if (tr?.result &&
             typeof tr.result === 'object' &&
-            '__approvalRequired' in tr.result) {
+            APPROVAL_REQUIRED in tr.result) {
             const r = tr.result;
             if (r.subApprovals?.length) {
                 for (const sub of r.subApprovals) {
-                    approvals.push(new ToolApprovalRequired(sub.toolCallId, r.toolName, r.args, undefined, sub.toolName, sub.args, r.agentRunId));
+                    approvals.push(new ToolApprovalRequired(sub.toolCallId, r.toolName, r.args, sub.reason, sub.toolName, sub.args, r.agentRunId));
                 }
             }
             else {
@@ -341,16 +366,32 @@ function handleCredentialRequests(requests, runId, channel, aiRunState, persisti
             suspendReason: 'credential',
             pendingApprovals,
         });
-        // Don't send credential-request SSE events — the tool result with
-        // __credentialRequired was already streamed. The frontend detects it
-        // from the tool result and shows Connect/Ignore buttons.
+        // The __credentialRequired tool result is suppressed from the stream, so
+        // credential-request events (with the runId needed for /resume) are the
+        // client's signal to show Connect/Ignore buttons — mirroring how
+        // approval-request suspensions work.
+        for (const req of requests) {
+            channel.send({
+                type: 'credential-request',
+                toolCallId: req.toolCallId,
+                toolName: req.toolName,
+                args: req.args,
+                credentialName: req.credentialName,
+                credentialType: req.credentialType,
+                connectUrl: req.connectUrl,
+                runId,
+            });
+        }
         channel.send({ type: 'done' });
         channel.close();
     })();
 }
 export async function streamAIAgent(agentName, input, channel, params, agentSessionMap, options) {
     const sessionMap = agentSessionMap ?? new Map();
-    const normalizedInput = input;
+    const normalizedInput = {
+        ...input,
+        resourceId: resolveOwnerResourceId(params, agentSessionScope(agentName), input.resourceId),
+    };
     const streamContext = { channel, options };
     // delegateState is attached after prepareAgentRun resolves the agent config
     const { agent, packageName, resolvedName, agentRunner, storage, memoryConfig, threadId, userMessage, runnerParams, maxSteps, missingRpcs, workingMemorySchemaName, } = await prepareAgentRun(agentName, normalizedInput, params, sessionMap, streamContext);
@@ -408,6 +449,7 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
         createdAt: new Date(),
         updatedAt: new Date(),
     });
+    options?.onRunCreated?.(runId);
     if (storage) {
         await storage.saveMessages(threadId, [userMessage]);
     }
@@ -443,10 +485,26 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
             ...streamMiddleware,
         ],
     });
-    const persistingChannel = createPersistingChannel(channel, storage, threadId);
+    const persistingChannel = createPersistingChannel(channel, storage, threadId, singletonServices.logger);
     const wrappedChannel = allChannelMiddleware.length > 0
         ? wrapChannelWithMiddleware({ channel: persistingChannel }, singletonServices, allChannelMiddleware).channel
         : persistingChannel;
+    // Tool results carrying the __credentialRequired marker must never reach
+    // the client or persisted history: the run suspends with credential-request
+    // events instead (mirroring approvals), and leaving the tool call
+    // unresulted is what lets the client resume it after connecting.
+    const credentialFilteredChannel = {
+        ...wrappedChannel,
+        send: (event) => {
+            if (event.type === 'tool-result' &&
+                event.result !== null &&
+                typeof event.result === 'object' &&
+                '__credentialRequired' in event.result) {
+                return;
+            }
+            wrappedChannel.send(event);
+        },
+    };
     // In delegate mode (default), suppress parent's text from reaching the client
     // AFTER a sub-agent has been called. If the parent responds directly (no delegation),
     // its text goes through normally. Sub-agent text bypasses this path entirely
@@ -458,16 +516,16 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
     }
     const outputChannel = isDelegateMode
         ? {
-            ...wrappedChannel,
+            ...credentialFilteredChannel,
             send: (event) => {
                 if (delegateState.delegated &&
                     (event.type === 'text-delta' || event.type === 'reasoning-delta'))
                     return;
-                wrappedChannel.send(event);
+                credentialFilteredChannel.send(event);
             },
             delegateState,
         }
-        : wrappedChannel;
+        : credentialFilteredChannel;
     try {
         const loopResult = await runStreamStepLoop({
             agent,
@@ -531,12 +589,18 @@ export async function resumeAIAgent(input, channel, params, options) {
     if (!run) {
         throw new Error(`No run found for runId ${input.runId}`);
     }
+    assertResourceOwner(resolveOwnerResourceId(params, agentSessionScope(run.agentName), run.resourceId), run.resourceId, 'run');
     const pending = run.pendingApprovals?.find((p) => p.toolCallId === input.toolCallId);
     if (!pending) {
         throw new Error(`No pending approval for toolCallId ${input.toolCallId} on run ${input.runId}`);
     }
-    await aiRunState.resolveApproval(input.toolCallId, input.approved ? 'approved' : 'denied');
     const { agent, packageName, resolvedName } = resolveAgent(run.agentName);
+    // Gate before resolving the approval: recording it is a persisted side
+    // effect, so an unauthorized caller must not reach it. Run ownership alone is
+    // not enough — a grant revoked while the run was suspended must stop the
+    // caller from approving its pending tool calls.
+    await assertAgentAuthorized(agent, params, packageName);
+    await aiRunState.resolveApproval(input.toolCallId, input.approved ? 'approved' : 'denied');
     const { storage } = resolveMemoryServices(agent, singletonServices);
     const memoryConfig = agent.memory;
     const agentRunner = singletonServices.aiAgentRunner;
@@ -567,6 +631,14 @@ export async function resumeAIAgent(input, channel, params, options) {
                 },
             ]);
         }
+        channel.send({
+            type: 'tool-result',
+            toolCallId: input.toolCallId,
+            toolName: pending.type === 'tool-call' || pending.type === 'credential-request'
+                ? pending.toolName
+                : pending.agentName,
+            result: denialResult,
+        });
         // Check remaining pending approvals
         const updatedRun = await aiRunState.getRun(run.runId);
         const remaining = updatedRun?.pendingApprovals ?? [];
@@ -756,7 +828,7 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
             ...streamMiddleware,
         ],
     });
-    const persistingChannel = createPersistingChannel(channel, storage, run.threadId);
+    const persistingChannel = createPersistingChannel(channel, storage, run.threadId, singletonServices.logger);
     const wrappedChannel = allChannelMiddleware.length > 0
         ? wrapChannelWithMiddleware({ channel: persistingChannel }, singletonServices, allChannelMiddleware).channel
         : persistingChannel;