@pikku/core 0.12.79 → 0.12.80

package/src/types/core.types.ts

@@ -298,6 +298,11 @@ export interface CoreUserSession {
    * Populated by whoever builds the session — core reads them, never fetches.
    */
   scopes?: string[]
+  /**
+   * Restricts the session to functions declared `readonly`. The function runner
+   * throws `ReadonlySessionError` for anything else.
+   */
+  readonly?: boolean
 }
 
 /**
@@ -378,7 +383,11 @@ export type PikkuWire<
   MCPTools extends string | never = never,
   TypedWorkflow extends PikkuWorkflowWire | never = PikkuWorkflowWire,
   TriggerOutput = unknown,
-  TypedScenario extends PikkuScenarioWire | never = PikkuScenarioWire,
+  // Defaulted to `any` rather than to `Out`: the emitted `TypedScenario<Out>`
+  // supplies the real context, while `PikkuWire`'s own defaults are what other
+  // generics constrain against — and a constraint that pinned the context to
+  // `Out` would reject every wire whose scenario output is anything else.
+  TypedScenario extends PikkuScenarioWire<any> | never = PikkuScenarioWire<any>,
   TypedActors extends ScenarioPersonas = ScenarioPersonas,
 > = {
   /** Always present — lazily initialised on first access for every function invocation */
