@pikku/core 0.12.72 → 0.12.77

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

@@ -20,6 +20,7 @@ import { pikkuState, getSingletonServices } from '../../pikku-state.js'
 import { createMiddlewareSessionWireProps } from '../../services/user-session-service.js'
 import type { SessionService } from '../../services/user-session-service.js'
 import { randomUUID } from './ai-agent-utils.js'
+import { awaitPendingInterruptNote } from './ai-agent-interrupt.js'
 import { streamAIAgent } from './ai-agent-stream.js'
 import { runAIAgent } from './ai-agent-runner.js'
 import {
@@ -38,44 +39,38 @@ export type RunAIAgentParams = {
   sessionService?: SessionService<CoreUserSession>
   /** 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>
+  /** Ephemeral owner identity minted for a sessionless request; never client-supplied, never reused across requests. */
+  anonymousOwnerResourceId?: string
 }
 
-/**
- * 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(
+export function resolveSessionPrincipal(
   params: RunAIAgentParams,
-  sessionScope: SessionScope | undefined,
-  requestedResourceId: string
-): string {
+  sessionScope: SessionScope | undefined
+): string | undefined {
   const session = params.sessionService?.get()
-  let principal: string | undefined
   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
+    return session.orgId
+  }
+  return session?.userId
+}
+
+export function resolveOwnerResourceId(
+  params: RunAIAgentParams,
+  sessionScope: SessionScope | undefined,
+  requestedResourceId: string
+): string {
+  const principal = resolveSessionPrincipal(params, sessionScope)
+
+  if (!principal) {
+    params.anonymousOwnerResourceId ??= `anon-${randomUUID()}`
+    return params.anonymousOwnerResourceId
   }
 
-  if (!principal) return requestedResourceId
   if (
     requestedResourceId === principal ||
     requestedResourceId.startsWith(`${principal}:`)
@@ -85,16 +80,22 @@ export function resolveOwnerResourceId(
   return `${principal}:${requestedResourceId}`
 }
 
-/** The declared {@link SessionScope} for an agent, defaulting to `'user'`. */
+export function assertResourcePrincipalOwner(
+  params: RunAIAgentParams,
+  sessionScope: SessionScope | undefined,
+  storedResourceId: string,
+  kind: 'thread' | 'run'
+): void {
+  const principal = resolveSessionPrincipal(params, sessionScope)
+  if (!principal || !isOwnedByPrincipal(storedResourceId, principal)) {
+    throw new ForbiddenError(`Not authorized to access this ${kind}`)
+  }
+}
+
 export function agentSessionScope(agentName: string): SessionScope {
   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: string,
   storedResourceId: string,
@@ -105,7 +106,6 @@ export function assertResourceOwner(
   }
 }
 
-/** A session's trusted principals, in the order they may be read as. */
 export function sessionPrincipals(
   session: { userId?: string; orgId?: string } | undefined
 ): string[] {
@@ -114,12 +114,6 @@ export function sessionPrincipals(
   )
 }
 
-/**
- * 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: string,
   principal: string
@@ -130,42 +124,18 @@ export function isOwnedByPrincipal(
   )
 }
 
-/**
- * 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: { userId?: string; orgId?: string } | undefined
-): string[] | undefined {
-  const principals = sessionPrincipals(session)
-  return principals.length > 0 ? principals : undefined
+): string[] {
+  return sessionPrincipals(session)
 }
 
-/**
- * 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: string,
   session: { userId?: string; orgId?: string } | undefined
 ): boolean {
   const principals = sessionPrincipals(session)
-  if (principals.length === 0) return true
+  if (principals.length === 0) return false
   return principals.some((principal) =>
     isOwnedByPrincipal(storedResourceId, principal)
   )
@@ -173,24 +143,22 @@ export function canAccessThread(
 
 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 const APPROVAL_REQUIRED: unique symbol = Symbol(
   'pikku.ai.approvalRequired'
 )
 
+/**
+ * In-process brand proving a credential request was produced by pikku itself and
+ * not by tool output an attacker can influence. Never serialized — a value that
+ * has crossed a JSON boundary has lost the brand and is treated as untrusted.
+ */
+export const CREDENTIAL_REQUIRED: unique symbol = Symbol(
+  'pikku.ai.credentialRequired'
+)
+
 export class ToolApprovalRequired extends PikkuError {
   public readonly toolCallId: string
   public readonly toolName: string
@@ -254,10 +222,6 @@ export interface AddonCredentialRequirement {
   oauth2: boolean
 }
 
-/**
- * Given a list of tool names (e.g. ["oauth-api:getProfile"]),
- * returns the wire OAuth credentials required by their addons.
- */
 export function getAddonCredentialRequirements(
   toolNames: string[]
 ): AddonCredentialRequirement[] {
@@ -333,26 +297,6 @@ export const resolveAgent = (
   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: CoreAIAgent,
   params: RunAIAgentParams,
@@ -472,20 +416,10 @@ export function createScopedChannel(
     setState: (s) => parent.setState(s),
     getState: () => parent.getState(),
     clearState: () => parent.clearState(),
+    remote: (funcName: string, data?: unknown) => parent.remote(funcName, data),
   }
 }
 
-/**
- * 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,
@@ -504,13 +438,6 @@ export async function buildToolDefs(
   streamContext?: StreamContext,
   aiMiddlewares?: PikkuAIMiddlewareHooks[],
   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()
@@ -522,7 +449,23 @@ export async function buildToolDefs(
   const meta = pikkuState(packageName, 'agent', 'agentsMeta')[agentName]
   if (!meta) return { tools, missingRpcs }
 
-  // Get session for permission filtering
+  /**
+   * A tool's description is what the model is told it does, and the main thing
+   * it chooses between tools on. It does not survive into the meta registered at
+   * boot: `description` is classed as a verbose field, so the bundled copy has
+   * it stripped and `fnMeta.description` is always undefined — every tool was
+   * being offered under its own bare name regardless of what its author wrote.
+   *
+   * `getFunctionsMeta` reads the verbose file and falls back to the minimal one,
+   * recovering the authored description wherever the generated `.pikku`
+   * directory is readable. Where it is not — no `metaService`, or a deployment
+   * shipping only the stripped copy — tools fall back to their name, which is
+   * what they did before this lookup existed.
+   */
+  const describedFunctions = await singletonServices.metaService
+    ?.getFunctionsMeta()
+    .catch(() => undefined)
+
   const session = params.sessionService
     ? await params.sessionService.get()
     : null
@@ -563,10 +506,6 @@ export async function buildToolDefs(
         continue
       }
 
-      // 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 funcConfig = pikkuFuncId
@@ -598,7 +537,6 @@ export async function buildToolDefs(
         approvalPolicy === 'all' ||
         (approvalPolicy === 'explicit' && fnMeta?.approvalRequired)
 
-      // Build approvalDescriptionFn if the function has an approvalDescription configured
       let approvalDescriptionFn:
         | ((input: unknown) => Promise<string>)
         | undefined
@@ -638,10 +576,14 @@ export async function buildToolDefs(
 
       tools.push({
         name: toolName.replaceAll('@', '_').replaceAll(':', '__'),
-        description: fnMeta?.description || fnMeta?.title || toolName,
+        description:
+          describedFunctions?.[pikkuFuncId]?.description ||
+          fnMeta?.description ||
+          toolName,
         inputSchema,
         needsApproval: needsApproval || undefined,
         approvalDescriptionFn,
+        readonly: fnMeta?.readonly || undefined,
         execute: async (toolInput: unknown) => {
           const wire: PikkuRawWire = params.sessionService
             ? { ...createMiddlewareSessionWireProps(params.sessionService) }
@@ -669,8 +611,6 @@ export async function buildToolDefs(
         continue
       }
 
-      // 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 subAgent = pikkuState(null, 'agent', 'agents').get(subAgentName)
@@ -726,8 +666,6 @@ export async function buildToolDefs(
               subAgentName,
               session
             )
-            // In supervise mode, suppress sub-agent text from reaching the client.
-            // Approvals still flow through normally.
             const effectiveChannel = isDelegate
               ? subChannel
               : {
@@ -773,7 +711,6 @@ export async function buildToolDefs(
             return resultText
           }
 
-          // No stream context: sub-agent runs non-streaming
           const result = await runAIAgent(
             subAgentName,
             buildSubAgentRunInput(message, threadId, resourceId, parentContext),
@@ -863,17 +800,19 @@ export async function buildToolDefs(
     }
   }
 
-  // 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: unknown) => {
       try {
         return await originalExecute(toolInput)
-      } catch (err) {
+      } catch (err: any) {
+        if (err?.payload?.error === 'missing_credential') {
+          return {
+            [CREDENTIAL_REQUIRED]: true,
+            __credentialRequired: true,
+            ...err.payload,
+          }
+        }
         singletonServices.logger.error(
           `AI agent tool '${tool.name}' threw during execute()`,
           err
@@ -1001,6 +940,11 @@ export async function prepareAgentRun(
 
   let messages: AIMessage[] = []
   if (storage) {
+    // A tool whose run was interrupted may still be writing its result to this
+    // thread. In voice the next turn lands within a second or two, so without
+    // this the model would load context that is missing the very thing it is
+    // about to be asked about.
+    await awaitPendingInterruptNote(threadId)
     messages = await storage.getMessages(threadId, {
       lastN: memoryConfig?.lastMessages ?? 20,
     })
@@ -1015,7 +959,13 @@ export async function prepareAgentRun(
 
   const userContent: AIMessage['content'] = input.attachments?.length
     ? [
-        { type: 'text' as const, text: input.message },
+        // Omitted when there is nothing to say. An attachment on its own is a
+        // real turn — a spoken one carries audio and no text at all — and an
+        // empty text part alongside it is a part providers are entitled to
+        // reject, for a caller who never wrote one.
+        ...(input.message
+          ? [{ type: 'text' as const, text: input.message }]
+          : []),
         ...input.attachments.map(
           (a) =>
             ({
@@ -1060,7 +1010,6 @@ export async function prepareAgentRun(
 
   const resolved = resolveModelConfig(resolvedName, agent)
 
-  // Per-request overrides
   if (input.model) {
     resolved.model = resolveModelConfig(resolvedName, {
       ...agent,
@@ -1081,6 +1030,7 @@ export async function prepareAgentRun(
     tools,
     maxSteps: 1,
     toolChoice: agent.toolChoice ?? 'auto',
+    providerOptions: agent.providerOptions,
     outputSchema,
   }
 

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

@@ -1,16 +1,56 @@
 import { beforeEach, describe, test } from 'node:test'
 import assert from 'node:assert/strict'
 
-import { resetPikkuState, pikkuState } from '../../pikku-state.js'
+import {
+  resetPikkuState,
+  pikkuState,
+  setSingletonServices,
+} from '../../pikku-state.js'
 import {
   addAIAgent,
   approveAIAgent,
   getAIAgents,
   getAIAgentsMeta,
 } from './ai-agent-registry.js'
+import { clearPermissionsCache } from '../../permissions.js'
+import { ForbiddenError, MissingScopeError } from '../../errors/errors.js'
+import type { CoreAIAgent } from './ai-agent.types.js'
+import type { CoreUserSession } from '../../types/core.types.js'
+
+const logger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+} as any
+
+const registerAgent = (
+  agentName: string,
+  overrides: Partial<CoreAIAgent> = {}
+) => {
+  const agent = {
+    name: agentName,
+    description: `${agentName} description`,
+    goal: `${agentName} goal`,
+    model: 'test/test-model',
+    ...overrides,
+  } as CoreAIAgent
+  pikkuState(null, 'agent', 'agents').set(agentName, agent)
+  pikkuState(null, 'agent', 'agentsMeta')[agentName] = { ...agent } as any
+  return agent
+}
+
+const sessionService = (session: CoreUserSession | undefined) =>
+  ({
+    get: () => session,
+    setInitial: () => {},
+    sessionChanged: false,
+  }) as any
 
 beforeEach(() => {
   resetPikkuState()
+  clearPermissionsCache()
+  setSingletonServices({ logger } as any)
 })
 
 describe('addAIAgent', () => {
@@ -70,7 +110,13 @@ describe('addAIAgent', () => {
 })
 
 describe('approveAIAgent', () => {
+  const ownerParams = {
+    sessionService: sessionService({ userId: 'resource-1' } as CoreUserSession),
+  } as any
+
   test('throws when run state service is missing, run is missing, or run is not suspended', async () => {
+    registerAgent('agent')
+
     await assert.rejects(() => approveAIAgent(null as any, 'run-1', []), {
       message: 'AIRunStateService not available',
     })
@@ -83,7 +129,9 @@ describe('approveAIAgent', () => {
             updateRun: async () => {},
           } as any,
           'run-1',
-          []
+          [],
+          undefined,
+          ownerParams
         ),
       {
         message: 'Run not found: run-1',
@@ -111,7 +159,9 @@ describe('approveAIAgent', () => {
             updateRun: async () => {},
           } as any,
           'run-1',
-          []
+          [],
+          undefined,
+          ownerParams
         ),
       {
         message: 'Run is not suspended: completed',
@@ -120,6 +170,7 @@ describe('approveAIAgent', () => {
   })
 
   test('rejects approval when run agent does not match expected agent', async () => {
+    registerAgent('internal-agent')
     const aiRunState = {
       getRun: async () => ({
         runId: 'run-1',
@@ -141,7 +192,8 @@ describe('approveAIAgent', () => {
           aiRunState,
           'run-1',
           [{ toolCallId: 'call-1', approved: true }],
-          'public-agent'
+          'public-agent',
+          ownerParams
         ),
       {
         message:
@@ -151,6 +203,7 @@ describe('approveAIAgent', () => {
   })
 
   test('marks run resumed when at least one approval is granted', async () => {
+    registerAgent('assistant')
     const updates: any[] = []
     const result = await approveAIAgent(
       {
@@ -186,7 +239,9 @@ describe('approveAIAgent', () => {
       [
         { toolCallId: 'call-1', approved: true },
         { toolCallId: 'call-3', approved: false },
-      ]
+      ],
+      undefined,
+      ownerParams
     )
 
     assert.deepEqual(updates, [
@@ -207,6 +262,7 @@ describe('approveAIAgent', () => {
   })
 
   test('keeps run suspended when nothing is approved', async () => {
+    registerAgent('assistant')
     const updates: any[] = []
     const result = await approveAIAgent(
       {
@@ -233,7 +289,9 @@ describe('approveAIAgent', () => {
         },
       } as any,
       'run-3',
-      [{ toolCallId: 'call-1', approved: false }]
+      [{ toolCallId: 'call-1', approved: false }],
+      undefined,
+      ownerParams
     )
 
     assert.deepEqual(updates, [
@@ -252,6 +310,133 @@ describe('approveAIAgent', () => {
   })
 })
 
+describe('approveAIAgent authorization', () => {
+  const suspendedRun = (agentName: string, resourceId: string) => ({
+    runId: 'run-auth',
+    agentName,
+    threadId: 'thread-1',
+    resourceId,
+    status: 'suspended',
+    pendingApprovals: [
+      { type: 'tool-call', toolCallId: 'call-1', toolName: 'refund', args: {} },
+    ],
+    usage: { inputTokens: 0, outputTokens: 0, model: 'test/test-model' },
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  })
+
+  const runStateFor = (agentName: string, resourceId: string) => {
+    const updates: any[] = []
+    return {
+      updates,
+      aiRunState: {
+        getRun: async () => suspendedRun(agentName, resourceId),
+        updateRun: async (_runId: string, patch: any) => {
+          updates.push(patch)
+        },
+      } as any,
+    }
+  }
+
+  test('rejects when the run belongs to another session principal', async () => {
+    registerAgent('owned-agent')
+    const { updates, aiRunState } = runStateFor('owned-agent', 'user-a:default')
+
+    await assert.rejects(
+      () =>
+        approveAIAgent(
+          aiRunState,
+          'run-auth',
+          [{ toolCallId: 'call-1', approved: true }],
+          undefined,
+          { sessionService: sessionService({ userId: 'user-b' }) } as any
+        ),
+      ForbiddenError
+    )
+    assert.deepEqual(updates, [], 'run state must not be mutated')
+  })
+
+  test('rejects when the agent permissions deny', async () => {
+    registerAgent('denied-agent', {
+      permissions: { denied: async () => false },
+    } as Partial<CoreAIAgent>)
+    const { updates, aiRunState } = runStateFor('denied-agent', 'u1')
+
+    await assert.rejects(
+      () =>
+        approveAIAgent(
+          aiRunState,
+          'run-auth',
+          [{ toolCallId: 'call-1', approved: true }],
+          undefined,
+          { sessionService: sessionService({ userId: 'u1' }) } as any
+        ),
+      ForbiddenError
+    )
+    assert.deepEqual(updates, [], 'run state must not be mutated')
+  })
+
+  test('rejects when a required scope is no longer held', async () => {
+    registerAgent('scoped-agent', { scopes: ['admin:refund'] })
+    const { updates, aiRunState } = runStateFor('scoped-agent', 'u1')
+
+    await assert.rejects(
+      () =>
+        approveAIAgent(
+          aiRunState,
+          'run-auth',
+          [{ toolCallId: 'call-1', approved: true }],
+          undefined,
+          {
+            sessionService: sessionService({
+              userId: 'u1',
+              scopes: ['support'],
+            }),
+          } as any
+        ),
+      MissingScopeError
+    )
+    assert.deepEqual(updates, [])
+  })
+
+  test('rejects when auth is required and the session is gone', async () => {
+    registerAgent('auth-agent', { auth: true })
+    const { updates, aiRunState } = runStateFor('auth-agent', 'resource-1')
+
+    await assert.rejects(
+      () =>
+        approveAIAgent(aiRunState, 'run-auth', [
+          { toolCallId: 'call-1', approved: true },
+        ]),
+      ForbiddenError
+    )
+    assert.deepEqual(updates, [])
+  })
+
+  test('allows the owning session through the gate', async () => {
+    registerAgent('owned-agent', { scopes: ['admin:refund'] })
+    const { updates, aiRunState } = runStateFor('owned-agent', 'user-a:default')
+
+    const result = await approveAIAgent(
+      aiRunState,
+      'run-auth',
+      [{ toolCallId: 'call-1', approved: true }],
+      undefined,
+      {
+        sessionService: sessionService({
+          userId: 'user-a',
+          scopes: ['admin:refund'],
+        }),
+      } as any
+    )
+
+    assert.equal(result.status, 'resumed')
+    assert.deepEqual(updates, [
+      { status: 'running', pendingApprovals: undefined },
+    ])
+  })
+})
+
 describe('getAIAgentsMeta', () => {
   test('returns the shared metadata registry', () => {
     const meta = getAIAgentsMeta()