@pikku/core 0.12.107 → 0.12.112

package/src/wirings/agent/agent-thread-ownership.test.ts

@@ -1,297 +0,0 @@
-import { beforeEach, describe, test } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { resetPikkuState, pikkuState } from '../../pikku-state.js'
-import { runAgent, resumeAgentSync } from './agent-runner.js'
-import { ForbiddenError } from '../../errors/errors.js'
-import type { AgentMessage, CoreAgent } from './agent.types.js'
-import type { AgentRunnerParams } from '../../services/agent-runner-service.js'
-
-const logger = {
-  debug: () => {},
-  info: () => {},
-  warn: () => {},
-  error: () => {},
-} as any
-
-const sessionService = (session?: Record<string, unknown>) =>
-  ({ get: () => session, setInitial: () => {}, sessionChanged: false }) as any
-
-const addTestAgent = (agentName: string) => {
-  const agent: CoreAgent = {
-    name: agentName,
-    description: 'test agent',
-    instructions: 'be helpful',
-    model: 'test/test-model',
-  } as CoreAgent
-
-  pikkuState(null, 'agent', 'agentsMeta')[agentName] = {
-    ...agent,
-    inputSchema: null,
-    outputSchema: null,
-    workingMemorySchema: null,
-  } as any
-  pikkuState(null, 'agent', 'agents').set(agentName, agent)
-}
-
-type Harness = {
-  threads: Map<string, { id: string; resourceId: string }>
-  messages: Map<string, AgentMessage[]>
-  created: Array<{ threadId: string; resourceId: string }>
-  modelSawMessages: AgentMessage[][]
-}
-
-const createHarness = (
-  seedThreads: Array<{ threadId: string; resourceId: string }> = [],
-  seedMessages: Record<string, string[]> = {}
-): Harness => {
-  const threads = new Map(
-    seedThreads.map((t) => [t.threadId, { id: t.threadId, ...t }])
-  )
-  const messages = new Map<string, AgentMessage[]>(
-    Object.entries(seedMessages).map(([threadId, texts]) => [
-      threadId,
-      texts.map((text, index) => ({
-        id: `${threadId}-${index}`,
-        role: 'user' as const,
-        content: text,
-        createdAt: new Date(),
-      })),
-    ])
-  )
-  const created: Harness['created'] = []
-  const modelSawMessages: AgentMessage[][] = []
-
-  const storage = {
-    getThread: async (threadId: string) => {
-      const thread = threads.get(threadId)
-      if (!thread) throw new Error(`No thread ${threadId}`)
-      return thread
-    },
-    createThread: async (resourceId: string, options: { threadId: string }) => {
-      const thread = { id: options.threadId, resourceId }
-      threads.set(options.threadId, thread)
-      created.push({ threadId: options.threadId, resourceId })
-      return thread
-    },
-    getMessages: async (threadId: string) => messages.get(threadId) ?? [],
-    saveMessages: async (threadId: string, newMessages: AgentMessage[]) => {
-      messages.set(threadId, [
-        ...(messages.get(threadId) ?? []),
-        ...newMessages,
-      ])
-    },
-    getWorkingMemory: async () => null,
-    saveWorkingMemory: async () => {},
-  }
-
-  pikkuState(null, 'package', 'singletonServices', {
-    logger,
-    agentStorage: storage,
-    agentRunner: {
-      run: async (params: AgentRunnerParams) => {
-        modelSawMessages.push(params.messages)
-        return {
-          text: 'ok',
-          toolCalls: [],
-          toolResults: [],
-          usage: { inputTokens: 0, outputTokens: 0 },
-          finishReason: 'stop',
-        }
-      },
-    },
-    agentRunState: {
-      createRun: async () => 'run-1',
-      updateRun: async () => {},
-      getRun: async () => ({
-        id: 'run-1',
-        agentName: 'ownership-agent',
-        resourceId: 'victim',
-        threadId: 'thread-victim',
-        status: 'suspended',
-        pendingApprovals: [
-          { toolCallId: 'tc-1', toolName: 'refund', args: {}, runId: 'run-1' },
-        ],
-        messages: [],
-      }),
-      resolveApproval: async () => true,
-    },
-  } as any)
-
-  return { threads, messages, created, modelSawMessages }
-}
-
-beforeEach(() => {
-  resetPikkuState()
-})
-
-describe('AI agent thread ownership without a session', () => {
-  test('a sessionless caller cannot reach a thread by naming its resourceId', async () => {
-    addTestAgent('ownership-agent')
-    const harness = createHarness(
-      [{ threadId: 'thread-victim', resourceId: 'victim' }],
-      { 'thread-victim': ['the victim bank details are 1234'] }
-    )
-
-    await assert.rejects(
-      () =>
-        runAgent(
-          'ownership-agent',
-          {
-            message: 'what did we discuss?',
-            threadId: 'thread-victim',
-            resourceId: 'victim',
-          },
-          {}
-        ),
-      (error: unknown) => error instanceof ForbiddenError
-    )
-
-    assert.deepEqual(
-      harness.modelSawMessages,
-      [],
-      "the victim's history must never reach the model"
-    )
-  })
-
-  test('a sessionless caller cannot resume another party run', async () => {
-    addTestAgent('ownership-agent')
-    createHarness()
-
-    await assert.rejects(
-      () =>
-        resumeAgentSync('run-1', [{ toolCallId: 'tc-1', approved: true }], {}),
-      (error: unknown) => error instanceof ForbiddenError
-    )
-  })
-
-  test('a sessionless one-shot conversation still runs', async () => {
-    addTestAgent('ownership-agent')
-    const harness = createHarness()
-
-    const result = await runAgent(
-      'ownership-agent',
-      { message: 'hello', threadId: 'thread-new', resourceId: 'whatever' },
-      {}
-    )
-
-    assert.equal(result.text, 'ok')
-    assert.equal(harness.created.length, 1)
-    assert.equal(harness.created[0]!.threadId, 'thread-new')
-    assert.notEqual(
-      harness.created[0]!.resourceId,
-      'whatever',
-      'a client-supplied resourceId must never become the ownership key'
-    )
-    assert.deepEqual(
-      harness.modelSawMessages[0]?.map((m) => m.content),
-      ['hello']
-    )
-  })
-
-  test('a sessionless run keeps its own thread across nested agent calls in one request', async () => {
-    addTestAgent('ownership-agent')
-    const harness = createHarness()
-    const requestParams = {}
-
-    await runAgent(
-      'ownership-agent',
-      { message: 'first', threadId: 'thread-sub', resourceId: 'ignored' },
-      requestParams
-    )
-    await runAgent(
-      'ownership-agent',
-      { message: 'second', threadId: 'thread-sub', resourceId: 'ignored' },
-      requestParams
-    )
-
-    assert.equal(harness.created.length, 1)
-    assert.equal(harness.modelSawMessages.length, 2)
-  })
-
-  test('two sessionless one-shot runs do not share an owner', async () => {
-    addTestAgent('ownership-agent')
-    const harness = createHarness()
-
-    await runAgent(
-      'ownership-agent',
-      { message: 'hello', threadId: 'thread-a', resourceId: 'shared' },
-      {}
-    )
-    await runAgent(
-      'ownership-agent',
-      { message: 'hello', threadId: 'thread-b', resourceId: 'shared' },
-      {}
-    )
-
-    assert.notEqual(
-      harness.created[0]!.resourceId,
-      harness.created[1]!.resourceId
-    )
-  })
-})
-
-describe('AI agent thread ownership with a session', () => {
-  test('an authenticated caller still reaches its own thread', async () => {
-    addTestAgent('ownership-agent')
-    const harness = createHarness(
-      [{ threadId: 'thread-alice', resourceId: 'alice:default' }],
-      { 'thread-alice': ['earlier alice turn'] }
-    )
-
-    const result = await runAgent(
-      'ownership-agent',
-      {
-        message: 'and then?',
-        threadId: 'thread-alice',
-        resourceId: 'default',
-      },
-      { sessionService: sessionService({ userId: 'alice' }) }
-    )
-
-    assert.equal(result.text, 'ok')
-    assert.deepEqual(
-      harness.modelSawMessages[0]?.map((m) => m.content),
-      ['earlier alice turn', 'and then?']
-    )
-    assert.equal(harness.created.length, 0)
-  })
-
-  test('an authenticated caller creates threads under its own principal', async () => {
-    addTestAgent('ownership-agent')
-    const harness = createHarness()
-
-    await runAgent(
-      'ownership-agent',
-      { message: 'hello', threadId: 'thread-new', resourceId: 'project-1' },
-      { sessionService: sessionService({ userId: 'alice' }) }
-    )
-
-    assert.deepEqual(harness.created, [
-      { threadId: 'thread-new', resourceId: 'alice:project-1' },
-    ])
-  })
-
-  test("an authenticated caller cannot reach another user's thread", async () => {
-    addTestAgent('ownership-agent')
-    const harness = createHarness(
-      [{ threadId: 'thread-bob', resourceId: 'bob:default' }],
-      { 'thread-bob': ['bob secret'] }
-    )
-
-    await assert.rejects(
-      () =>
-        runAgent(
-          'ownership-agent',
-          {
-            message: 'what did we discuss?',
-            threadId: 'thread-bob',
-            resourceId: 'bob:default',
-          },
-          { sessionService: sessionService({ userId: 'alice' }) }
-        ),
-      (error: unknown) => error instanceof ForbiddenError
-    )
-    assert.deepEqual(harness.modelSawMessages, [])
-  })
-})

