@pikku/core 0.12.72 → 0.12.77

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

@@ -1,6 +1,13 @@
 import type { CoreAIAgent, AgentRunState } from './ai-agent.types.js'
 import { pikkuState } from '../../pikku-state.js'
 import type { AIRunStateService } from '../../services/ai-run-state-service.js'
+import {
+  agentSessionScope,
+  assertAgentAuthorized,
+  assertResourcePrincipalOwner,
+  resolveAgent,
+  type RunAIAgentParams,
+} from './ai-agent-prepare.js'
 
 export const addAIAgent = (
   agentName: string,
@@ -26,7 +33,8 @@ export async function approveAIAgent(
   aiRunState: AIRunStateService,
   runId: string,
   approvals: { toolCallId: string; approved: boolean }[],
-  expectedAgentName?: string
+  expectedAgentName?: string,
+  params: RunAIAgentParams = {}
 ): Promise<{
   status: 'resumed' | 'suspended'
   runId: string
@@ -38,6 +46,12 @@ export async function approveAIAgent(
 
   const run = await aiRunState.getRun(runId)
   if (!run) throw new Error('Run not found: ' + runId)
+  assertResourcePrincipalOwner(
+    params,
+    agentSessionScope(run.agentName),
+    run.resourceId,
+    'run'
+  )
   if (expectedAgentName && run.agentName !== expectedAgentName) {
     throw new Error(
       `Run ${runId} belongs to agent '${run.agentName}', not '${expectedAgentName}'`
@@ -46,6 +60,9 @@ export async function approveAIAgent(
   if (run.status !== 'suspended')
     throw new Error('Run is not suspended: ' + run.status)
 
+  const { agent, packageName } = resolveAgent(run.agentName)
+  await assertAgentAuthorized(agent, params, packageName)
+
   const approvedIds = new Set(
     approvals.filter((a) => a.approved).map((a) => a.toolCallId)
   )

package/src/wirings/ai-agent/ai-agent-resume-authorization.test.ts

@@ -125,8 +125,6 @@ describe('resumeAIAgentSync authorization', () => {
     setup('scoped-agent-ok')
     addAgent('scoped-agent-ok', { scopes: ['admin:refund'] })
 
-    // Gets past authorization and fails later on the unconfigured provider,
-    // which is how we know the gate admitted it.
     await assert.rejects(
       () =>
         resumeAIAgentSync(

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

@@ -46,6 +46,10 @@ const makeStepResult = (
   ...overrides,
 })
 
+const asOwner = (resourceId: string) => ({
+  sessionService: { get: () => ({ userId: resourceId }) } as never,
+})
+
 describe('runAIAgent', () => {
   test('throws when aiRunState service is missing', async () => {
     addTestAgent('missing-run-state-agent')
@@ -416,7 +420,7 @@ describe('runAIAgent', () => {
     const result = await runAIAgent(
       'missing-rpc-agent',
       { message: 'deploy', threadId: 'thread-1', resourceId: 'resource-1' },
-      {}
+      asOwner('resource-1')
     )
 
     assert.equal(result.runId, 'run-missing-rpc')
@@ -686,7 +690,7 @@ describe('resumeAIAgentSync', () => {
         }),
       },
     } as any)
-    await assert.rejects(() => resumeAIAgentSync('run-y', [], {}), {
+    await assert.rejects(() => resumeAIAgentSync('run-y', [], asOwner('r')), {
       message: 'Run run-y is not suspended (status: completed)',
     })
 
@@ -708,7 +712,7 @@ describe('resumeAIAgentSync', () => {
       },
     } as any)
     await assert.rejects(
-      () => resumeAIAgentSync('run-z', [], {}),
+      () => resumeAIAgentSync('run-z', [], asOwner('r')),
       (error: unknown) => error instanceof AIProviderNotConfiguredError
     )
   })
@@ -795,7 +799,7 @@ describe('resumeAIAgentSync', () => {
     const result = await resumeAIAgentSync(
       'run-resume',
       [{ toolCallId: 'tc-1', approved: true }],
-      {}
+      asOwner('resource-resume')
     )
 
     assert.deepEqual(resolveCalls, [{ toolCallId: 'tc-1', status: 'approved' }])
@@ -872,7 +876,7 @@ describe('resumeAIAgentSync', () => {
     const denied = await resumeAIAgentSync(
       'run-deny',
       [{ toolCallId: 'tc-2', approved: false }],
-      {}
+      asOwner('resource-deny')
     )
 
     assert.deepEqual(resolveCalls, [{ toolCallId: 'tc-2', status: 'denied' }])
@@ -887,7 +891,7 @@ describe('resumeAIAgentSync', () => {
         resumeAIAgentSync(
           'run-deny',
           [{ toolCallId: 'tc-2', approved: false }],
-          {},
+          asOwner('resource-deny'),
           'other-agent'
         ),
       {
@@ -969,7 +973,7 @@ describe('resumeAIAgentSync', () => {
     const result = await resumeAIAgentSync(
       'run-error',
       [{ toolCallId: 'tc-error', approved: true }],
-      {}
+      asOwner('resource-error')
     )
 
     assert.match(savedMessages[0][0].toolResults[0].result, /tool exploded/)
@@ -1135,8 +1139,6 @@ describe('C2 resume run ownership', () => {
   test('allows the owning user past the ownership gate', async () => {
     addTestAgent('resume-owner-agent')
     pikkuState(null, 'package', 'singletonServices', {
-      // No aiAgentRunner, so a passing ownership gate surfaces the provider
-      // error instead of ForbiddenError — proving the gate did not block.
       aiRunState: { getRun: async () => suspendedRun('user-a') },
     } as any)
 

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

@@ -29,11 +29,19 @@ import {
   buildToolDefs,
   resolveOwnerResourceId,
   agentSessionScope,
-  assertResourceOwner,
+  assertResourcePrincipalOwner,
   assertAgentAuthorized,
   type RunAIAgentParams,
 } from './ai-agent-prepare.js'
 import { checkForApprovals, appendStepMessages } from './ai-agent-stream.js'
+import {
+  AgentInterruptedError,
+  isAbortError,
+  persistOrphanedToolResults,
+  registerInterruptibleRun,
+  trackInterruptNote,
+  trackToolExecution,
+} from './ai-agent-interrupt.js'
 import { pikkuState, getSingletonServices } from '../../pikku-state.js'
 import { resolveModelConfig } from './ai-agent-model-config.js'
 import { AIProviderNotConfiguredError } from '../../errors/errors.js'
@@ -136,6 +144,9 @@ export async function runAIAgent(
     ...(agent.aiMiddleware ?? []),
   ]
 
+  // One bag per run, shared by every middleware — see PikkuAIMiddlewareHooks.
+  const sharedNotes: Record<string, unknown> = {}
+
   let modifiedMessages = runnerParams.messages
   let modifiedInstructions = runnerParams.instructions
   for (const mw of aiMiddlewares) {
@@ -143,6 +154,7 @@ export async function runAIAgent(
       const result = await mw.modifyInput(singletonServices, {
         messages: modifiedMessages,
         instructions: modifiedInstructions,
+        shared: sharedNotes,
       })
       modifiedMessages = result.messages
       modifiedInstructions = result.instructions
@@ -151,6 +163,14 @@ export async function runAIAgent(
   runnerParams.messages = modifiedMessages
   runnerParams.instructions = modifiedInstructions
 
+  // History records what the model was asked, which for a spoken turn is the
+  // transcript rather than the base64 audio that arrived — see the same note on
+  // the streaming path. Identity-checked, because a middleware may legitimately
+  // replace the message list with something unrelated to this turn.
+  const lastModified = modifiedMessages[modifiedMessages.length - 1]
+  const persistedUserMessage =
+    lastModified?.id === userMessage.id ? lastModified : userMessage
+
   const runId = await aiRunState.createRun({
     agentName,
     threadId,
@@ -161,6 +181,14 @@ export async function runAIAgent(
     updatedAt: new Date(),
   })
 
+  // Registered on the same terms as `streamAIAgent`. A run created here is
+  // visible to `interruptAIAgent` through `aiRunState` either way, so skipping
+  // this would leave that call finding the run, passing the ownership check and
+  // then failing to stop it — reported as if it were running on another host.
+  const interruptHandle = registerInterruptibleRun(runId)
+  runnerParams.abortSignal = interruptHandle.signal
+  runnerParams.tools = trackToolExecution(runnerParams.tools, interruptHandle)
+
   try {
     const accumulatedSteps: AIAgentStep[] = []
     const totalUsage = { inputTokens: 0, outputTokens: 0 }
@@ -220,11 +248,7 @@ export async function runAIAgent(
 
       if (stepResult.toolCalls.length === 0) break
 
-      const approvalsNeeded = checkForApprovals(
-        stepResult,
-        runnerParams.tools,
-        runId
-      )
+      const approvalsNeeded = checkForApprovals(stepResult, runnerParams.tools)
       if (approvalsNeeded.length > 0) {
         for (const approval of approvalsNeeded) {
           const toolDef = runnerParams.tools.find(
@@ -235,9 +259,7 @@ export async function runAIAgent(
               approval.reason = await toolDef.approvalDescriptionFn(
                 approval.args
               )
-            } catch {
-              // If description generation fails, continue without it
-            }
+            } catch {}
           }
         }
 
@@ -265,7 +287,7 @@ export async function runAIAgent(
           threadId,
           input.resourceId,
           memoryConfig,
-          userMessage,
+          persistedUserMessage,
           { text: '', steps: completedStepsForSave }
         )
 
@@ -341,7 +363,7 @@ export async function runAIAgent(
       threadId,
       input.resourceId,
       memoryConfig,
-      userMessage,
+      persistedUserMessage,
       {
         ...result,
         text: outputText,
@@ -363,6 +385,21 @@ export async function runAIAgent(
       usage: totalUsage,
     }
   } catch (error) {
+    // An interrupt is not a failure, so it skips the `onError` hooks and never
+    // becomes an `errorMessage`. Unlike the streaming path there is no partial
+    // reply to hand back — nothing was delivered — so the caller gets a typed
+    // throw it can tell apart from a provider outage instead of a result.
+    const interruption = interruptHandle.interruption
+    if (interruption || isAbortError(error)) {
+      await aiRunState.updateRun(runId, { status: 'interrupted' })
+      if (storage) {
+        trackInterruptNote(
+          threadId,
+          persistOrphanedToolResults(interruptHandle, storage, threadId)
+        )
+      }
+      throw new AgentInterruptedError(runId, interruption ?? { reason: 'user' })
+    }
     for (const mw of aiMiddlewares) {
       if (mw.onError) {
         try {
@@ -371,9 +408,7 @@ export async function runAIAgent(
             stepNumber: -1,
             messages: runnerParams.messages,
           })
-        } catch {
-          // onError hooks must not affect error flow
-        }
+        } catch {}
       }
     }
     await aiRunState.updateRun(runId, {
@@ -381,6 +416,8 @@ export async function runAIAgent(
       errorMessage: error instanceof Error ? error.message : String(error),
     })
     throw error
+  } finally {
+    interruptHandle.release()
   }
 }
 
@@ -398,12 +435,9 @@ export async function resumeAIAgentSync(
 
   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
-    ),
+  assertResourcePrincipalOwner(
+    params,
+    agentSessionScope(run.agentName),
     run.resourceId,
     'run'
   )
@@ -418,9 +452,6 @@ export async function resumeAIAgentSync(
 
   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)
@@ -483,7 +514,6 @@ export async function resumeAIAgentSync(
         typeof pending.args === 'string'
           ? JSON.parse(pending.args)
           : pending.args
-      // Strip null values recursively — LLMs send null for optional fields but Zod expects undefined
       const toolArgs = stripNulls(rawArgs) ?? {}
       try {
         const toolResult = await matchingTool.execute(toolArgs)
@@ -590,6 +620,9 @@ async function continueAfterToolResultSync(
     }),
     ...(agent.aiMiddleware ?? []),
   ]
+  // One bag per run, shared by every middleware — see PikkuAIMiddlewareHooks.
+  const sharedNotes: Record<string, unknown> = {}
+
   let modifiedMessages = trimmedMessages
   let modifiedInstructions = instructions
   for (const mw of aiMiddlewares) {
@@ -597,6 +630,7 @@ async function continueAfterToolResultSync(
       const result = await mw.modifyInput(singletonServices, {
         messages: modifiedMessages,
         instructions: modifiedInstructions,
+        shared: sharedNotes,
       })
       modifiedMessages = result.messages
       modifiedInstructions = result.instructions
@@ -624,12 +658,20 @@ async function continueAfterToolResultSync(
     tools: resumeTools,
     maxSteps: 1,
     toolChoice: (agent.toolChoice ?? 'auto') as 'auto' | 'required' | 'none',
+    providerOptions: agent.providerOptions,
     outputSchema: meta?.outputSchema
       ? pikkuState(packageName, 'misc', 'schemas').get(meta.outputSchema)
       : undefined,
     agentId: run.agentName,
   }
 
+  // A resumed run keeps its original runId, so the handle registered for the
+  // first leg is long gone — an approval that kicks off more generation has to
+  // be interruptible on its own terms.
+  const interruptHandle = registerInterruptibleRun(run.runId)
+  runnerParams.abortSignal = interruptHandle.signal
+  runnerParams.tools = trackToolExecution(runnerParams.tools, interruptHandle)
+
   try {
     const accumulatedSteps: AIAgentStep[] = []
     const totalUsage = { inputTokens: 0, outputTokens: 0 }
@@ -674,11 +716,7 @@ async function continueAfterToolResultSync(
 
       if (stepResult.toolCalls.length === 0) break
 
-      const approvalsNeeded = checkForApprovals(
-        stepResult,
-        runnerParams.tools,
-        run.runId
-      )
+      const approvalsNeeded = checkForApprovals(stepResult, runnerParams.tools)
       if (approvalsNeeded.length > 0) {
         for (const approval of approvalsNeeded) {
           const toolDef = runnerParams.tools.find(
@@ -689,9 +727,7 @@ async function continueAfterToolResultSync(
               approval.reason = await toolDef.approvalDescriptionFn(
                 approval.args
               )
-            } catch {
-              // ignore
-            }
+            } catch {}
           }
         }
 
@@ -817,6 +853,20 @@ async function continueAfterToolResultSync(
       usage: totalUsage,
     }
   } catch (error) {
+    const interruption = interruptHandle.interruption
+    if (interruption || isAbortError(error)) {
+      await aiRunState.updateRun(run.runId, { status: 'interrupted' })
+      if (storage) {
+        trackInterruptNote(
+          run.threadId,
+          persistOrphanedToolResults(interruptHandle, storage, run.threadId)
+        )
+      }
+      throw new AgentInterruptedError(
+        run.runId,
+        interruption ?? { reason: 'user' }
+      )
+    }
     for (const mw of aiMiddlewares) {
       if (mw.onError) {
         try {
@@ -825,9 +875,7 @@ async function continueAfterToolResultSync(
             stepNumber: -1,
             messages: runnerParams.messages,
           })
-        } catch {
-          // ignore
-        }
+        } catch {}
       }
     }
     await aiRunState.updateRun(run.runId, {
@@ -835,5 +883,7 @@ async function continueAfterToolResultSync(
       errorMessage: error instanceof Error ? error.message : String(error),
     })
     throw error
+  } finally {
+    interruptHandle.release()
   }
 }