@pikku/core 0.12.83 → 0.12.86

package/src/wirings/{ai-agent/ai-agent-thread-ownership.test.ts → agent/agent-thread-ownership.test.ts}

@@ -2,10 +2,10 @@ import { beforeEach, describe, test } from 'node:test'
 import assert from 'node:assert/strict'
 
 import { resetPikkuState, pikkuState } from '../../pikku-state.js'
-import { runAIAgent, resumeAIAgentSync } from './ai-agent-runner.js'
+import { runAgent, resumeAgentSync } from './agent-runner.js'
 import { ForbiddenError } from '../../errors/errors.js'
-import type { AIMessage, CoreAIAgent } from './ai-agent.types.js'
-import type { AIAgentRunnerParams } from '../../services/ai-agent-runner-service.js'
+import type { AgentMessage, CoreAgent } from './agent.types.js'
+import type { AgentRunnerParams } from '../../services/agent-runner-service.js'
 
 const logger = {
   debug: () => {},
@@ -18,12 +18,12 @@ const sessionService = (session?: Record<string, unknown>) =>
   ({ get: () => session, setInitial: () => {}, sessionChanged: false }) as any
 
 const addTestAgent = (agentName: string) => {
-  const agent: CoreAIAgent = {
+  const agent: CoreAgent = {
     name: agentName,
     description: 'test agent',
     instructions: 'be helpful',
     model: 'test/test-model',
-  } as CoreAIAgent
+  } as CoreAgent
 
   pikkuState(null, 'agent', 'agentsMeta')[agentName] = {
     ...agent,
@@ -36,9 +36,9 @@ const addTestAgent = (agentName: string) => {
 
 type Harness = {
   threads: Map<string, { id: string; resourceId: string }>
-  messages: Map<string, AIMessage[]>
+  messages: Map<string, AgentMessage[]>
   created: Array<{ threadId: string; resourceId: string }>
-  modelSawMessages: AIMessage[][]
+  modelSawMessages: AgentMessage[][]
 }
 
 const createHarness = (
@@ -48,7 +48,7 @@ const createHarness = (
   const threads = new Map(
     seedThreads.map((t) => [t.threadId, { id: t.threadId, ...t }])
   )
-  const messages = new Map<string, AIMessage[]>(
+  const messages = new Map<string, AgentMessage[]>(
     Object.entries(seedMessages).map(([threadId, texts]) => [
       threadId,
       texts.map((text, index) => ({
@@ -60,7 +60,7 @@ const createHarness = (
     ])
   )
   const created: Harness['created'] = []
-  const modelSawMessages: AIMessage[][] = []
+  const modelSawMessages: AgentMessage[][] = []
 
   const storage = {
     getThread: async (threadId: string) => {
@@ -75,7 +75,7 @@ const createHarness = (
       return thread
     },
     getMessages: async (threadId: string) => messages.get(threadId) ?? [],
-    saveMessages: async (threadId: string, newMessages: AIMessage[]) => {
+    saveMessages: async (threadId: string, newMessages: AgentMessage[]) => {
       messages.set(threadId, [
         ...(messages.get(threadId) ?? []),
         ...newMessages,
@@ -87,9 +87,9 @@ const createHarness = (
 
   pikkuState(null, 'package', 'singletonServices', {
     logger,
-    aiStorage: storage,
-    aiAgentRunner: {
-      run: async (params: AIAgentRunnerParams) => {
+    agentStorage: storage,
+    agentRunner: {
+      run: async (params: AgentRunnerParams) => {
         modelSawMessages.push(params.messages)
         return {
           text: 'ok',
@@ -100,7 +100,7 @@ const createHarness = (
         }
       },
     },
-    aiRunState: {
+    agentRunState: {
       createRun: async () => 'run-1',
       updateRun: async () => {},
       getRun: async () => ({
@@ -135,7 +135,7 @@ describe('AI agent thread ownership without a session', () => {
 
     await assert.rejects(
       () =>
-        runAIAgent(
+        runAgent(
           'ownership-agent',
           {
             message: 'what did we discuss?',
@@ -160,11 +160,7 @@ describe('AI agent thread ownership without a session', () => {
 
     await assert.rejects(
       () =>
-        resumeAIAgentSync(
-          'run-1',
-          [{ toolCallId: 'tc-1', approved: true }],
-          {}
-        ),
+        resumeAgentSync('run-1', [{ toolCallId: 'tc-1', approved: true }], {}),
       (error: unknown) => error instanceof ForbiddenError
     )
   })
@@ -173,7 +169,7 @@ describe('AI agent thread ownership without a session', () => {
     addTestAgent('ownership-agent')
     const harness = createHarness()
 
-    const result = await runAIAgent(
+    const result = await runAgent(
       'ownership-agent',
       { message: 'hello', threadId: 'thread-new', resourceId: 'whatever' },
       {}
@@ -198,12 +194,12 @@ describe('AI agent thread ownership without a session', () => {
     const harness = createHarness()
     const requestParams = {}
 
-    await runAIAgent(
+    await runAgent(
       'ownership-agent',
       { message: 'first', threadId: 'thread-sub', resourceId: 'ignored' },
       requestParams
     )
-    await runAIAgent(
+    await runAgent(
       'ownership-agent',
       { message: 'second', threadId: 'thread-sub', resourceId: 'ignored' },
       requestParams
@@ -217,12 +213,12 @@ describe('AI agent thread ownership without a session', () => {
     addTestAgent('ownership-agent')
     const harness = createHarness()
 
-    await runAIAgent(
+    await runAgent(
       'ownership-agent',
       { message: 'hello', threadId: 'thread-a', resourceId: 'shared' },
       {}
     )
-    await runAIAgent(
+    await runAgent(
       'ownership-agent',
       { message: 'hello', threadId: 'thread-b', resourceId: 'shared' },
       {}
@@ -243,7 +239,7 @@ describe('AI agent thread ownership with a session', () => {
       { 'thread-alice': ['earlier alice turn'] }
     )
 
-    const result = await runAIAgent(
+    const result = await runAgent(
       'ownership-agent',
       {
         message: 'and then?',
@@ -265,7 +261,7 @@ describe('AI agent thread ownership with a session', () => {
     addTestAgent('ownership-agent')
     const harness = createHarness()
 
-    await runAIAgent(
+    await runAgent(
       'ownership-agent',
       { message: 'hello', threadId: 'thread-new', resourceId: 'project-1' },
       { sessionService: sessionService({ userId: 'alice' }) }
@@ -285,7 +281,7 @@ describe('AI agent thread ownership with a session', () => {
 
     await assert.rejects(
       () =>
-        runAIAgent(
+        runAgent(
           'ownership-agent',
           {
             message: 'what did we discuss?',

package/src/wirings/{ai-agent/ai-agent-turn.test.ts → agent/agent-turn.test.ts}

@@ -1,12 +1,10 @@
 import { describe, test } from 'node:test'
 import assert from 'node:assert/strict'
 
-import { toAccumulatedStep } from './ai-agent-turn.js'
-import type { AIAgentStepResult } from '../../services/ai-agent-runner-service.js'
+import { toAccumulatedStep } from './agent-turn.js'
+import type { AgentStepResult } from '../../services/agent-runner-service.js'
 
-const stepResult = (
-  overrides?: Partial<AIAgentStepResult>
-): AIAgentStepResult => ({
+const stepResult = (overrides?: Partial<AgentStepResult>): AgentStepResult => ({
   text: '',
   toolCalls: [],
   toolResults: [],

package/src/wirings/{ai-agent/ai-agent-turn.ts → agent/agent-turn.ts}

@@ -1,9 +1,9 @@
 import type { CoreSingletonServices } from '../../types/core.types.js'
-import type { PikkuAIMiddlewareHooks } from './ai-agent.types.js'
+import type { PikkuAgentMiddlewareHooks } from './agent.types.js'
 
 /** Exactly what `modifyInput` accepts and returns, taken from the hook itself. */
 type TurnInput = Pick<
-  Parameters<NonNullable<PikkuAIMiddlewareHooks['modifyInput']>>[1],
+  Parameters<NonNullable<PikkuAgentMiddlewareHooks['modifyInput']>>[1],
   'messages' | 'instructions'
 >
 
@@ -16,13 +16,13 @@ type TurnInput = Pick<
  * leaves the transcript there for `voiceOutput`).
  */
 export const applyInputMiddleware = async (
-  aiMiddlewares: PikkuAIMiddlewareHooks[],
+  agentMiddlewares: PikkuAgentMiddlewareHooks[],
   singletonServices: CoreSingletonServices,
   input: TurnInput,
   sharedNotes: Record<string, unknown>
 ): Promise<TurnInput> => {
   let { messages, instructions } = input
-  for (const mw of aiMiddlewares) {
+  for (const mw of agentMiddlewares) {
     if (!mw.modifyInput) continue
     const result = await mw.modifyInput(singletonServices, {
       messages,
@@ -37,7 +37,7 @@ export const applyInputMiddleware = async (
 
 /** The step fields both agent paths hand to `afterStep`, taken from the hook. */
 type StepResult = Omit<
-  Parameters<NonNullable<PikkuAIMiddlewareHooks['afterStep']>>[1],
+  Parameters<NonNullable<PikkuAgentMiddlewareHooks['afterStep']>>[1],
   'stepNumber'
 >
 
@@ -46,12 +46,12 @@ type StepResult = Omit<
  * ordinal — a hook that wants the run's totals accumulates them itself.
  */
 export const notifyAfterStep = async (
-  aiMiddlewares: PikkuAIMiddlewareHooks[],
+  agentMiddlewares: PikkuAgentMiddlewareHooks[],
   singletonServices: CoreSingletonServices,
   stepNumber: number,
   stepResult: StepResult
 ): Promise<void> => {
-  for (const mw of aiMiddlewares) {
+  for (const mw of agentMiddlewares) {
     if (!mw.afterStep) continue
     await mw.afterStep(singletonServices, {
       stepNumber,

package/src/wirings/agent/agent-utils.ts

@@ -0,0 +1,20 @@
+export const randomUUID = (): string => globalThis.crypto.randomUUID()
+
+/**
+ * The tool result stored and streamed when a user denies an approval.
+ *
+ * Two readers, one string. The model needs the sentence — it has to tell the
+ * user the action was declined and not retry it. A client needs to know a
+ * denial when it sees one, so it can render the call as denied rather than as
+ * a successful call that happened to return prose; that is what `approved`
+ * carries, and it is the same flag a client sets optimistically the moment the
+ * deny button is clicked. Emitting only the sentence made the two disagree:
+ * live the call showed denied, and on any re-render from storage the same call
+ * came back green.
+ */
+export const deniedToolResult = (): string =>
+  JSON.stringify({
+    approved: false,
+    message:
+      'The user explicitly declined this action. Inform them that it was declined and do not retry.',
+  })

package/src/wirings/{ai-agent/ai-agent.types.ts → agent/agent.types.ts}

@@ -5,14 +5,14 @@ import type {
 import type {
   CorePikkuMiddleware,
   MiddlewareMetadata,
-  PermissionMetadata,
-} from '../../types/core.types.js'
-import type { AIProviderOptions } from '../../services/ai-agent-runner-service.js'
+} from '../../middleware/middleware.types.js'
+import type { PermissionMetadata } from '../../function/function-meta.types.js'
+import type { AIProviderOptions } from '../../services/agent-runner-service.js'
 import type { PikkuChannel } from '../channel/channel.types.js'
 import type { CorePikkuChannelMiddleware } from '../channel/channel.types.js'
 import type { ApprovalPolicy } from '../channel/channel-rpc.js'
 
-export interface AIThread {
+export interface AgentThread {
   id: string
   resourceId: string
   title?: string
@@ -21,7 +21,7 @@ export interface AIThread {
   updatedAt: Date
 }
 
-export type AIContentPart =
+export type AgentContentPart =
   | { type: 'text'; text: string }
   | { type: 'image'; data?: string; url?: string; mediaType?: string }
   | {
@@ -41,13 +41,13 @@ export type AIContentPart =
       spec: unknown
     }
 
-export interface AIToolCall {
+export interface AgentToolCall {
   id: string
   name: string
   args: Record<string, unknown>
 }
 
-export interface AIToolResult {
+export interface AgentToolResult {
   id: string
   name: string
   result: string
@@ -60,12 +60,12 @@ export interface AIToolResult {
   error?: string
 }
 
-export interface AIMessage {
+export interface AgentMessage {
   id: string
   role: 'system' | 'user' | 'assistant' | 'tool'
-  content?: string | AIContentPart[]
-  toolCalls?: AIToolCall[]
-  toolResults?: AIToolResult[]
+  content?: string | AgentContentPart[]
+  toolCalls?: AgentToolCall[]
+  toolResults?: AgentToolResult[]
   reasoningContent?: string
   /**
    * Set on an assistant message whose generation was cut short by
@@ -87,7 +87,7 @@ export interface AIMessage {
   createdAt: Date
 }
 
-export interface AIAgentStep {
+export interface AgentStep {
   usage: { inputTokens: number; outputTokens: number }
   toolCalls?: {
     name: string
@@ -98,7 +98,7 @@ export interface AIAgentStep {
   }[]
 }
 
-export interface AIAgentInputAttachment {
+export interface AgentInputAttachment {
   type: 'image' | 'file'
   data?: string
   url?: string
@@ -106,11 +106,11 @@ export interface AIAgentInputAttachment {
   filename?: string
 }
 
-export interface AIAgentInput {
+export interface AgentInput {
   message: string
   threadId: string
   resourceId: string
-  attachments?: AIAgentInputAttachment[]
+  attachments?: AgentInputAttachment[]
   model?: string
   temperature?: number
   /** Structured context injected into the system instructions for this request.
@@ -119,12 +119,12 @@ export interface AIAgentInput {
   context?: string
 }
 
-export interface AIAgentOutput {
+export interface AgentOutput {
   runId: string
   text: string
   object?: unknown
   threadId: string
-  steps: AIAgentStep[]
+  steps: AgentStep[]
   usage: { inputTokens: number; outputTokens: number }
   status?: 'completed' | 'suspended'
   pendingApprovals?: Array<{
@@ -156,7 +156,7 @@ export type SessionScope = 'user' | 'org'
  * written by whoever runs the server it executes on. A capability runs on
  * someone else's machine, so it requires the field instead.
  */
-export interface AIAgentToolDef extends Partial<ApprovalPolicy> {
+export interface AgentToolDef extends Partial<ApprovalPolicy> {
   name: string
   description: string
   inputSchema: Record<string, unknown>
@@ -178,14 +178,14 @@ export interface AIAgentToolDef extends Partial<ApprovalPolicy> {
   forwardsApproval?: boolean
 }
 
-export interface PikkuAIMiddlewareHooks<
+export interface PikkuAgentMiddlewareHooks<
   State extends Record<string, unknown> = Record<string, unknown>,
   Services = any,
 > {
   modifyInput?: (
     services: Services,
     ctx: {
-      messages: AIMessage[]
+      messages: AgentMessage[]
       instructions: string
       /**
        * Notes about this run that every middleware can read and write, as
@@ -206,14 +206,14 @@ export interface PikkuAIMiddlewareHooks<
       shared: Record<string, unknown>
     }
   ) =>
-    | Promise<{ messages: AIMessage[]; instructions: string }>
-    | { messages: AIMessage[]; instructions: string }
+    | Promise<{ messages: AgentMessage[]; instructions: string }>
+    | { messages: AgentMessage[]; instructions: string }
 
   modifyOutputStream?: (
     services: Services,
     ctx: {
-      event: AIStreamEvent
-      allEvents: readonly AIStreamEvent[]
+      event: AgentStreamEvent
+      allEvents: readonly AgentStreamEvent[]
       /** Private to this middleware, for this run. Cross-middleware facts go in `shared`. */
       state: State
       /** Per-run notes shared with every middleware — see {@link modifyInput}. */
@@ -232,7 +232,7 @@ export interface PikkuAIMiddlewareHooks<
        * it matters — and a hook that emits must make sure anything still
        * outstanding has landed before it lets `done` through.
        */
-      emit: (event: AIStreamEvent) => Promise<void>
+      emit: (event: AgentStreamEvent) => Promise<void>
       /**
        * Aborts when the run is interrupted. Pass it to any provider call the
        * hook makes: work started for a reply the user has already talked over
@@ -241,9 +241,9 @@ export interface PikkuAIMiddlewareHooks<
       signal?: AbortSignal
     }
   ) =>
-    | Promise<AIStreamEvent | AIStreamEvent[] | null>
-    | AIStreamEvent
-    | AIStreamEvent[]
+    | Promise<AgentStreamEvent | AgentStreamEvent[] | null>
+    | AgentStreamEvent
+    | AgentStreamEvent[]
     | null
 
   /**
@@ -265,20 +265,20 @@ export interface PikkuAIMiddlewareHooks<
     services: Services,
     ctx: {
       text: string
-      messages: AIMessage[]
+      messages: AgentMessage[]
       usage: { inputTokens: number; outputTokens: number }
-      toolCalls: NonNullable<AIAgentStep['toolCalls']>
+      toolCalls: NonNullable<AgentStep['toolCalls']>
     }
   ) =>
     | Promise<{
         text: string
-        messages: AIMessage[]
-        toolCalls?: NonNullable<AIAgentStep['toolCalls']>
+        messages: AgentMessage[]
+        toolCalls?: NonNullable<AgentStep['toolCalls']>
       }>
     | {
         text: string
-        messages: AIMessage[]
-        toolCalls?: NonNullable<AIAgentStep['toolCalls']>
+        messages: AgentMessage[]
+        toolCalls?: NonNullable<AgentStep['toolCalls']>
       }
 
   beforeToolCall?: (
@@ -327,12 +327,12 @@ export interface PikkuAIMiddlewareHooks<
     ctx: {
       error: Error
       stepNumber: number
-      messages: AIMessage[]
+      messages: AgentMessage[]
     }
   ) => Promise<void> | void
 }
 
-export type AIAgentMemoryConfig = {
+export type AgentMemoryConfig = {
   storage?: string
   vector?: string
   embedder?: string
@@ -340,7 +340,7 @@ export type AIAgentMemoryConfig = {
   workingMemory?: unknown
 }
 
-export type CoreAIAgent<
+export type CoreAgent<
   PikkuPermission = CorePikkuPermission<any, any>,
   PikkuMiddleware = CorePikkuMiddleware<any>,
   Scope extends string = string,
@@ -382,7 +382,7 @@ export type CoreAIAgent<
    */
   scorers?: Scorer[]
   agentMode?: 'delegate' | 'supervise'
-  memory?: AIAgentMemoryConfig
+  memory?: AgentMemoryConfig
   maxSteps?: number
   toolChoice?: 'auto' | 'required' | 'none'
   /**
@@ -400,15 +400,15 @@ export type CoreAIAgent<
   tags?: string[]
   prepareStep?: (ctx: {
     stepNumber: number
-    messages: AIMessage[]
-    tools: AIAgentToolDef[]
+    messages: AgentMessage[]
+    tools: AgentToolDef[]
     toolChoice: 'auto' | 'required' | 'none'
     model: string
     stop: () => void
   }) => void | Promise<void>
   middleware?: PikkuMiddleware[]
   channelMiddleware?: CorePikkuChannelMiddleware<any, any>[]
-  aiMiddleware?: PikkuAIMiddlewareHooks<any, any>[]
+  agentMiddleware?: PikkuAgentMiddlewareHooks<any, any>[]
   /**
    * Whether a session is required to run this agent. Defaults to `false`, since
    * agents are commonly invoked from an already-authenticated `pikkuFunc` or
@@ -423,13 +423,13 @@ export type CoreAIAgent<
    * which OR together, a scope can only narrow access.
    *
    * Narrowed to the generated `ScopeId` union in a project's own
-   * `pikku-types.gen.ts`, so an undeclared scope is a compile error.
+   * `#pikku/scopes`, so an undeclared scope is a compile error.
    */
   scopes?: Scope[]
   permissions?: CorePermissionGroup<PikkuPermission>
 }
 
-export type AIStreamEvent =
+export type AgentStreamEvent =
   | { type: 'step-start'; stepNumber: number; agent?: string; session?: string }
   | { type: 'text-delta'; text: string; agent?: string; session?: string }
   | { type: 'reasoning-delta'; text: string; agent?: string; session?: string }
@@ -555,7 +555,10 @@ export type AIStreamEvent =
     }
   | { type: 'done' }
 
-export interface AIStreamChannel extends PikkuChannel<unknown, AIStreamEvent> {}
+export interface AgentStreamChannel extends PikkuChannel<
+  unknown,
+  AgentStreamEvent
+> {}
 
 export type PendingApproval =
   | {
@@ -630,18 +633,18 @@ export interface AgentRunService {
     owners?: string[]
     limit?: number
     offset?: number
-  }): Promise<AIThread[]>
-  getThread(threadId: string): Promise<AIThread | null>
-  getThreadMessages(threadId: string): Promise<AIMessage[]>
+  }): Promise<AgentThread[]>
+  getThread(threadId: string): Promise<AgentThread | null>
+  getThreadMessages(threadId: string): Promise<AgentMessage[]>
   getThreadRuns(threadId: string): Promise<AgentRunRow[]>
   deleteThread(threadId: string): Promise<boolean>
   getDistinctAgentNames(): Promise<string[]>
 }
 
-export type AIAgentMeta = Record<
+export type AgentsMeta = Record<
   string,
   Omit<
-    CoreAIAgent,
+    CoreAgent,
     | 'input'
     | 'output'
     | 'tools'
@@ -649,7 +652,7 @@ export type AIAgentMeta = Record<
     | 'workflows'
     | 'middleware'
     | 'channelMiddleware'
-    | 'aiMiddleware'
+    | 'agentMiddleware'
     | 'permissions'
   > & {
     tools?: string[]
@@ -660,7 +663,7 @@ export type AIAgentMeta = Record<
     workingMemorySchema: string | null
     middleware?: MiddlewareMetadata[]
     channelMiddleware?: MiddlewareMetadata[]
-    aiMiddleware?: MiddlewareMetadata[]
+    agentMiddleware?: MiddlewareMetadata[]
     permissions?: PermissionMetadata[]
     sourceFile?: string
     exportedName?: string

package/src/wirings/agent/index.ts

@@ -0,0 +1,57 @@
+export {
+  agent,
+  agentStream,
+  agentResume,
+  agentApprove,
+  agentInterrupt,
+} from './agent-helpers.js'
+export { wrapChannelWithAGUI } from './agent-agui.js'
+export { runAgent, resumeAgentSync } from './agent-runner.js'
+export { resolveModelAlias } from './agent-model-config.js'
+export { streamAgent, resumeAgent, interruptAgent } from './agent-stream.js'
+export {
+  voiceInput,
+  NoSpeechDetectedError,
+  SPOKEN_TURN,
+  SPOKEN_TRANSCRIPT,
+} from './voice-input.js'
+export {
+  voiceOutput,
+  unspeakableScripts,
+  voiceForText,
+  type SpeakableScripts,
+  type VoiceOutputState,
+} from './voice-output.js'
+export { AgentInterruptedError, signalRunInterrupt } from './agent-interrupt.js'
+export type {
+  AgentInterruption,
+  AgentInterruptResult,
+  InterruptibleRunHandle,
+} from './agent-interrupt.js'
+export {
+  type RunAgentParams,
+  type StreamAgentOptions,
+  ToolApprovalRequired,
+  ToolCredentialRequired,
+  canAccessThread,
+  isOwnedByPrincipal,
+  threadOwnerConstraint,
+} from './agent-prepare.js'
+export { addAgent } from './agent-registry.js'
+export type {
+  AgentInput,
+  AgentsMeta,
+  AgentMemoryConfig,
+  AgentStep,
+  AgentContentPart,
+  AgentRunRow,
+  AgentRunService,
+  AgentRunState,
+  AgentMessage,
+  AgentStreamChannel,
+  AgentStreamEvent,
+  AgentThread,
+  CoreAgent,
+  PendingApproval,
+  PikkuAgentMiddlewareHooks,
+} from './agent.types.js'