@pikku/core 0.12.106 → 0.12.111

package/src/scopes.test.ts

@@ -1,203 +0,0 @@
-import { describe, test } from 'node:test'
-import * as assert from 'node:assert'
-import { hasScopes, verifyScopes } from './scopes.js'
-import { MissingScopeError } from './errors/errors.js'
-import type { CoreUserSession } from './types/core.types.js'
-
-const session = (scopes?: string[]): CoreUserSession =>
-  ({ userId: 'test-user', scopes }) as CoreUserSession
-
-describe('verifyScopes', () => {
-  test('passes on an exact match', () => {
-    verifyScopes(['invoices:create'], session(['invoices:create']))
-  })
-
-  test('passes when no scopes are required', () => {
-    verifyScopes([], session())
-  })
-
-  test('throws when the session holds none', () => {
-    assert.throws(
-      () => verifyScopes(['invoices:create'], session([])),
-      MissingScopeError
-    )
-  })
-
-  test('holding an unrelated scope does not grant', () => {
-    assert.throws(
-      () => verifyScopes(['invoices:create'], session(['billing:read'])),
-      MissingScopeError
-    )
-  })
-
-  describe('wildcards', () => {
-    test('admin:* satisfies a descendant', () => {
-      verifyScopes(['admin:invoices:create'], session(['admin:*']))
-    })
-
-    test('admin:* satisfies an intermediate descendant', () => {
-      verifyScopes(['admin:invoices'], session(['admin:*']))
-    })
-
-    test('admin:* satisfies the parent itself', () => {
-      verifyScopes(['admin'], session(['admin:*']))
-    })
-
-    test('a bare * satisfies anything', () => {
-      verifyScopes(['admin:invoices:create'], session(['*']))
-    })
-
-    test('a deep wildcard satisfies its own descendants', () => {
-      verifyScopes(['admin:invoices:create'], session(['admin:invoices:*']))
-    })
-
-    test('does not leak across siblings', () => {
-      assert.throws(
-        () => verifyScopes(['billing:read'], session(['admin:*'])),
-        MissingScopeError
-      )
-    })
-
-    test('a required wildcard is not satisfied by one narrow grant', () => {
-      assert.throws(
-        () => verifyScopes(['admin:*'], session(['admin:invoices:create'])),
-        MissingScopeError
-      )
-    })
-
-    test('a required wildcard is satisfied by a broader grant', () => {
-      verifyScopes(['admin:*'], session(['*']))
-    })
-  })
-
-  describe('a plain parent grant covers its descendants', () => {
-    test('holding a parent satisfies a deep descendant', () => {
-      verifyScopes(['admin:invoices:create'], session(['admin']))
-    })
-
-    test('holding a parent satisfies an intermediate descendant', () => {
-      verifyScopes(['admin:invoices'], session(['admin']))
-    })
-
-    test('holding an intermediate parent satisfies its child', () => {
-      verifyScopes(['admin:invoices:create'], session(['admin:invoices']))
-    })
-
-    test('a parent does not leak across siblings', () => {
-      assert.throws(
-        () => verifyScopes(['billing:read'], session(['admin'])),
-        MissingScopeError
-      )
-    })
-  })
-
-  describe('AND semantics', () => {
-    test('passes only when every required scope is held', () => {
-      verifyScopes(
-        ['invoices:read', 'invoices:write'],
-        session(['invoices:read', 'invoices:write'])
-      )
-    })
-
-    test('throws when only one of two is held', () => {
-      assert.throws(
-        () =>
-          verifyScopes(
-            ['invoices:read', 'invoices:write'],
-            session(['invoices:read'])
-          ),
-        MissingScopeError
-      )
-    })
-
-    test('one wildcard can satisfy several requirements', () => {
-      verifyScopes(['admin:read', 'admin:write'], session(['admin:*']))
-    })
-  })
-
-  describe('fails closed', () => {
-    test('throws when the session has no scopes field', () => {
-      assert.throws(
-        () => verifyScopes(['invoices:create'], session(undefined)),
-        MissingScopeError
-      )
-    })
-
-    test('throws when there is no session at all', () => {
-      assert.throws(
-        () => verifyScopes(['invoices:create'], undefined),
-        MissingScopeError
-      )
-    })
-
-    test('a narrower grant does not satisfy a broader requirement', () => {
-      assert.throws(
-        () => verifyScopes(['admin'], session(['admin:invoices'])),
-        MissingScopeError
-      )
-    })
-  })
-
-  describe('a parent grant coexists with a child grant', () => {
-    test('the parent still grants when a child is also held', () => {
-      verifyScopes(
-        ['admin:invoices'],
-        session(['admin:invoices', 'admin:invoices:create'])
-      )
-    })
-
-    test('the child still grants when a parent is also held', () => {
-      verifyScopes(
-        ['admin:invoices:create'],
-        session(['admin:invoices', 'admin:invoices:create'])
-      )
-    })
-  })
-
-  test('names the missing scope', () => {
-    assert.throws(
-      () => verifyScopes(['a:b', 'c:d'], session(['a:b'])),
-      (err: MissingScopeError) => {
-        assert.equal(err.payload.scope, 'c:d')
-        assert.match(err.message, /c:d/)
-        return true
-      }
-    )
-  })
-})
-
-describe('hasScopes', () => {
-  test('true on an exact match', () => {
-    assert.equal(hasScopes(['invoices:create'], ['invoices:create']), true)
-  })
-
-  test('false when the grant is unrelated', () => {
-    assert.equal(hasScopes(['invoices:create'], ['billing:read']), false)
-  })
-
-  test('shares the hierarchy rules with verifyScopes', () => {
-    assert.equal(hasScopes(['admin:impersonate'], ['admin']), true)
-    assert.equal(hasScopes(['admin:impersonate'], ['admin:*']), true)
-    assert.equal(hasScopes(['admin:impersonate'], ['*']), true)
-    assert.equal(hasScopes(['admin'], ['admin:impersonate']), false)
-  })
-
-  test('AND semantics: every required scope must be satisfied', () => {
-    assert.equal(hasScopes(['a:read', 'a:write'], ['a:read']), false)
-    assert.equal(hasScopes(['a:read', 'a:write'], ['a']), true)
-  })
-
-  test('fails closed on absent or empty grants', () => {
-    assert.equal(hasScopes(['invoices:create'], undefined), false)
-    assert.equal(hasScopes(['invoices:create'], []), false)
-  })
-
-  test('an empty requirement is satisfied by anything', () => {
-    assert.equal(hasScopes([], undefined), true)
-    assert.equal(hasScopes(undefined, undefined), true)
-  })
-
-  test('accepts a Set of held grants', () => {
-    assert.equal(hasScopes(['admin:impersonate'], new Set(['admin'])), true)
-  })
-})