package/src/wirings/agent/agent-turn.test.ts

@@ -1,65 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { toAccumulatedStep } from './agent-turn.js'
-import type { AgentStepResult } from '../../services/agent-runner-service.js'
-
-const stepResult = (overrides?: Partial<AgentStepResult>): AgentStepResult => ({
-  text: '',
-  toolCalls: [],
-  toolResults: [],
-  usage: { inputTokens: 0, outputTokens: 0 },
-  finishReason: 'stop',
-  ...overrides,
-})
-
-describe('toAccumulatedStep', () => {
-  test('carries a tool failure as its own field, not only as rendered text', () => {
-    const step = toAccumulatedStep(
-      stepResult({
-        toolCalls: [
-          { toolCallId: 'call-1', toolName: 'lookupOrder', args: { id: 7 } },
-        ],
-        toolResults: [
-          {
-            toolCallId: 'call-1',
-            toolName: 'lookupOrder',
-            result: 'Error: order service unreachable',
-            error: 'order service unreachable',
-          },
-        ],
-      })
-    )
-
-    assert.deepEqual(step.toolCalls, [
-      {
-        name: 'lookupOrder',
-        args: { id: 7 },
-        result: 'Error: order service unreachable',
-        error: 'order service unreachable',
-      },
-    ])
-  })
-
-  test('leaves error unset on a tool that returned normally, even if it says Error', () => {
-    // A tool is allowed to return the word "Error" — which is exactly why
-    // "did this fail" cannot be answered by matching on the result text.
-    const step = toAccumulatedStep(
-      stepResult({
-        toolCalls: [
-          { toolCallId: 'call-1', toolName: 'searchLogs', args: { q: 'x' } },
-        ],
-        toolResults: [
-          {
-            toolCallId: 'call-1',
-            toolName: 'searchLogs',
-            result: 'Error: connection refused (1 match)',
-          },
-        ],
-      })
-    )
-
-    assert.equal(step.toolCalls[0].error, undefined)
-    assert.ok(!('error' in step.toolCalls[0]))
-  })
-})

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

