@pikku/core 0.12.72 → 0.12.77

package/src/types/state.types.ts

@@ -1,4 +1,7 @@
-import type { PikkuError, ErrorDetails } from '../errors/error-handler.js'
+import type {
+  PikkuErrorConstructor,
+  ErrorDetails,
+} from '../errors/error-handler.js'
 import type {
   CorePikkuFunctionConfig,
   CorePermissionGroup,
@@ -63,9 +66,6 @@ import type {
 } from './core.types.js'
 import type { CorePikkuChannelMiddleware } from '../wirings/channel/channel.types.js'
 
-/**
- * State structure for an individual package
- */
 export interface PikkuPackageState {
   function: {
     meta: FunctionsMeta
@@ -90,6 +90,8 @@ export interface PikkuPackageState {
         rpcEndpoint?: string
         auth?: boolean
         tags?: string[]
+        /** Required of every function in this package, on top of the function's own */
+        scopes?: string[]
         /** Per-instance name-aliases: logical name the addon reads -> actual project secret name */
         secretOverrides?: Record<string, string>
         /** Per-instance name-aliases: logical name the addon reads -> actual project variable name */
@@ -172,14 +174,13 @@ export interface PikkuPackageState {
     global: (CorePermissionGroup | CorePikkuPermission)[]
   }
   misc: {
-    errors: Map<PikkuError, ErrorDetails>
+    errors: Map<PikkuErrorConstructor, ErrorDetails>
     schemas: Map<string, any>
     middleware: Record<string, CorePikkuMiddleware[]>
     channelMiddleware: Record<string, CorePikkuChannelMiddleware[]>
     permissions: Record<string, CorePermissionGroup | CorePikkuPermission[]>
   }
   package: {
-    /** Service factory functions for addon packages */
     factories: {
       createConfig?: CreateConfig<CoreConfig>
       createSingletonServices?: CreateSingletonServices<
@@ -192,19 +193,16 @@ export interface PikkuPackageState {
         CoreUserSession
       >
     } | null
-    /** Cached singleton services for this package */
     singletonServices: CoreSingletonServices | null
     /** The pikkuBetterAuth factory, self-registered when auth.ts is evaluated.
      *  pikkuServices reads it to build and inject the `auth` singleton. */
     authFactory:
       | ((services: CoreSingletonServices) => unknown | Promise<unknown>)
       | null
-    /** Credential metadata for this addon package */
     credentialsMeta: Record<
       string,
       { name: string; displayName: string; type: string; oauth2?: boolean }
     > | null
-    /** Services this addon needs from the parent project */
     requiredParentServices: string[] | null
   }
 }

package/src/utils/hmac.ts

@@ -1,22 +1,16 @@
 import { createHmac, timingSafeEqual } from 'node:crypto'
 
 /**
- * HMAC-SHA256 a payload, hex-encoded.
- *
- * Senders wrap this in their own scheme prefix (`sha256=`, `v0=`, …).
- *
- * @param secret - The signing key shared with the other side
- * @param payload - The exact bytes that were signed
+ * HMAC-SHA256 of a payload, hex-encoded. Senders wrap this in their own scheme
+ * prefix (`sha256=`, `v0=`, …).
  */
 export function hmacSha256Hex(secret: string, payload: string): string {
   return createHmac('sha256', secret).update(payload).digest('hex')
 }
 
 /**
- * Compare two signatures without leaking their contents through timing.
- *
- * Returns false rather than throwing on a length mismatch, which is what
- * `timingSafeEqual` does when the buffers differ in size.
+ * Constant-time signature comparison. Returns false on a length mismatch,
+ * where `timingSafeEqual` itself throws.
  */
 export function timingSafeStringEqual(a: string, b: string): boolean {
   try {

package/src/utils/safe-fetch.ts

@@ -1,20 +1,7 @@
 /**
- * SSRF-aware fetch helpers.
- *
- * `@pikku/core` runs in edge runtimes (Cloudflare Workers) with no Node `dns`,
- * so we cannot resolve hostnames to check for private targets. We reject the
- * obvious internal literals and, crucially, re-validate every redirect hop —
- * a public URL that 302s to `169.254.169.254` is the common bypass. This does
- * NOT defend against a public hostname that itself resolves to a private IP
- * (DNS rebinding), which is out of reach without DNS resolution.
- */
-
-/**
- * Parse the many textual encodings of an IPv4 address that `fetch`/`undici`
- * (and `inet_aton`-style parsers) accept — a dotted quad whose octets may be
- * decimal, octal (`0177`) or hex (`0x7f`), or the whole address as a single
- * 32-bit integer (decimal `2130706433`, hex `0x7f000001`). Returns the four
- * octets, or `null` when the host is not a numeric IPv4 literal.
+ * Parses the textual IPv4 encodings `fetch`/`undici` accept — a dotted quad
+ * whose octets may be decimal, octal (`0177`) or hex (`0x7f`), or the whole
+ * address as a single 32-bit integer. `null` when not an IPv4 literal.
  */
 function parseIPv4Octets(
   host: string
@@ -46,15 +33,9 @@ function parseIPv4Octets(
 }
 
 /**
- * Whether a hostname is an obvious internal/private target (loopback, private
- * IPv4 ranges, link-local incl. the cloud metadata endpoint, or private IPv6).
- *
- * Alias/encoded forms that resolve to the same targets are also rejected: a
- * trailing-dot FQDN (`localhost.`), the `*.localhost` reserved name, IPv4-mapped
- * IPv6 (`::ffff:127.0.0.1`), and octal/decimal/hex-encoded IPv4. This is
- * best-effort literal matching only — it cannot catch a public hostname that
- * *resolves* to a private IP (DNS rebinding), which needs DNS resolution
- * unavailable in edge runtimes.
+ * Whether a hostname is an obvious internal target. Best-effort literal
+ * matching only: it cannot catch a public hostname that *resolves* to a
+ * private IP.
  */
 export function isPrivateHost(hostname: string): boolean {
   const host = hostname
@@ -102,11 +83,6 @@ export interface SafeFetchOptions {
   maxRedirects?: number
 }
 
-/**
- * Parse and validate a URL for outbound fetching: only http(s), and — unless an
- * `allowedHosts` allowlist is supplied — not an obvious private/internal host.
- * Returns the parsed URL or throws.
- */
 export function assertFetchableUrl(
   url: string,
   options: SafeFetchOptions = {}
@@ -127,17 +103,9 @@ export function assertFetchableUrl(
   return parsed
 }
 
-/**
- * The only 3xx statuses that request a redirect be followed. `300` (Multiple
- * Choices), `304` (Not Modified), `305` (Use Proxy) and `306` are returned to
- * the caller as-is rather than followed.
- */
+/** The only 3xx statuses followed; every other 3xx is returned to the caller. */
 const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308])
 
-/**
- * Drop credential-bearing headers (`Authorization`, `Cookie`) so they are not
- * replayed to a different origin across a redirect.
- */
 function stripCredentialHeaders(init: RequestInit): RequestInit {
   if (!init.headers) return init
   const headers = new Headers(init.headers)
@@ -147,10 +115,8 @@ function stripCredentialHeaders(init: RequestInit): RequestInit {
 }
 
 /**
- * Apply the WHATWG-fetch method/body transform for a redirect: a `303` (and a
- * `301`/`302` on a `POST`) becomes a bodyless `GET`; `307`/`308` preserve the
- * original method and body. When the method changes to `GET` the request body
- * and its `Content-*` headers are dropped.
+ * The WHATWG method/body transform for a redirect: `303` (and `301`/`302` on
+ * a `POST`) becomes a bodyless `GET`; `307`/`308` preserve method and body.
  */
 function redirectInit(status: number, init: RequestInit): RequestInit {
   const method = (init.method ?? 'GET').toUpperCase()
@@ -165,17 +131,10 @@ function redirectInit(status: number, init: RequestInit): RequestInit {
 }
 
 /**
- * `fetch` with SSRF protection. The initial URL and every redirect target are
- * validated with {@link assertFetchableUrl}. Redirects are followed manually
- * (`redirect: 'manual'`) so an unsafe `Location` can never be followed into the
- * internal network; only the redirect statuses in {@link REDIRECT_STATUSES} are
- * followed, and the method/body are transformed per {@link redirectInit}. Each
- * intermediate redirect response body is cancelled before the next hop so it is
- * not left dangling. When a redirect cannot or should not be followed (no
- * `Location`, or the hop budget is exhausted) the raw redirect response is
- * returned for the caller to handle by status. Credential headers
- * (`Authorization`, `Cookie`) are stripped whenever a redirect crosses origin,
- * so they never leak to a redirected host.
+ * `fetch` with SSRF protection on the initial URL and every redirect hop.
+ * When a redirect cannot be followed (no `Location`, or the hop budget is
+ * spent) the raw redirect response is returned for the caller to handle by
+ * status.
  */
 export async function safeFetch(
   url: string,

package/src/utils.test.ts

@@ -34,6 +34,17 @@ describe('createWeakUID', () => {
     const uid = createWeakUID()
     assert.ok(uid.includes('-'))
   })
+
+  test('separate module instances get different prefixes', async () => {
+    const [a, b] = await Promise.all([
+      import('./utils.js?instance=a'),
+      import('./utils.js?instance=b'),
+    ])
+    assert.notStrictEqual(
+      a.createWeakUID().split('-')[0],
+      b.createWeakUID().split('-')[0]
+    )
+  })
 })
 
 describe('isSerializable', () => {
@@ -238,7 +249,6 @@ describe('closeWireServices', () => {
     }
 
     await closeWireServices(mockLogger as any, wireServices as any)
-    // Should not throw
   })
 })
 
@@ -295,7 +305,6 @@ describe('stopSingletonServices', () => {
     pikkuState(null, 'package', 'singletonServices', mockServices as any)
 
     await stopSingletonServices()
-    // Should not throw
   })
 
   test('should handle errors during stop gracefully', async () => {

package/src/utils.ts

@@ -23,9 +23,12 @@ export const closeWireServices = async (
   )
 }
 
-const _uidPrefix = Date.now().toString(36)
+let _uidPrefix: string | undefined
 let _uidCounter = 0
-export const createWeakUID = () => `${_uidPrefix}-${++_uidCounter}`
+export const createWeakUID = () => {
+  _uidPrefix ??= globalThis.crypto.randomUUID().slice(0, 8)
+  return `${_uidPrefix}-${++_uidCounter}`
+}
 
 export const isSerializable = (data: any): boolean => {
   return !(
@@ -78,9 +81,6 @@ export const freezeDedupe = <T>(
   return Object.freeze(out)
 }
 
-/**
- * Stop a single service by calling its stop method if it exists
- */
 const stopService = async (
   logger: Logger,
   name: string,
@@ -97,21 +97,14 @@ const stopService = async (
   }
 }
 
-/**
- * Stop all singleton services, including addon package services.
- * Addon package services are stopped first, then the parent services.
- *
- * @param singletonServices - The parent singleton services to stop
- */
+/** Stops addon package services first, then the parent singleton services. */
 export const stopSingletonServices = async (): Promise<void> => {
   const singletonServices = getSingletonServices()
   const logger = singletonServices.logger
 
-  // Stop all addon package singleton services
   const stateMap = getAllPackageStates()
   if (stateMap.size > 0) {
     for (const [packageName, packageState] of stateMap) {
-      // Skip main package - we handle it separately
       if (packageName === '__main__') continue
 
       const packageServices = packageState.package?.singletonServices
@@ -120,13 +113,11 @@ export const stopSingletonServices = async (): Promise<void> => {
         for (const [name, service] of Object.entries(packageServices)) {
           await stopService(logger, `${packageName}/${name}`, service)
         }
-        // Clear the cached services
         packageState.package.singletonServices = null
       }
     }
   }
 
-  // Then stop the parent singleton services
   for (const [name, service] of Object.entries(singletonServices)) {
     await stopService(logger, name, service)
   }

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

@@ -1,47 +1,22 @@
-/**
- * How an actor agent answers the target agent's tool-approval requests during
- * a conversation.
- * - `'in-persona'` — the actor agent decides as the persona would (default).
- * - `'always'` — approve every request (stress the happy path).
- * - `'never'` — deny every request (exercise refusal handling).
- */
 export type ActorFlowApprovalPolicy = 'in-persona' | 'always' | 'never'
 
-/**
- * Options for `actor.converse(...)` — a dynamic conversation an actor holds
- * with a target Pikku AI agent, in the actor's own persona. `TAgentName` is
- * bound to the generated union of agent names in a typed project.
- */
 export interface ConverseOptions<TAgentName extends string = string> {
-  /** Target Pikku AI agent name to converse with. */
   agent: TAgentName
   /** What the actor is trying to get the agent to accomplish. */
   task: string
-  /** Natural-language success criterion the actor evaluates at the end. */
+  /** Natural-language success criterion the actor judges the conversation against. */
   evaluate: string
-  /** How the actor answers the agent's tool-approval requests. Default `'in-persona'`. */
   approvals?: ActorFlowApprovalPolicy
-  /** Model the actor uses for its own turns/decisions. Falls back to the actor service default. */
   model?: string
-  /** Hard cap on conversation turns before forcing evaluation. Default 12. */
   maxTurns?: number
 }
 
-/**
- * The verdict a conversation produces: the persona's LLM self-evaluation of
- * whether the task was met. Deterministic checks are the caller's job — they
- * already hold the actor and can `actor.invoke(...)` afterwards.
- */
 export interface ActorFlowVerdict {
-  /** Whether the actor judged the task accomplished. */
   passed: boolean
-  /** The actor's reasoning for its verdict. */
   reasoning: string
-  /** The conversation transcript, for debugging/reporting. */
   transcript: string[]
 }
 
-/** A pending tool-approval request surfaced by the target agent. */
 export interface TargetPendingApproval {
   toolCallId: string
   toolName: string
@@ -49,7 +24,6 @@ export interface TargetPendingApproval {
   reason?: string
 }
 
-/** A normalized reply from the target agent, independent of transport. */
 export interface TargetAgentReply {
   text: string
   runId: string
@@ -57,15 +31,8 @@ export interface TargetAgentReply {
   pendingApprovals?: TargetPendingApproval[]
 }
 
-/**
- * Drives the target agent. In production this is HTTP-backed (the actor's
- * `agentRun` / `agentApprove` calls as the signed-in actor); the conversation
- * engine only sees this transport-agnostic contract.
- */
 export interface TargetAgentDriver {
-  /** Send a message, starting or continuing the target agent's run. */
   run(message: string): Promise<TargetAgentReply>
-  /** Answer the target agent's pending approvals and continue its run. */
   approve(
     runId: string,
     decisions: { toolCallId: string; approved: boolean }[]

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

@@ -1,12 +1,3 @@
-/**
- * Actor flow module exports.
- *
- * An actor holds a dynamic conversation with a target Pikku AI agent via
- * `actor.converse(...)` — playing its own persona, approving the agent's tool
- * requests in-persona, and evaluating whether the task was accomplished. The
- * conversation engine here is transport-agnostic; the actor drives the target
- * over HTTP.
- */
 export type {
   ActorFlowApprovalPolicy,
   ActorFlowVerdict,

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

@@ -18,7 +18,6 @@ const stepResult = (object: unknown): AIAgentStepResult => ({
   finishReason: 'stop',
 })
 
-/** A persona LLM scripted by the outputSchema it's asked for. */
 const scriptedLLM = (script: {
   turns: Array<{ message: string; done: boolean }>
   decisions: Array<{ toolCallId: string; approved: boolean }>
@@ -31,7 +30,6 @@ const scriptedLLM = (script: {
       (params.outputSchema as { properties?: Record<string, unknown> })
         ?.properties ?? {}
     if ('message' in props) {
-      // Providers reject an empty prompt — every persona turn must carry messages.
       assert.ok(
         params.messages.length > 0,
         'persona turn requested with empty messages'
@@ -54,7 +52,6 @@ const scriptedLLM = (script: {
   return { llm, calls }
 }
 
-/** A target that suspends once for approval, then completes. */
 const suspendingTarget = (): {
   target: TargetAgentDriver
   approvedWith: Array<{ toolCallId: string; approved: boolean }[]>
@@ -84,7 +81,6 @@ const suspendingTarget = (): {
   return { target, approvedWith }
 }
 
-/** A target that never completes — always re-suspends for the same approval. */
 const alwaysSuspendingTarget = (): {
   target: TargetAgentDriver
   approveCalls: () => number
@@ -109,8 +105,17 @@ const alwaysSuspendingTarget = (): {
 }
 
 const base = {
-  actor: { email: 'pm@example.com', name: 'Priya', personality: 'concise' },
-  actorName: 'Priya',
+  persona: {
+    id: 'priya',
+    email: 'priya@personas.local',
+    name: 'Priya',
+    personality: 'concise',
+    roles: [],
+    goals: [],
+    tags: [],
+    runnable: true,
+  },
+  personaId: 'priya',
   agentName: 'todoBot',
   task: 'Get a todo created',
   evaluate: 'A todo now exists',

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

@@ -4,7 +4,7 @@ import type {
   TargetAgentDriver,
   TargetPendingApproval,
 } from './actor-flow.types.js'
-import type { ScenarioActorConfig } from '../../services/scenario-actors-service.js'
+import type { ResolvedPersona } from '../../services/personas-service.js'
 import type { AIMessage } from '../ai-agent/ai-agent.types.js'
 import type {
   AIAgentRunnerParams,
@@ -61,10 +61,10 @@ export type ActorLLM = (
 ) => Promise<AIAgentStepResult>
 
 export interface RunConversationParams {
-  /** The actor's own config (personality/jobTitle/name), which shapes how it talks. */
-  actor: ScenarioActorConfig
-  /** Stable actor name (for transcript labelling). */
-  actorName: string
+  /** The person being played — name, job title, personality. */
+  persona: ResolvedPersona
+  /** The id they were declared under (for transcript labelling). */
+  personaId: string
   /** What the actor is trying to get the target agent to accomplish. */
   task: string
   /** Natural-language success criterion the actor evaluates at the end. */
@@ -109,16 +109,23 @@ function readObject<T>(result: { object?: unknown; text?: string }): T | null {
   return null
 }
 
-function actorInstructions(actor: ScenarioActorConfig, task: string): string {
+function actorInstructions(persona: ResolvedPersona, task: string): string {
   return [
     `You are role-playing a real user interacting with an AI assistant. Stay in character at all times — you are the user, not the assistant.`,
-    actor.name ? `Your name is ${actor.name}.` : '',
-    actor.jobTitle ? `Your role: ${actor.jobTitle}.` : '',
-    actor.personality
-      ? `Your personality and communication style: ${actor.personality}. Match this tone, vocabulary, and level of detail exactly.`
+    `Your name is ${persona.name}.`,
+    persona.jobTitle ? `Your role: ${persona.jobTitle}.` : '',
+    persona.personality
+      ? `Your personality and communication style: ${persona.personality}. Match this tone, vocabulary, and level of detail exactly.`
       : '',
     `Your goal in this conversation: ${task}.`,
     `Send one message at a time. Set "done" to true only once your goal is clearly accomplished, or clearly impossible.`,
+    // Every call the actor makes wants a schema'd object back, and a gateway
+    // that cannot take a JSON *schema* degrades to OpenAI's `json_object`
+    // mode — which refuses the request outright unless the word "json" appears
+    // somewhere in the prompt. Saying it once here covers all three call sites
+    // (turn, approvals, verdict), since each builds on these instructions, and
+    // it costs nothing on providers that never needed telling.
+    `Reply with json matching the schema you are given, and nothing else.`,
   ]
     .filter(Boolean)
     .join('\n')
@@ -215,7 +222,7 @@ export async function runConversation(
   params: RunConversationParams
 ): Promise<ActorFlowVerdict> {
   const maxTurns = params.maxTurns ?? DEFAULT_MAX_TURNS
-  const instructions = actorInstructions(params.actor, params.task)
+  const instructions = actorInstructions(params.persona, params.task)
   // Seed a kickoff so the very first actor turn has a non-empty message list
   // (providers reject an empty prompt). It's an instruction TO the actor, so
   // it never appears in the transcript.
@@ -245,7 +252,7 @@ export async function runConversation(
     }
 
     actorMessages.push(msg('assistant', actorMessage))
-    transcript.push(`${params.actorName}: ${actorMessage}`)
+    transcript.push(`${params.persona.name}: ${actorMessage}`)
 
     const reply = await converseWithTarget(params, instructions, actorMessage)
     actorMessages.push(msg('user', reply.text ?? ''))

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

@@ -562,8 +562,8 @@ describe('wrapChannelWithAGUI — Pikku CUSTOM events', () => {
   })
 })
 
-describe('wrapChannelWithAGUI — silently dropped events', () => {
-  it('drops audio-delta without emitting anything', () => {
+describe('wrapChannelWithAGUI — speech', () => {
+  it('forwards audio-delta as a CUSTOM event', () => {
     const { channel, events } = makeChannel()
     const wrapped = wrapChannelWithAGUI(channel)
 
@@ -573,16 +573,57 @@ describe('wrapChannelWithAGUI — silently dropped events', () => {
       format: 'mp3',
     } as AIStreamEvent)
 
-    assert.equal(events.length, 0)
+    // AG-UI has no speech event, but dropping it makes a voice agent reached
+    // over HTTP inaudible: every sentence is synthesized and billed, then
+    // thrown away here.
+    const custom = find(events, 'CUSTOM', 'pikku:audio-delta')
+    assert.ok(custom)
+    assert.deepEqual(custom.value, { data: 'base64abc', format: 'mp3' })
   })
 
-  it('drops audio-done without emitting anything', () => {
+  it('forwards audio-done as a CUSTOM event', () => {
     const { channel, events } = makeChannel()
     const wrapped = wrapChannelWithAGUI(channel)
 
     wrapped.send({ type: 'audio-done' } as AIStreamEvent)
 
-    assert.equal(events.length, 0)
+    assert.ok(find(events, 'CUSTOM', 'pikku:audio-done'))
+  })
+
+  it('forwards the transcript as a CUSTOM event', () => {
+    const { channel, events } = makeChannel()
+    const wrapped = wrapChannelWithAGUI(channel)
+
+    wrapped.send({
+      type: 'transcript',
+      text: 'what the user said',
+    } as AIStreamEvent)
+
+    // The client sent audio, so this is the only way it learns what its own
+    // turn was. Dropped, the user's message renders as an empty bubble.
+    const custom = find(events, 'CUSTOM', 'pikku:transcript')
+    assert.ok(custom)
+    assert.deepEqual(custom.value, { text: 'what the user said' })
+  })
+
+  it('leaves an open text message open, so speech cannot split a reply', () => {
+    const { channel, events } = makeChannel()
+    const wrapped = wrapChannelWithAGUI(channel)
+
+    wrapped.send({ type: 'text-delta', text: 'hello' } as AIStreamEvent)
+    wrapped.send({
+      type: 'audio-delta',
+      data: 'abc',
+      format: 'mp3',
+    } as AIStreamEvent)
+    wrapped.send({ type: 'text-delta', text: ' there' } as AIStreamEvent)
+
+    // Audio arrives interleaved with the text it is saying. Ending the message
+    // around it would render one reply as several.
+    const starts = events.filter(
+      (event: any) => event.type === 'TEXT_MESSAGE_START'
+    )
+    assert.equal(starts.length, 1)
   })
 })
 
@@ -642,11 +683,6 @@ describe('wrapChannelWithAGUI — channel proxy', () => {
   })
 })
 
-/**
- * Replicates the ordering rules enforced by @ag-ui/client's verifyEvents so
- * the bridge's output is checked against the same contract the browser
- * applies. Throws on the first violation.
- */
 function assertClientAcceptsStream(events: any[]): void {
   let started = false
   let finished = false
@@ -1109,3 +1145,48 @@ describe('wrapChannelWithAGUI — late-bound runId', () => {
     assert.equal(started.runId, find(fallback.events, 'RUN_FINISHED').runId)
   })
 })
+
+describe('wrapChannelWithAGUI — interruption', () => {
+  it('closes the open text message and forwards the fragment as a custom event', () => {
+    const { channel, events } = makeChannel()
+    const wrapped = wrapChannelWithAGUI(channel, { threadId: 't', runId: 'r' })
+
+    wrapped.send({
+      type: 'text-delta',
+      text: 'I will delete the ',
+    } as AIStreamEvent)
+    wrapped.send({
+      type: 'interrupted',
+      runId: 'r',
+      text: 'I will delete the ',
+      reason: 'speech',
+    } as AIStreamEvent)
+
+    // Leaving TEXT_MESSAGE_END unsent would strand the assistant bubble in a
+    // streaming state that never resolves.
+    assert.ok(types(events).includes('TEXT_MESSAGE_END'))
+    const custom = find(events, 'CUSTOM', 'pikku:interrupted')
+    assert.deepEqual(custom.value, {
+      runId: 'r',
+      text: 'I will delete the ',
+      reason: 'speech',
+    })
+  })
+
+  it('still ends the run exactly once, so an interrupted run is not terminal on its own', () => {
+    const { channel, events } = makeChannel()
+    const wrapped = wrapChannelWithAGUI(channel, { threadId: 't', runId: 'r' })
+
+    wrapped.send({ type: 'text-delta', text: 'partial' } as AIStreamEvent)
+    wrapped.send({
+      type: 'interrupted',
+      runId: 'r',
+      text: 'partial',
+      reason: 'speech',
+    } as AIStreamEvent)
+    wrapped.send({ type: 'done' } as AIStreamEvent)
+
+    assert.equal(events.filter((e: any) => e.type === 'RUN_FINISHED').length, 1)
+    assert.equal(events.filter((e: any) => e.type === 'RUN_ERROR').length, 0)
+  })
+})