package/src/scopes.ts

@@ -1,67 +0,0 @@
-import type { CoreUserSession } from './types/core.types.js'
-import { MissingScopeError } from './errors/errors.js'
-
-const SEPARATOR = ':'
-const WILDCARD = '*'
-
-/**
- * Every grant that would satisfy `scope`: the scope itself, a wildcard
- * directly beneath it, a wildcard at each ancestor level, and each plain
- * ancestor id.
- */
-const satisfyingGrants = (scope: string): string[] => {
-  const segments = scope.split(SEPARATOR)
-  const grants = [scope, `${scope}${SEPARATOR}${WILDCARD}`]
-  for (let i = 0; i < segments.length; i++) {
-    grants.push([...segments.slice(0, i), WILDCARD].join(SEPARATOR))
-  }
-  for (let i = 1; i < segments.length; i++) {
-    grants.push(segments.slice(0, i).join(SEPARATOR))
-  }
-  return grants
-}
-
-const holds = (held: ReadonlySet<string>, scope: string): boolean =>
-  satisfyingGrants(scope).some((grant) => held.has(grant))
-
-/** The first required scope `held` does not satisfy, or `null`. Fails closed. */
-const firstUnsatisfied = (
-  required: readonly string[] | undefined,
-  held: Iterable<string> | undefined
-): string | null => {
-  if (!required || required.length === 0) {
-    return null
-  }
-
-  const grants = new Set(held ?? [])
-  for (const scope of required) {
-    if (!holds(grants, scope)) {
-      return scope
-    }
-  }
-  return null
-}
-
-/**
- * The non-throwing counterpart to {@link verifyScopes}, for deciding rather
- * than enforcing. Fails closed; an empty `required` is satisfied by anything.
- */
-export const hasScopes = (
-  required: readonly string[] | undefined,
-  held: Iterable<string> | undefined
-): boolean => firstUnsatisfied(required, held) === null
-
-/**
- * Throws {@link MissingScopeError} naming the first scope the session does not
- * hold. Fails closed: no session, or a session without `scopes`, satisfies
- * nothing.
- */
-export const verifyScopes = (
-  required: readonly string[] | undefined,
-  session: CoreUserSession | undefined
-): void => {
-  const missing = firstUnsatisfied(required, session?.scopes)
-  if (missing !== null) {
-    throw new MissingScopeError(missing)
-  }
-}