@@ -1,122 +0,0 @@
-import type { CoreSingletonServices } from '../../types/core.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<PikkuAgentMiddlewareHooks['modifyInput']>>[1],
-  'messages' | 'instructions'
->
-
-/**
- * Run every `modifyInput` hook in order, threading each result into the next.
- *
- * Shared by the four places a turn starts — first turn and resume, on both the
- * streaming and non-streaming paths. `sharedNotes` is one bag per run that the
- * caller keeps, because hooks use it to pass things forward (`voiceInput`
- * leaves the transcript there for `voiceOutput`).
- */
-export const applyInputMiddleware = async (
-  agentMiddlewares: PikkuAgentMiddlewareHooks[],
-  singletonServices: CoreSingletonServices,
-  input: TurnInput,
-  sharedNotes: Record<string, unknown>
-): Promise<TurnInput> => {
-  let { messages, instructions } = input
-  for (const mw of agentMiddlewares) {
-    if (!mw.modifyInput) continue
-    const result = await mw.modifyInput(singletonServices, {
-      messages,
-      instructions,
-      shared: sharedNotes,
-    })
-    messages = result.messages
-    instructions = result.instructions
-  }
-  return { messages, instructions }
-}
-
-/** The step fields both agent paths hand to `afterStep`, taken from the hook. */
-type StepResult = Omit<
-  Parameters<NonNullable<PikkuAgentMiddlewareHooks['afterStep']>>[1],
-  'stepNumber'
->
-
-/**
- * Notify every `afterStep` hook. The payload is the step verbatim plus its
- * ordinal — a hook that wants the run's totals accumulates them itself.
- */
-export const notifyAfterStep = async (
-  agentMiddlewares: PikkuAgentMiddlewareHooks[],
-  singletonServices: CoreSingletonServices,
-  stepNumber: number,
-  stepResult: StepResult
-): Promise<void> => {
-  for (const mw of agentMiddlewares) {
-    if (!mw.afterStep) continue
-    await mw.afterStep(singletonServices, {
-      stepNumber,
-      text: stepResult.text,
-      toolCalls: stepResult.toolCalls,
-      toolResults: stepResult.toolResults,
-      usage: stepResult.usage,
-      finishReason: stepResult.finishReason,
-    })
-  }
-}
-
-/**
- * The step shape kept on the run: each tool call paired with its result.
- *
- * A result is stringified unless it already is a string, because this is what
- * gets persisted and read back as history — an object there is unreadable.
- */
-export const toAccumulatedStep = (stepResult: StepResult) => ({
-  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 ?? ''),
-      ...(tr?.error ? { error: tr.error } : {}),
-    }
-  }),
-})
-
-type PendingApproval = {
-  toolName: string
-  args: unknown
-  reason?: string
-}
-
-type ToolDef = {
-  name: string
-  approvalDescriptionFn?: (args: any) => Promise<string> | string
-}
-
-/**
- * Fill in each approval's human-readable reason from the tool's own
- * `approvalDescriptionFn`, where it did not supply one.
- *
- * A description that throws is swallowed: the approval still has to be raised,
- * and a gate that disappears because its label failed to render is the worst
- * available outcome.
- */
-export const describeApprovals = async (
-  approvals: PendingApproval[],
-  tools: ToolDef[]
-): Promise<void> => {
-  for (const approval of approvals) {
-    if (approval.reason) continue
-    const toolDef = tools.find((t) => t.name === approval.toolName)
-    if (!toolDef?.approvalDescriptionFn) continue
-    try {
-      approval.reason = await toolDef.approvalDescriptionFn(approval.args)
-    } catch {}
-  }
-}

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

@@ -1,20 +0,0 @@
-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.',
-  })