@pikku/core 0.12.79 → 0.12.82

package/src/types/core.types.ts

@@ -188,8 +188,6 @@ export type FunctionRuntimeMeta = {
   audit?: {
     durability: AuditDurability
   }
-  /** Keeps the full `SecretService`. Set by the inspector, read by the runner. */
-  secretBroker?: boolean
   version?: number
   approvalRequired?: boolean
   approvalDescription?: string
@@ -298,6 +296,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 +381,10 @@ export type PikkuWire<
   MCPTools extends string | never = never,
   TypedWorkflow extends PikkuWorkflowWire | never = PikkuWorkflowWire,
   TriggerOutput = unknown,
-  TypedScenario extends PikkuScenarioWire | never = PikkuScenarioWire,
+  // `any`, not `Out`: the emitted `TypedScenario<Out>` supplies the real
+  // context, and this default is what other generics constrain against. See
+  // `ScenarioContext`.
+  TypedScenario extends PikkuScenarioWire<any> | never = PikkuScenarioWire<any>,
   TypedActors extends ScenarioPersonas = ScenarioPersonas,
 > = {
   /** Always present — lazily initialised on first access for every function invocation */
@@ -386,6 +392,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

@@ -29,6 +29,10 @@ import type {
   CoreAIAgent,
   AIAgentMeta,
 } from '../wirings/ai-agent/ai-agent.types.js'
+import type {
+  PikkuAIScorer,
+  ScorerMeta,
+} from '../wirings/ai-scorer/ai-scorer.types.js'
 import type {
   CoreGateway,
   GatewaysMeta,
@@ -98,6 +102,10 @@ export interface PikkuPackageState {
         variableOverrides?: Record<string, string>
         /** Per-instance name-aliases: logical name the addon reads -> actual project credential name */
         credentialOverrides?: Record<string, string>
+        /** Why this instance gets the whole `SecretService` rather than one scoped to its declared secrets */
+        globalSecrets?: string
+        /** Why this instance gets the whole `CredentialService` rather than one scoped to its declared credentials */
+        globalCredentials?: string
         /** Set by `wireRemoteAddon`: this namespace is consumed remotely over HTTP, not bundled */
         remote?: boolean
         /** Remote host base URL (wireRemoteAddon) — string or resolver over singleton services */
@@ -119,7 +127,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: {
@@ -153,6 +161,10 @@ export interface PikkuPackageState {
   agent: {
     agents: Map<string, CoreAIAgent>
     agentsMeta: AIAgentMeta
+    scorers: Map<string, PikkuAIScorer>
+    scorersMeta: ScorerMeta
+    /** Alias -> `provider/model`, from the `models` table in pikku.config.json. */
+    modelAliases: Record<string, string>
   }
   gateway: {
     gateways: Map<string, CoreGateway>
@@ -204,5 +216,9 @@ export interface PikkuPackageState {
       { name: string; displayName: string; type: string; oauth2?: boolean }
     > | null
     requiredParentServices: string[] | null
+    /** The secret keys this package is allowed to read, emitted by the CLI from
+     *  what the package declares and is seen to read. `null` when the package
+     *  was never analysed, which scopes it to nothing. */
+    declaredSecrets: string[] | null
   }
 }

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

@@ -1,9 +1,6 @@
 export type {
-  ActorFlowApprovalPolicy,
   ActorFlowVerdict,
   ConverseOptions,
-  TargetAgentReply,
-  TargetPendingApproval,
   TargetAgentDriver,
 } from './actor-flow.types.js'
 export {

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-finalize.test.ts

@@ -0,0 +1,186 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+import {
+  applyOutputMiddleware,
+  finalizeAgentRun,
+  type FinalizedRun,
+} from './ai-agent-finalize.js'
+import type { AIAgentStep, PikkuAIMiddlewareHooks } from './ai-agent.types.js'
+import type { AIRunStateService } from '../../services/ai-run-state-service.js'
+
+const step = (
+  toolCalls: NonNullable<AIAgentStep['toolCalls']>
+): AIAgentStep => ({
+  usage: { inputTokens: 0, outputTokens: 0 },
+  toolCalls,
+})
+
+const call = (name: string, result: string) => ({
+  name,
+  args: {} as Record<string, unknown>,
+  result,
+})
+
+describe('applyOutputMiddleware', () => {
+  test('hands the middleware every tool call the run made, flattened across steps', async () => {
+    const seen: string[][] = []
+    const middleware: PikkuAIMiddlewareHooks[] = [
+      {
+        modifyOutput: (_services, ctx) => {
+          seen.push(ctx.toolCalls.map((c) => c.name))
+          return { text: ctx.text, messages: ctx.messages }
+        },
+      },
+    ]
+
+    await applyOutputMiddleware(
+      middleware,
+      {},
+      {
+        text: 'done',
+        messages: [],
+        steps: [step([call('search', 'a')]), step([call('fetch', 'b')])],
+        usage: { inputTokens: 1, outputTokens: 2 },
+      }
+    )
+
+    assert.deepEqual(seen, [['search', 'fetch']])
+  })
+
+  test('a rewritten tool call is redistributed back onto the step it came from', async () => {
+    const middleware: PikkuAIMiddlewareHooks[] = [
+      {
+        modifyOutput: (_services, ctx) => ({
+          text: ctx.text,
+          messages: ctx.messages,
+          toolCalls: ctx.toolCalls.map((c) => ({ ...c, result: '[redacted]' })),
+        }),
+      },
+    ]
+
+    const { steps } = await applyOutputMiddleware(
+      middleware,
+      {},
+      {
+        text: 'done',
+        messages: [],
+        steps: [
+          step([call('search', 'secret')]),
+          step([call('fetch', 'token')]),
+        ],
+        usage: { inputTokens: 0, outputTokens: 0 },
+      }
+    )
+
+    assert.deepEqual(
+      steps.map((s) => s.toolCalls?.map((c) => [c.name, c.result])),
+      [[['search', '[redacted]']], [['fetch', '[redacted]']]]
+    )
+  })
+
+  test('dropping a tool call collapses the calls into the last step rather than mis-attributing them', async () => {
+    const middleware: PikkuAIMiddlewareHooks[] = [
+      {
+        modifyOutput: (_services, ctx) => ({
+          text: ctx.text,
+          messages: ctx.messages,
+          toolCalls: ctx.toolCalls.filter((c) => c.name !== 'search'),
+        }),
+      },
+    ]
+
+    const { steps } = await applyOutputMiddleware(
+      middleware,
+      {},
+      {
+        text: 'done',
+        messages: [],
+        steps: [step([call('search', 'a')]), step([call('fetch', 'b')])],
+        usage: { inputTokens: 0, outputTokens: 0 },
+      }
+    )
+
+    assert.deepEqual(
+      steps.map((s) => s.toolCalls?.map((c) => c.name)),
+      [[], ['fetch']]
+    )
+  })
+
+  test('runs the chain in reverse registration order, each hook seeing the previous rewrite', async () => {
+    const order: string[] = []
+    const middleware: PikkuAIMiddlewareHooks[] = [
+      {
+        modifyOutput: (_services, ctx) => {
+          order.push(`first saw ${ctx.text}`)
+          return { text: `${ctx.text}+first`, messages: ctx.messages }
+        },
+      },
+      {
+        modifyOutput: (_services, ctx) => {
+          order.push(`second saw ${ctx.text}`)
+          return { text: `${ctx.text}+second`, messages: ctx.messages }
+        },
+      },
+    ]
+
+    const { text } = await applyOutputMiddleware(
+      middleware,
+      {},
+      {
+        text: 'raw',
+        messages: [],
+        steps: [],
+        usage: { inputTokens: 0, outputTokens: 0 },
+      }
+    )
+
+    assert.deepEqual(order, ['second saw raw', 'first saw raw+second'])
+    assert.equal(text, 'raw+second+first')
+  })
+})
+
+describe('finalizeAgentRun', () => {
+  const run = (usage: FinalizedRun['usage']): FinalizedRun => ({
+    runId: 'run-1',
+    agentName: 'assistant',
+    threadId: 'thread-1',
+    input: 'what is the capital of France?',
+    text: 'done',
+    steps: [],
+    usage,
+  })
+
+  test('completes the run and records its usage', async () => {
+    const updates: unknown[] = []
+    const aiRunState = {
+      updateRun: async (_runId: string, update: unknown) => {
+        updates.push(update)
+      },
+    } as unknown as AIRunStateService
+
+    await finalizeAgentRun(
+      aiRunState,
+      run({ inputTokens: 10, outputTokens: 20, model: 'gpt-4o' })
+    )
+
+    assert.deepEqual(updates, [
+      {
+        status: 'completed',
+        usage: { inputTokens: 10, outputTokens: 20, model: 'gpt-4o' },
+      },
+    ])
+  })
+
+  test('omits usage entirely when no model reported one', async () => {
+    const updates: any[] = []
+    const aiRunState = {
+      updateRun: async (_runId: string, update: unknown) => {
+        updates.push(update)
+      },
+    } as unknown as AIRunStateService
+
+    await finalizeAgentRun(aiRunState, run({ inputTokens: 0, outputTokens: 0 }))
+
+    assert.deepEqual(updates, [{ status: 'completed' }])
+  })
+})

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

@@ -0,0 +1,197 @@
+import type {
+  AIAgentStep,
+  AIMessage,
+  PikkuAIMiddlewareHooks,
+} from './ai-agent.types.js'
+import type { AIRunStateService } from '../../services/ai-run-state-service.js'
+import { pikkuState } from '../../pikku-state.js'
+import { scoreFinishedRun } from '../ai-scorer/ai-scorer-live.js'
+import { recordScoreSnapshot } from '../ai-scorer/ai-scorer-snapshots.js'
+
+export type RunUsage = {
+  inputTokens: number
+  outputTokens: number
+  model?: string
+}
+
+/**
+ * Everything a finished run produced, after all middleware has had its say.
+ *
+ * One snapshot feeds persistence and anything that grades the run, so that what
+ * a scorer is shown is exactly what was stored — including the redactions.
+ */
+export type FinalizedRun = {
+  runId: string
+  agentName: string
+  threadId: string
+  resourceId?: string
+  /** The prompt the run answered — what a scorer grades the answer against. */
+  input: string
+  text: string
+  steps: AIAgentStep[]
+  usage: RunUsage
+}
+
+/**
+ * The prompt a run answered: the most recent user turn, which is what the model
+ * was last asked. On a resumed run the earlier turns are context, not the ask.
+ */
+export const lastUserMessageText = (messages: AIMessage[]): string => {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i]
+    if (message?.role !== 'user') continue
+    if (typeof message.content === 'string') return message.content
+    if (Array.isArray(message.content)) {
+      return message.content
+        .filter((part) => part.type === 'text')
+        .map((part) => (part as { text: string }).text)
+        .join('\n')
+    }
+  }
+  return ''
+}
+
+const flattenToolCalls = (
+  steps: AIAgentStep[]
+): NonNullable<AIAgentStep['toolCalls']> =>
+  steps.flatMap((step) => step.toolCalls ?? [])
+
+/**
+ * Push a rewritten flat tool-call list back onto the steps it came from,
+ * preserving the step boundaries. A hook that adds or drops calls would make
+ * the boundaries meaningless, so a length change collapses them into the last
+ * step rather than silently mis-attributing calls to the wrong step.
+ */
+const distributeToolCalls = (
+  steps: AIAgentStep[],
+  toolCalls: NonNullable<AIAgentStep['toolCalls']>
+): AIAgentStep[] => {
+  if (toolCalls.length !== flattenToolCalls(steps).length) {
+    return steps.map((step, index) => ({
+      ...step,
+      toolCalls: index === steps.length - 1 ? toolCalls : [],
+    }))
+  }
+
+  let cursor = 0
+  return steps.map((step) => {
+    if (!step.toolCalls) return step
+    const next = toolCalls.slice(cursor, cursor + step.toolCalls.length)
+    cursor += step.toolCalls.length
+    return { ...step, toolCalls: next }
+  })
+}
+
+/**
+ * Run the `modifyOutput` chain over a finished non-streaming run.
+ *
+ * Reverse order, matching the input chain: the middleware registered first
+ * wraps the others, so it sees the output last.
+ */
+export const applyOutputMiddleware = async (
+  aiMiddlewares: PikkuAIMiddlewareHooks[],
+  singletonServices: any,
+  input: {
+    text: string
+    messages: AIMessage[]
+    steps: AIAgentStep[]
+    usage: { inputTokens: number; outputTokens: number }
+  }
+): Promise<{ text: string; messages: AIMessage[]; steps: AIAgentStep[] }> => {
+  let text = input.text
+  let messages = input.messages
+  let steps = input.steps
+  let toolCalls = flattenToolCalls(steps)
+
+  for (let i = aiMiddlewares.length - 1; i >= 0; i--) {
+    const mw = aiMiddlewares[i]
+    if (!mw.modifyOutput) continue
+    const result = await mw.modifyOutput(singletonServices, {
+      text,
+      messages,
+      usage: {
+        inputTokens: input.usage.inputTokens,
+        outputTokens: input.usage.outputTokens,
+      },
+      toolCalls,
+    })
+    text = result.text
+    messages = result.messages
+    if (result.toolCalls) {
+      toolCalls = result.toolCalls
+      steps = distributeToolCalls(steps, toolCalls)
+    }
+  }
+
+  return { text, messages, steps }
+}
+
+/**
+ * The one place a run ends successfully.
+ *
+ * Every path that completes a run — streamed, non-streamed, and resumed after a
+ * tool approval — goes through here, so that anything terminal is reachable
+ * from all of them and cannot be reordered by a middleware author. Nothing here
+ * may rewrite the run: by this point the output middleware has resolved and, on
+ * the streaming path, the client already has the reply.
+ */
+export const finalizeAgentRun = async (
+  aiRunState: AIRunStateService,
+  run: FinalizedRun
+): Promise<void> => {
+  await aiRunState.updateRun(run.runId, {
+    status: 'completed',
+    ...(run.usage.model
+      ? {
+          usage: {
+            inputTokens: run.usage.inputTokens,
+            outputTokens: run.usage.outputTokens,
+            model: run.usage.model,
+          },
+        }
+      : {}),
+  })
+
+  // Read rather than `getSingletonServices()`: a process that never registered
+  // them grades nothing, which is not an error at the point a run has already
+  // succeeded.
+  const services = pikkuState(null, 'package', 'singletonServices')
+  if (!services) return
+
+  const snapshot = {
+    runId: run.runId,
+    agentName: run.agentName,
+    threadId: run.threadId,
+    ...(run.resourceId !== undefined ? { resourceId: run.resourceId } : {}),
+    input: run.input,
+    output: run.text,
+    toolCalls: run.steps.flatMap((step) =>
+      (step.toolCalls ?? []).map((call) => ({
+        name: call.name,
+        args: call.args,
+        result: call.result,
+        ...(call.error !== undefined ? { error: call.error } : {}),
+      }))
+    ),
+    usage: {
+      inputTokens: run.usage.inputTokens,
+      outputTokens: run.usage.outputTokens,
+      ...(run.usage.model !== undefined ? { model: run.usage.model } : {}),
+    },
+  }
+
+  // The same object a scenario grades, so an asserted score and a sampled one
+  // are the same measurement. A no-op unless a dev server turned retention on.
+  recordScoreSnapshot(snapshot)
+
+  // Best-effort and last: the client already has its answer, so a grading
+  // failure must not surface as a failed run.
+  try {
+    await scoreFinishedRun(snapshot, services)
+  } catch (error) {
+    services.logger?.error(
+      `[pikku] Live scoring failed for run ${run.runId}`,
+      error
+    )
+  }
+}

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-interrupt.ts

@@ -381,6 +381,7 @@ export const persistOrphanedToolResults = async (
           : typeof entry.result === 'string'
             ? entry.result
             : JSON.stringify(entry.result),
+        ...(entry.error ? { error: entry.error } : {}),
       })),
       undelivered: true,
       createdAt: new Date(),