package/src/services/agent-run-state-service.ts

@@ -1,37 +0,0 @@
-import type {
-  AgentRunState,
-  PendingApproval,
-} from '../wirings/agent/agent.types.js'
-import type { AgentRunScore } from '../wirings/agent-scorer/agent-scorer.types.js'
-
-export type CreateRunInput = Omit<AgentRunState, 'runId'>
-
-export type SaveScoreInput = Omit<AgentRunScore, 'createdAt'>
-
-export interface AgentRunStateService {
-  createRun(run: CreateRunInput): Promise<string>
-  updateRun(runId: string, updates: Partial<AgentRunState>): Promise<void>
-  getRun(runId: string): Promise<AgentRunState | null>
-  getRunsByThread(threadId: string): Promise<AgentRunState[]>
-  /**
-   * Claims an approval: removes it from the run's pending list and records the
-   * decision, as one atomic step. Returns whether THIS caller made the claim —
-   * concurrent approvals of the same tool call produce exactly one `true`, and
-   * only that caller may run the tool.
-   */
-  resolveApproval(
-    toolCallId: string,
-    status: 'approved' | 'denied'
-  ): Promise<boolean>
-  findRunByToolCallId(
-    toolCallId: string
-  ): Promise<{ run: AgentRunState; approval: PendingApproval } | null>
-  /**
-   * Record one scorer's grade of a finished run. A run accumulates one row per
-   * scorer, and a scorer may grade the same run more than once — a retried job
-   * appends rather than replaces, so a re-grade never silently overwrites the
-   * grade that was acted on.
-   */
-  saveScore(score: SaveScoreInput): Promise<void>
-  getScores(runId: string): Promise<AgentRunScore[]>
-}

package/src/services/agent-runner-service.ts