@@ -386,6 +395,11 @@ export type PikkuWire<
 } & Partial<{
   wireType: PikkuWiringTypes
   wireId: string
+  /**
+   * A logger scoped to this invocation, when a host attaches one. Core never
+   * sets it; services that log fall back to the singleton logger.
+   */
+  logger: Logger
   /** Trace ID for distributed tracing — propagated across remote RPC calls via x-trace-id header */
   traceId: string
   functionId: string

package/src/types/state.types.ts

@@ -119,7 +119,7 @@ export interface PikkuPackageState {
     meta: HTTPWiringsMeta
   }
   channel: {
-    channels: Map<string, CoreChannel<any, any>>
+    channels: Map<string, CoreChannel<any, any, any, any, any>>
     meta: ChannelsMeta
   }
   scheduler: {

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

@@ -119,12 +119,7 @@ function actorInstructions(persona: ResolvedPersona, task: string): string {
       : '',
     `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.
+    // knowledge: decisions/internals/the-actor-prompt-says-json-because-of-json-object-mode.md
     `Reply with json matching the schema you are given, and nothing else.`,
   ]
     .filter(Boolean)

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

@@ -0,0 +1,120 @@
+import type { PikkuRawWire } from '../../types/core.types.js'
+import type { SessionService } from '../../services/user-session-service.js'
+import type { CoreUserSession } from '../../types/core.types.js'
+import type { PikkuRPC } from '../rpc/rpc-types.js'
+import type { AIAgentInput, AIStreamChannel } from './ai-agent.types.js'
+import type { StreamAIAgentOptions } from './ai-agent-prepare.js'
+import { runAIAgent, resumeAIAgentSync } from './ai-agent-runner.js'
+import {
+  streamAIAgent,
+  resumeAIAgent,
+  interruptAIAgent,
+} from './ai-agent-stream.js'
+import { wrapChannelWithAGUI } from './ai-agent-agui.js'
+
+export type AgentRPCOptions = {
+  sessionService?: SessionService<CoreUserSession>
+}
+
+/**
+ * `wire.rpc.agent`, implemented.
+ *
+ * Lives here rather than in `rpc-runner` so the agent surface is one file next
+ * to the runner and stream code it delegates to, instead of a wing of the RPC
+ * primitive.
+ */
+export const createAgentRPC = (
+  wire: PikkuRawWire,
+  options: AgentRPCOptions
+): PikkuRPC['agent'] => {
+  const params = () => ({
+    sessionService: options.sessionService,
+    getCredential: wire.getCredential?.bind(wire),
+  })
+
+  const streamingChannel = (): AIStreamChannel => {
+    const channel = wire.channel as unknown as AIStreamChannel | undefined
+    if (!channel) throw new Error('No channel available for streaming')
+    return channel
+  }
+
+  /** `run` and `approve` return the same shape; only the call differs. */
+  const asRunResult = (result: Awaited<ReturnType<typeof runAIAgent>>) => ({
+    runId: result.runId,
+    result: result.object ?? result.text,
+    usage: result.usage,
+    ...(result.status === 'suspended' && {
+      status: 'suspended' as const,
+      pendingApprovals: result.pendingApprovals,
+    }),
+  })
+
+  return {
+    run: async (agentName: string, input: AIAgentInput) =>
+      asRunResult(await runAIAgent(agentName, input, params())),
+
+    stream: async (
+      agentName: string,
+      input: {
+        message: string
+        threadId: string
+        resourceId: string
+        model?: string
+        temperature?: number
+      },
+      streamOptions?: StreamAIAgentOptions
+    ) => {
+      let currentRunId: string | undefined
+      await streamAIAgent(
+        agentName,
+        input,
+        wrapChannelWithAGUI(streamingChannel(), {
+          threadId: input.threadId,
+          getRunId: () => currentRunId,
+        }),
+        params(),
+        undefined,
+        {
+          ...streamOptions,
+          onRunCreated: (runId) => {
+            currentRunId = runId
+            streamOptions?.onRunCreated?.(runId)
+          },
+        }
+      )
+    },
+
+    resume: async (
+      runId: string,
+      input: { toolCallId: string; approved: boolean },
+      streamOptions?: StreamAIAgentOptions
+    ) => {
+      await resumeAIAgent(
+        { runId, ...input },
+        wrapChannelWithAGUI(streamingChannel(), { runId }),
+        params(),
+        streamOptions
+      )
+    },
+
+    interrupt: async (runId: string, reason?: 'speech' | 'user' | 'timeout') =>
+      interruptAIAgent(
+        { runId, ...(reason ? { reason } : {}) },
+        { sessionService: options.sessionService }
+      ),
+
+    approve: async (
+      runId: string,
+      approvals: { toolCallId: string; approved: boolean }[],
+      expectedAgentName?: string
+    ) =>
+      asRunResult(
+        await resumeAIAgentSync(
+          runId,
+          approvals,
+          { sessionService: options.sessionService },
+          expectedAgentName
+        )
+      ),
+  }
+}

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

@@ -372,11 +372,7 @@ export function wrapChannelWithAGUI(
           break
         }
 
-        // AG-UI has no event for speech, so it travels as CUSTOM like the other
-        // pikku-specific ones. Dropping it instead — which is what this did —
-        // means a voice agent reached over HTTP is inaudible: `voiceOutput`
-        // synthesizes every sentence, the provider bills for it, and nothing
-        // gets past the mapper.
+        // knowledge: decisions/internals/agent-speech-travels-as-a-custom-agui-event.md
         case 'audio-delta': {
           send({
             type: 'CUSTOM',

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

@@ -574,7 +574,7 @@ describe('non-streaming agent interruption', () => {
         updateRun: async (_runId: string, patch: unknown) => {
           updates.push(patch)
         },
-        resolveApproval: async () => {},
+        resolveApproval: async () => true,
       },
     } as any)
 
@@ -648,6 +648,7 @@ describe('streaming resume interruption', () => {
         // for approvals that have already been given.
         resolveApproval: async () => {
           run.pendingApprovals = []
+          return true
         },
       },
     } as any)

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

@@ -19,7 +19,14 @@ export function resolveMemoryServices(
 } {
   const memoryConfig = agent.memory
   const storage = memoryConfig?.storage
-    ? (singletonServices as any)[memoryConfig.storage]
+    ? // The service is named by string in agent config, so the lookup cannot be
+      // checked — only the shape it is required to have.
+      (
+        singletonServices as unknown as Record<
+          string,
+          AIStorageService | undefined
+        >
+      )[memoryConfig.storage]
     : singletonServices.aiStorage
   return { storage }
 }

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

@@ -12,7 +12,11 @@ import type {
 } from './ai-agent.types.js'
 import type { AIAgentRunnerParams } from '../../services/ai-agent-runner-service.js'
 import { PikkuError } from '../../errors/error-handler.js'
-import { checkAuthPermissions, runPermissions } from '../../permissions.js'
+import {
+  checkAuthPermissions,
+  runPermissions,
+  type PermissionWire,
+} from '../../permissions.js'
 import { AIProviderNotConfiguredError } from '../../errors/errors.js'
 import { ForbiddenError } from '../../errors/errors.js'
 import { verifyScopes } from '../../scopes.js'
@@ -319,8 +323,8 @@ export async function assertAgentAuthorized(
 
   await runPermissions({
     funcPermissions: agent.permissions,
-    services: singletonServices as any,
-    wire: wire as any,
+    services: singletonServices,
+    wire: wire as PermissionWire,
     data: {},
     packageName,
     label: 'agent',
@@ -395,7 +399,7 @@ export function createScopedChannel(
           toolName: event.toolName,
           args: event.args,
           ...(event.reason !== undefined ? { reason: event.reason } : {}),
-          runId: (event as any).runId,
+          runId: event.runId,
         })
         return
       }
@@ -940,10 +944,7 @@ 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.
+    // knowledge: decisions/internals/agent-context-waits-for-a-tool-result-still-being-written.md
     await awaitPendingInterruptNote(threadId)
     messages = await storage.getMessages(threadId, {
       lastN: memoryConfig?.lastMessages ?? 20,
@@ -959,10 +960,7 @@ export async function prepareAgentRun(
 
   const userContent: AIMessage['content'] = input.attachments?.length
     ? [
-        // 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.
+        // knowledge: decisions/internals/an-empty-text-part-is-omitted-from-an-agent-message.md
         ...(input.message
           ? [{ type: 'text' as const, text: input.message }]
           : []),

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

@@ -43,6 +43,7 @@ const setup = (agentName: string, resourceId = 'u1') => {
       getRun: async () => suspendedRun(agentName, resourceId),
       resolveApproval: async (toolCallId: string) => {
         resolved.push(toolCallId)
+        return true
       },
     },
   } as any)

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

@@ -707,7 +707,7 @@ describe('resumeAIAgentSync', () => {
           createdAt: new Date(),
           updatedAt: new Date(),
         }),
-        resolveApproval: async () => {},
+        resolveApproval: async () => true,
         updateRun: async () => {},
       },
     } as any)
@@ -784,6 +784,7 @@ describe('resumeAIAgentSync', () => {
         },
         resolveApproval: async (toolCallId: string, status: string) => {
           resolveCalls.push({ toolCallId, status })
+          return true
         },
       },
       aiStorage: {
@@ -816,6 +817,84 @@ describe('resumeAIAgentSync', () => {
     ])
   })
 
+  test('an approver that loses the claim never runs the tool', async () => {
+    addTestAgent('claim-agent')
+    pikkuState(null, 'agent', 'agentsMeta')['claim-agent'].tools = ['refund']
+    pikkuState(null, 'rpc', 'meta').refund = 'refund'
+    pikkuState(null, 'function', 'meta').refund = {
+      description: 'Refund',
+      sessionless: true,
+    }
+
+    let executions = 0
+    pikkuState(null, 'function', 'functions').set('refund', {
+      func: async () => {
+        executions++
+        return { refunded: true }
+      },
+    })
+
+    const run: AgentRunState = {
+      runId: 'run-claim',
+      agentName: 'claim-agent',
+      threadId: 'thread-claim',
+      resourceId: 'resource-claim',
+      status: 'suspended',
+      suspendReason: 'approval',
+      pendingApprovals: [
+        {
+          type: 'tool-call',
+          toolCallId: 'tc-claim',
+          toolName: 'refund',
+          args: {},
+        },
+      ],
+      usage: { inputTokens: 0, outputTokens: 0, model: 'test/test-model' },
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    }
+
+    // Every concurrent approver reads the same `suspended` run with the same
+    // pending list; the store hands the claim to exactly one of them.
+    let claimsLeft = 1
+    pikkuState(null, 'package', 'singletonServices', {
+      logger: {
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        debug: () => {},
+      },
+      aiAgentRunner: {
+        run: async (): Promise<AIAgentStepResult> =>
+          makeStepResult({
+            text: 'Refunded',
+            usage: { inputTokens: 1, outputTokens: 1 },
+          }),
+      },
+      aiRunState: {
+        getRun: async () => run,
+        createRun: async () => 'unused',
+        updateRun: async () => {},
+        resolveApproval: async () => claimsLeft-- > 0,
+      },
+      aiStorage: {
+        saveMessages: async () => {},
+        getMessages: async () => [],
+      },
+    } as any)
+
+    const approvals = [{ toolCallId: 'tc-claim', approved: true }]
+    await resumeAIAgentSync('run-claim', approvals, asOwner('resource-claim'))
+    assert.equal(executions, 1, 'the winner ran the tool once')
+
+    await assert.rejects(
+      () =>
+        resumeAIAgentSync('run-claim', approvals, asOwner('resource-claim')),
+      /already resolved by another caller/
+    )
+    assert.equal(executions, 1, 'the loser did not run it a second time')
+  })
+
   test('records denied approvals and rejects agent mismatches', async () => {
     addTestAgent('resume-agent')
 
@@ -861,6 +940,7 @@ describe('resumeAIAgentSync', () => {
         updateRun: async () => {},
         resolveApproval: async (toolCallId: string, status: string) => {
           resolveCalls.push({ toolCallId, status })
+          return true
         },
       },
       aiStorage: {
@@ -959,7 +1039,7 @@ describe('resumeAIAgentSync', () => {
       },
       aiRunState: {
         getRun: async () => run,
-        resolveApproval: async () => {},
+        resolveApproval: async () => true,
         updateRun: async () => {},
       },
       aiStorage: {

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

@@ -43,6 +43,12 @@ import {
   trackToolExecution,
 } from './ai-agent-interrupt.js'
 import { pikkuState, getSingletonServices } from '../../pikku-state.js'
+import {
+  applyInputMiddleware,
+  describeApprovals,
+  notifyAfterStep,
+  toAccumulatedStep,
+} from './ai-agent-turn.js'
 import { resolveModelConfig } from './ai-agent-model-config.js'
 import { AIProviderNotConfiguredError } from '../../errors/errors.js'
 import { randomUUID } from './ai-agent-utils.js'
@@ -147,26 +153,20 @@ export async function runAIAgent(
   // 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) {
-    if (mw.modifyInput) {
-      const result = await mw.modifyInput(singletonServices, {
-        messages: modifiedMessages,
-        instructions: modifiedInstructions,
-        shared: sharedNotes,
-      })
-      modifiedMessages = result.messages
-      modifiedInstructions = result.instructions
-    }
-  }
+  const { messages: modifiedMessages, instructions: modifiedInstructions } =
+    await applyInputMiddleware(
+      aiMiddlewares,
+      singletonServices,
+      {
+        messages: runnerParams.messages,
+        instructions: runnerParams.instructions,
+      },
+      sharedNotes
+    )
   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.
+  // knowledge: decisions/internals/thread-history-records-the-transcript-not-the-audio.md
   const lastModified = modifiedMessages[modifiedMessages.length - 1]
   const persistedUserMessage =
     lastModified?.id === userMessage.id ? lastModified : userMessage
@@ -181,10 +181,7 @@ 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.
+  // knowledge: decisions/internals/a-non-streaming-agent-run-registers-with-airunstate-too.md
   const interruptHandle = registerInterruptibleRun(runId)
   runnerParams.abortSignal = interruptHandle.signal
   runnerParams.tools = trackToolExecution(runnerParams.tools, interruptHandle)
@@ -216,52 +213,15 @@ export async function runAIAgent(
       totalUsage.inputTokens += stepResult.usage.inputTokens
       totalUsage.outputTokens += stepResult.usage.outputTokens
 
-      for (const mw of aiMiddlewares) {
-        if (mw.afterStep) {
-          await mw.afterStep(singletonServices, {
-            stepNumber: step,
-            text: stepResult.text,
-            toolCalls: stepResult.toolCalls,
-            toolResults: stepResult.toolResults,
-            usage: stepResult.usage,
-            finishReason: stepResult.finishReason,
-          })
-        }
-      }
+      await notifyAfterStep(aiMiddlewares, singletonServices, step, stepResult)
 
-      accumulatedSteps.push({
-        usage: stepResult.usage,
-        toolCalls: stepResult.toolCalls.map((tc) => {
-          const tr = stepResult.toolResults.find(
-            (r) => r.toolCallId === tc.toolCallId
-          )
-          return {
-            name: tc.toolName,
-            args: tc.args as Record<string, unknown>,
-            result:
-              typeof tr?.result === 'string'
-                ? tr.result
-                : JSON.stringify(tr?.result ?? ''),
-          }
-        }),
-      })
+      accumulatedSteps.push(toAccumulatedStep(stepResult))
 
       if (stepResult.toolCalls.length === 0) break
 
       const approvalsNeeded = checkForApprovals(stepResult, runnerParams.tools)
       if (approvalsNeeded.length > 0) {
-        for (const approval of approvalsNeeded) {
-          const toolDef = runnerParams.tools.find(
-            (t) => t.name === approval.toolName
-          )
-          if (toolDef?.approvalDescriptionFn && !approval.reason) {
-            try {
-              approval.reason = await toolDef.approvalDescriptionFn(
-                approval.args
-              )
-            } catch {}
-          }
-        }
+        await describeApprovals(approvalsNeeded, runnerParams.tools)
 
         const pendingApprovals = approvalsNeeded.map((a) =>
           a.agentRunId
@@ -385,10 +345,7 @@ 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.
+    // knowledge: decisions/internals/an-agent-interrupt-is-not-a-failure.md
     const interruption = interruptHandle.interruption
     if (interruption || isAbortError(error)) {
       await aiRunState.updateRun(runId, { status: 'interrupted' })
@@ -470,11 +427,24 @@ export async function resumeAIAgentSync(
 
   const savedPendingApprovals = [...(run.pendingApprovals ?? [])]
 
+  // The read above is not a claim — concurrent resumes all see the same pending
+  // list. `resolveApproval` is the claim, and only the caller it returns true
+  // for may run the tool.
+  const claimedIds = new Set<string>()
   for (const { toolCallId, approved } of approvals) {
-    await aiRunState.resolveApproval(
+    const claimed = await aiRunState.resolveApproval(
       toolCallId,
       approved ? 'approved' : 'denied'
     )
+    if (claimed) {
+      claimedIds.add(toolCallId)
+    }
+  }
+
+  if (approvals.length > 0 && claimedIds.size === 0) {
+    throw new Error(
+      `Approvals for run ${runId} were already resolved by another caller`
+    )
   }
 
   const { tools } = await buildToolDefs(
@@ -498,6 +468,8 @@ export async function resumeAIAgentSync(
     if (pending.type !== 'tool-call') continue
 
     const toolCallId = pending.toolCallId
+    if (!claimedIds.has(toolCallId)) continue
+
     let resultStr: string
 
     if (rejectedIds.has(toolCallId)) {
@@ -623,19 +595,13 @@ async function continueAfterToolResultSync(
   // 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) {
-    if (mw.modifyInput) {
-      const result = await mw.modifyInput(singletonServices, {
-        messages: modifiedMessages,
-        instructions: modifiedInstructions,
-        shared: sharedNotes,
-      })
-      modifiedMessages = result.messages
-      modifiedInstructions = result.instructions
-    }
-  }
+  const { messages: modifiedMessages, instructions: modifiedInstructions } =
+    await applyInputMiddleware(
+      aiMiddlewares,
+      singletonServices,
+      { messages: trimmedMessages, instructions: instructions },
+      sharedNotes
+    )
 
   const { tools: resumeTools } = await buildToolDefs(
     params,
@@ -684,52 +650,15 @@ async function continueAfterToolResultSync(
       totalUsage.inputTokens += stepResult.usage.inputTokens
       totalUsage.outputTokens += stepResult.usage.outputTokens
 
-      for (const mw of aiMiddlewares) {
-        if (mw.afterStep) {
-          await mw.afterStep(singletonServices, {
-            stepNumber: step,
-            text: stepResult.text,
-            toolCalls: stepResult.toolCalls,
-            toolResults: stepResult.toolResults,
-            usage: stepResult.usage,
-            finishReason: stepResult.finishReason,
-          })
-        }
-      }
+      await notifyAfterStep(aiMiddlewares, singletonServices, step, stepResult)
 
-      accumulatedSteps.push({
-        usage: stepResult.usage,
-        toolCalls: stepResult.toolCalls.map((tc) => {
-          const tr = stepResult.toolResults.find(
-            (r) => r.toolCallId === tc.toolCallId
-          )
-          return {
-            name: tc.toolName,
-            args: tc.args as Record<string, unknown>,
-            result:
-              typeof tr?.result === 'string'
-                ? tr.result
-                : JSON.stringify(tr?.result ?? ''),
-          }
-        }),
-      })
+      accumulatedSteps.push(toAccumulatedStep(stepResult))
 
       if (stepResult.toolCalls.length === 0) break
 
       const approvalsNeeded = checkForApprovals(stepResult, runnerParams.tools)
       if (approvalsNeeded.length > 0) {
-        for (const approval of approvalsNeeded) {
-          const toolDef = runnerParams.tools.find(
-            (t) => t.name === approval.toolName
-          )
-          if (toolDef?.approvalDescriptionFn && !approval.reason) {
-            try {
-              approval.reason = await toolDef.approvalDescriptionFn(
-                approval.args
-              )
-            } catch {}
-          }
-        }
+        await describeApprovals(approvalsNeeded, runnerParams.tools)
 
         const pendingApprovals = approvalsNeeded.map((a) =>
           a.agentRunId
@@ -832,7 +761,7 @@ async function continueAfterToolResultSync(
       run.threadId,
       run.resourceId,
       memoryConfig,
-      null as any,
+      null,
       {
         ...result,
         text: outputText,