@@ -1,238 +0,0 @@
-import type {
-  AgentMessage,
-  AgentStep,
-  AgentToolDef,
-  AgentStreamChannel,
-} from '../wirings/agent/agent.types.js'
-
-export type AIProviderOptions = Record<string, Record<string, unknown>>
-
-export type AgentRunnerParams = {
-  model: string
-  temperature?: number
-  instructions: string
-  messages: AgentMessage[]
-  tools: AgentToolDef[]
-  maxSteps: number
-  toolChoice: 'auto' | 'required' | 'none'
-  outputSchema?: Record<string, unknown>
-  /** Pikku agent function name — forwarded to the LLM proxy (LiteLLM) as
-   *  request-level metadata so usage can be broken down per agent. */
-  agentId?: string
-  /**
-   * Cancels the model call itself, not just delivery of its output. Set by
-   * `streamAgent` from the run's interrupt handle so a voice barge-in stops
-   * generation upstream rather than leaving tokens being billed into a stream
-   * nobody reads. A runner that ignores it degrades to "the caller stops
-   * listening", which is the behaviour before this field existed.
-   */
-  abortSignal?: AbortSignal
-  /**
-   * Per-provider settings passed to the model untouched — the escape hatch for
-   * anything the shared params above cannot express because only one vendor
-   * has it.
-   *
-   * The setting that motivated it is `reasoningEffort`. A voice turn is heard
-   * rather than read, so the wait before the first word is most of the
-   * experience: `{ openai: { reasoningEffort: 'minimal' } }` on gpt-5-mini
-   * measured 0.9s to first token against 2.5s at the default, and 1.6s of
-   * silence is a long time to sit through having just finished speaking.
-   */
-  providerOptions?: AIProviderOptions
-}
-
-export type AgentRunnerResult = {
-  text: string
-  object?: unknown
-  steps: AgentStep[]
-  usage: { inputTokens: number; outputTokens: number }
-}
-
-export type AgentStepResult = {
-  text: string
-  object?: unknown
-  toolCalls: { toolCallId: string; toolName: string; args: unknown }[]
-  toolResults: {
-    toolCallId: string
-    toolName: string
-    result: unknown
-    /**
-     * Set when the tool threw rather than returned. Carried as its own field
-     * because `result` is a rendered string by the time anything downstream
-     * reads it, and "did this tool fail" is not answerable by looking for an
-     * `Error:` prefix in text a tool could legitimately have returned.
-     */
-    error?: string
-  }[]
-  usage: { inputTokens: number; outputTokens: number }
-  finishReason: 'stop' | 'tool-calls' | 'length' | 'error' | 'unknown'
-  reasoningContent?: string
-}
-
-export type AITranscriptionParams = {
-  model: string
-  audio: Uint8Array
-  providerOptions?: AIProviderOptions
-  maxRetries?: number
-  abortSignal?: AbortSignal
-  headers?: Record<string, string>
-}
-
-export type AITranscriptionResult = {
-  text: string
-  segments?: Array<{
-    text: string
-    startSecond: number
-    endSecond: number
-  }>
-  language?: string
-  durationInSeconds?: number
-  warnings?: unknown[]
-  providerMetadata?: Record<string, unknown>
-  responses?: unknown[]
-}
-
-export type AIGenerateSpeechParams = {
-  model: string
-  text: string
-  voice?: string
-  outputFormat?: string
-  instructions?: string
-  speed?: number
-  language?: string
-  providerOptions?: AIProviderOptions
-  maxRetries?: number
-  abortSignal?: AbortSignal
-  headers?: Record<string, string>
-}
-
-export type AIGenerateSpeechResult = {
-  audio: {
-    uint8Array: Uint8Array
-    base64: string
-    mediaType: string
-    format: string
-  }
-  warnings?: unknown[]
-  providerMetadata?: Record<string, unknown>
-  responses?: unknown[]
-}
-
-export type AIGenerateImagePrompt =
-  | string
-  | {
-      images: Array<Uint8Array | ArrayBuffer | string>
-      text?: string
-      mask?: Uint8Array | ArrayBuffer | string
-    }
-
-export type AIGenerateImageParams = {
-  model: string
-  prompt: AIGenerateImagePrompt
-  n?: number
-  maxImagesPerCall?: number
-  size?: `${number}x${number}`
-  aspectRatio?: `${number}:${number}`
-  seed?: number
-  providerOptions?: AIProviderOptions
-  maxRetries?: number
-  abortSignal?: AbortSignal
-  headers?: Record<string, string>
-}
-
-export type AIGenerateImageResult = {
-  images: Array<{
-    uint8Array: Uint8Array
-    base64: string
-    mediaType: string
-  }>
-  warnings?: unknown[]
-  providerMetadata?: Record<string, unknown>
-  responses?: unknown[]
-  usage?: {
-    inputTokens?: number
-    outputTokens?: number
-    totalTokens?: number
-  }
-}
-
-export type AIEmbedParams = {
-  model: string
-  value: string
-  providerOptions?: AIProviderOptions
-  maxRetries?: number
-  abortSignal?: AbortSignal
-  headers?: Record<string, string>
-}
-
-export type AIEmbedResult = {
-  value: string
-  embedding: number[]
-  usage?: { tokens?: number }
-  warnings?: unknown[]
-  providerMetadata?: Record<string, unknown>
-  response?: unknown
-}
-
-export type AIEmbedManyParams = {
-  model: string
-  values: string[]
-  providerOptions?: AIProviderOptions
-  maxRetries?: number
-  abortSignal?: AbortSignal
-  headers?: Record<string, string>
-  maxParallelCalls?: number
-}
-
-export type AIEmbedManyResult = {
-  values: string[]
-  embeddings: number[][]
-  usage?: { tokens?: number }
-  warnings?: unknown[]
-  providerMetadata?: Record<string, unknown>
-  responses?: unknown[]
-}
-
-export type AIRerankParams<VALUE extends string | Record<string, unknown>> = {
-  model: string
-  query: string
-  documents: VALUE[]
-  topK?: number
-  providerOptions?: AIProviderOptions
-  maxRetries?: number
-  abortSignal?: AbortSignal
-  headers?: Record<string, string>
-}
-
-export type AIRerankResult<VALUE extends string | Record<string, unknown>> = {
-  ranking: Array<{
-    index: number
-    document: VALUE
-    score: number
-  }>
-  rerankedDocuments: VALUE[]
-  originalDocuments: VALUE[]
-  providerMetadata?: Record<string, unknown>
-  response?: unknown
-}
-
-export interface AgentRunnerService {
-  stream(
-    params: AgentRunnerParams,
-    channel: AgentStreamChannel
-  ): Promise<AgentStepResult>
-  run(params: AgentRunnerParams): Promise<AgentStepResult>
-  transcribe?(params: AITranscriptionParams): Promise<AITranscriptionResult>
-  generateSpeech?(
-    params: AIGenerateSpeechParams
-  ): Promise<AIGenerateSpeechResult>
-  generateImage?(params: AIGenerateImageParams): Promise<AIGenerateImageResult>
-  embed?(params: AIEmbedParams): Promise<AIEmbedResult>
-  embedMany?(params: AIEmbedManyParams): Promise<AIEmbedManyResult>
-  rerank?<VALUE extends string | Record<string, unknown>>(
-    params: AIRerankParams<VALUE>
-  ): Promise<AIRerankResult<VALUE>>
-  /** Return a new runner that uses the given API key for every LLM call.
-   *  Optional — runners that don't support per-key scoping leave this undefined. */
-  withApiKey?(apiKey: string): AgentRunnerService
-}

package/src/services/agent-storage-service.ts

@@ -1,39 +0,0 @@
-import type { AgentThread, AgentMessage } from '../wirings/agent/agent.types.js'
-
-export interface AgentStorageService {
-  createThread(
-    resourceId: string,
-    options?: {
-      threadId?: string
-      title?: string
-      metadata?: Record<string, unknown>
-    }
-  ): Promise<AgentThread>
-
-  getThread(threadId: string): Promise<AgentThread>
-
-  getThreads(resourceId: string): Promise<AgentThread[]>
-
-  deleteThread(threadId: string): Promise<void>
-
-  getMessages(
-    threadId: string,
-    options?: {
-      lastN?: number
-      cursor?: string
-    }
-  ): Promise<AgentMessage[]>
-
-  saveMessages(threadId: string, messages: AgentMessage[]): Promise<void>
-
-  getWorkingMemory(
-    id: string,
-    scope: 'resource' | 'thread'
-  ): Promise<Record<string, unknown> | null>
-
-  saveWorkingMemory(
-    id: string,
-    scope: 'resource' | 'thread',
-    data: Record<string, unknown>
-  ): Promise<void>
-}

package/src/services/ai-embedding-service.ts

@@ -1,9 +0,0 @@
-// knowledge: decisions/internals/the-embedding-model-is-pinned-per-service-and-doc-query-embedding-is-split.md
-export interface AIEmbeddingService {
-  readonly model: string
-  readonly dimensions?: number
-  /** Index time. Preserves input order. */
-  embedDocuments(values: string[]): Promise<number[][]>
-  /** Query time. */
-  embedQuery(value: string): Promise<number[]>
-}

package/src/services/audit-service.test.ts

@@ -1,44 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert/strict'
-import {
-  createInvocationAudit,
-  type AuditEvent,
-  type AuditEventBatch,
-} from './audit-service.js'
-
-describe('audit-service', () => {
-  test('best-effort flush failures are logged and do not throw', async () => {
-    const warnings: unknown[][] = []
-    const audit = createInvocationAudit(
-      {
-        async audit(_event: AuditEvent): Promise<void> {
-          throw new Error('should not use single-event write')
-        },
-        async write(_batch: AuditEventBatch): Promise<void> {
-          throw new Error('sink failed')
-        },
-      },
-      {
-        wireType: 'rpc',
-        wireId: 'wire-best-effort',
-        functionId: 'bestEffortFunc',
-        audit: { durability: 'best-effort' },
-        logger: {
-          warn: (...args: unknown[]) => warnings.push(args),
-        },
-      } as any
-    )
-
-    await audit.write({
-      type: 'db.query',
-      source: 'auto',
-      queryId: 'q-1',
-    })
-
-    await assert.doesNotReject(async () => {
-      await audit.close()
-    })
-    assert.equal(warnings.length, 1)
-    assert.equal(warnings[0]?.[0], 'best-effort audit flush failed')
-  })
-})