@pikku/core 0.12.83 → 0.12.86

package/src/public-surface.test.ts

@@ -1,6 +1,6 @@
 import { describe, test } from 'node:test'
 import assert from 'node:assert/strict'
-import { readFileSync } from 'node:fs'
+import { readdirSync, readFileSync } from 'node:fs'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import { dirname, join, resolve } from 'node:path'
 
@@ -16,6 +16,34 @@ const expected: Record<string, string[]> = JSON.parse(
 
 const subpaths = packageJson.exports as Record<string, string>
 
+/**
+ * `exports` entries, with a wildcard subpath replaced by the files it matches.
+ *
+ * A wildcard subpath would pin a pattern rather than a surface, and a module
+ * dropped into the matched directory would appear in the published API without
+ * a diff. Expanding it is what keeps every entry point's exports in
+ * `public-surface.json` under the same guarantee. `exports` declares none
+ * today, and this keeps that from being a silent assumption.
+ */
+const entryPoints = (): [string, string][] =>
+  Object.entries(subpaths).flatMap(([subpath, dist]) => {
+    if (!subpath.includes('*')) return [[subpath, dist] as [string, string]]
+
+    const [prefix] = dist.split('*') as [string]
+    const directory = resolve(packageRoot, prefix.replace('./dist/', './src/'))
+    return readdirSync(directory, { recursive: true, encoding: 'utf-8' })
+      .filter((file) => file.endsWith('.ts') && !file.endsWith('.d.ts'))
+      .map((file) => file.slice(0, -'.ts'.length))
+      .sort()
+      .map(
+        (area) =>
+          [subpath.replace('*', area), dist.replace('*', area)] as [
+            string,
+            string,
+          ]
+      )
+  })
+
 /**
  * Every runtime export reachable through an entry point, keyed by subpath.
  *
@@ -24,7 +52,7 @@ const subpaths = packageJson.exports as Record<string, string>
  */
 const actualSurface = async () => {
   const surface: Record<string, string[]> = {}
-  for (const [subpath, dist] of Object.entries(subpaths)) {
+  for (const [subpath, dist] of entryPoints()) {
     const src = resolve(packageRoot, dist.replace('./dist/', './src/'))
     const module = await import(pathToFileURL(src).href)
     surface[subpath] = Object.keys(module).sort()
@@ -38,7 +66,7 @@ const REGENERATE =
 
 describe('the published surface is the surface we meant to publish', () => {
   test('every export subpath resolves to a source file', () => {
-    const missing = Object.entries(subpaths).filter(([, dist]) => {
+    const missing = entryPoints().filter(([, dist]) => {
       try {
         readFileSync(
           resolve(packageRoot, dist.replace('./dist/', './src/')).replace(

package/src/remote.test.ts

@@ -4,7 +4,7 @@ import { buildRemoteHeaders } from './remote.js'
 import { pikkuRemoteAuthMiddleware } from './middleware/remote-auth.js'
 import { resetPikkuState } from './pikku-state.js'
 import { WeakKeyMaterialError } from './errors/errors.js'
-import { createSecretValue } from './secret-value.js'
+import { createSecretValue } from './classification/secret-value.js'
 
 beforeEach(() => {
   resetPikkuState()

package/src/removed-legacy-exports.test.ts

@@ -14,11 +14,15 @@ const thisFile = fileURLToPath(import.meta.url)
  * They survived as throwing stubs only so the pinned bootstrap CLI could
  * resolve the import; `@pikku/cli@0.12.96` emits none of them, so the stubs
  * went too.
+ *
+ * `ZodLike` sat on the package root, which is now `bootstrap-compat/root.ts` —
+ * what `.` resolves to for the pinned CLI's sake, and the only place a name
+ * could return to the root from.
  */
 const REMOVED = [
   { name: 'addTagPermission', entry: './middleware/index.js' },
   { name: 'addHTTPPermission', entry: './wirings/http/index.js' },
-  { name: 'ZodLike', entry: './index.js' },
+  { name: 'ZodLike', entry: './bootstrap-compat/root.js' },
 ]
 
 const collectSourceFiles = (directory: string): string[] =>

package/src/services/{ai-run-state-service.ts → agent-run-state-service.ts}

@@ -1,14 +1,14 @@
 import type {
   AgentRunState,
   PendingApproval,
-} from '../wirings/ai-agent/ai-agent.types.js'
-import type { AIRunScore } from '../wirings/ai-scorer/ai-scorer.types.js'
+} 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<AIRunScore, 'createdAt'>
+export type SaveScoreInput = Omit<AgentRunScore, 'createdAt'>
 
-export interface AIRunStateService {
+export interface AgentRunStateService {
   createRun(run: CreateRunInput): Promise<string>
   updateRun(runId: string, updates: Partial<AgentRunState>): Promise<void>
   getRun(runId: string): Promise<AgentRunState | null>
@@ -33,5 +33,5 @@ export interface AIRunStateService {
    * grade that was acted on.
    */
   saveScore(score: SaveScoreInput): Promise<void>
-  getScores(runId: string): Promise<AIRunScore[]>
+  getScores(runId: string): Promise<AgentRunScore[]>
 }

package/src/services/{ai-agent-runner-service.ts → agent-runner-service.ts}

@@ -1,18 +1,18 @@
 import type {
-  AIMessage,
-  AIAgentStep,
-  AIAgentToolDef,
-  AIStreamChannel,
-} from '../wirings/ai-agent/ai-agent.types.js'
+  AgentMessage,
+  AgentStep,
+  AgentToolDef,
+  AgentStreamChannel,
+} from '../wirings/agent/agent.types.js'
 
 export type AIProviderOptions = Record<string, Record<string, unknown>>
 
-export type AIAgentRunnerParams = {
+export type AgentRunnerParams = {
   model: string
   temperature?: number
   instructions: string
-  messages: AIMessage[]
-  tools: AIAgentToolDef[]
+  messages: AgentMessage[]
+  tools: AgentToolDef[]
   maxSteps: number
   toolChoice: 'auto' | 'required' | 'none'
   outputSchema?: Record<string, unknown>
@@ -21,7 +21,7 @@ export type AIAgentRunnerParams = {
   agentId?: string
   /**
    * Cancels the model call itself, not just delivery of its output. Set by
-   * `streamAIAgent` from the run's interrupt handle so a voice barge-in stops
+   * `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.
@@ -41,14 +41,14 @@ export type AIAgentRunnerParams = {
   providerOptions?: AIProviderOptions
 }
 
-export type AIAgentRunnerResult = {
+export type AgentRunnerResult = {
   text: string
   object?: unknown
-  steps: AIAgentStep[]
+  steps: AgentStep[]
   usage: { inputTokens: number; outputTokens: number }
 }
 
-export type AIAgentStepResult = {
+export type AgentStepResult = {
   text: string
   object?: unknown
   toolCalls: { toolCallId: string; toolName: string; args: unknown }[]
@@ -216,12 +216,12 @@ export type AIRerankResult<VALUE extends string | Record<string, unknown>> = {
   response?: unknown
 }
 
-export interface AIAgentRunnerService {
+export interface AgentRunnerService {
   stream(
-    params: AIAgentRunnerParams,
-    channel: AIStreamChannel
-  ): Promise<AIAgentStepResult>
-  run(params: AIAgentRunnerParams): Promise<AIAgentStepResult>
+    params: AgentRunnerParams,
+    channel: AgentStreamChannel
+  ): Promise<AgentStepResult>
+  run(params: AgentRunnerParams): Promise<AgentStepResult>
   transcribe?(params: AITranscriptionParams): Promise<AITranscriptionResult>
   generateSpeech?(
     params: AIGenerateSpeechParams
@@ -234,5 +234,5 @@ export interface AIAgentRunnerService {
   ): 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): AIAgentRunnerService
+  withApiKey?(apiKey: string): AgentRunnerService
 }

package/src/services/{ai-storage-service.ts → agent-storage-service.ts}

@@ -1,6 +1,6 @@
-import type { AIThread, AIMessage } from '../wirings/ai-agent/ai-agent.types.js'
+import type { AgentThread, AgentMessage } from '../wirings/agent/agent.types.js'
 
-export interface AIStorageService {
+export interface AgentStorageService {
   createThread(
     resourceId: string,
     options?: {
@@ -8,11 +8,11 @@ export interface AIStorageService {
       title?: string
       metadata?: Record<string, unknown>
     }
-  ): Promise<AIThread>
+  ): Promise<AgentThread>
 
-  getThread(threadId: string): Promise<AIThread>
+  getThread(threadId: string): Promise<AgentThread>
 
-  getThreads(resourceId: string): Promise<AIThread[]>
+  getThreads(resourceId: string): Promise<AgentThread[]>
 
   deleteThread(threadId: string): Promise<void>
 
@@ -22,9 +22,9 @@ export interface AIStorageService {
       lastN?: number
       cursor?: string
     }
-  ): Promise<AIMessage[]>
+  ): Promise<AgentMessage[]>
 
-  saveMessages(threadId: string, messages: AIMessage[]): Promise<void>
+  saveMessages(threadId: string, messages: AgentMessage[]): Promise<void>
 
   getWorkingMemory(
     id: string,

package/src/services/audit-service.ts

@@ -4,7 +4,7 @@ import type {
   PikkuWiringTypes,
 } from '../types/core.types.js'
 import type { Logger } from './logger.js'
-import type { Safe } from '../secret-value.js'
+import type { Safe } from '../classification/secret-value.js'
 
 export type AuditDurability = 'best-effort' | 'transactional'
 export type AuditOutcome = 'success' | 'failed' | 'denied'

package/src/services/credential-wire-service.ts

@@ -1,4 +1,4 @@
-import { isSecretValue } from '../secret-value.js'
+import { isSecretValue } from '../classification/secret-value.js'
 import type { CredentialService } from './credential-service.js'
 import { defaultPikkuUserIdResolver } from './pikku-user-id.js'
 import type { PikkuRawWire } from '../types/core.types.js'

package/src/services/email-service.ts

@@ -1,4 +1,4 @@
-import type { Safe } from '../secret-value.js'
+import type { Safe } from '../classification/secret-value.js'
 
 export interface EmailTemplateReference {
   name: string
@@ -35,9 +35,7 @@ export interface SendTemplateEmailInput extends BaseSendEmailInput {
 }
 
 export type SendEmailInput =
-  | SendTextEmailInput
-  | SendHTMLEmailInput
-  | SendTemplateEmailInput
+  SendTextEmailInput | SendHTMLEmailInput | SendTemplateEmailInput
 
 export interface SendEmailResult {
   messageId?: string

package/src/services/file-scenario-run-store.test.ts

@@ -0,0 +1,349 @@
+import { describe, test, beforeEach, afterEach } from 'node:test'
+import assert from 'node:assert/strict'
+import {
+  mkdtempSync,
+  mkdirSync,
+  rmSync,
+  writeFileSync,
+  existsSync,
+} from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import {
+  FileScenarioRunStore,
+  scenarioRunSummary,
+} from './file-scenario-run-store.js'
+import type {
+  ScenarioResult,
+  ScenarioRunRecord,
+} from '../wirings/workflow/scenario-run.types.js'
+
+let dir: string
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'pikku-scenario-runs-'))
+})
+
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true })
+})
+
+const record = (
+  overrides: Partial<ScenarioRunRecord> = {}
+): ScenarioRunRecord => ({
+  runId: 'run-1',
+  environment: 'local',
+  surface: 'browser',
+  status: 'running',
+  startedAt: '2026-08-15T10:00:00.000Z',
+  results: [],
+  skipped: [],
+  hookFailures: [],
+  ...overrides,
+})
+
+const result = (overrides: Partial<ScenarioResult> = {}): ScenarioResult => ({
+  name: 'todos › a member adds one',
+  status: 'passed',
+  durationMs: 120,
+  ...overrides,
+})
+
+describe('FileScenarioRunStore', () => {
+  test('a run is readable from the moment it opens, before any scenario finishes', async () => {
+    const store = new FileScenarioRunStore({ dir })
+
+    await store.start(record())
+
+    const open = await store.get('run-1')
+    assert.equal(open?.status, 'running')
+    assert.deepEqual(open?.results, [])
+  })
+
+  test('scenarios accumulate as they finish, so a suite killed halfway keeps what ran', async () => {
+    const store = new FileScenarioRunStore({ dir })
+    await store.start(record())
+
+    await store.recordScenario('run-1', result({ name: 'one' }))
+    await store.recordScenario(
+      'run-1',
+      result({ name: 'two', status: 'failed' })
+    )
+
+    const partial = await store.get('run-1')
+    assert.deepEqual(
+      partial?.results.map((r) => r.name),
+      ['one', 'two']
+    )
+    assert.equal(
+      partial?.status,
+      'running',
+      'a run nobody finished is still running, not passed'
+    )
+  })
+
+  test('finishing settles the outcome and everything only known at the end', async () => {
+    const store = new FileScenarioRunStore({ dir })
+    await store.start(record())
+    await store.recordScenario('run-1', result())
+
+    await store.finish('run-1', {
+      status: 'failed',
+      finishedAt: '2026-08-15T10:00:30.000Z',
+      skipped: [{ name: 'quarantined', reason: 'flaky' }],
+      hookFailures: ['feature after hook failed: boom'],
+    })
+
+    const done = await store.get('run-1')
+    assert.equal(done?.status, 'failed')
+    assert.equal(done?.finishedAt, '2026-08-15T10:00:30.000Z')
+    assert.deepEqual(done?.skipped, [{ name: 'quarantined', reason: 'flaky' }])
+    assert.equal(done?.results.length, 1, 'finishing does not lose the results')
+  })
+
+  test('concurrent scenario writes never lose one to a read-modify-write race', async () => {
+    const store = new FileScenarioRunStore({ dir })
+    await store.start(record())
+
+    await Promise.all(
+      Array.from({ length: 20 }, (_, i) =>
+        store.recordScenario('run-1', result({ name: `scenario-${i}` }))
+      )
+    )
+
+    const all = await store.get('run-1')
+    assert.equal(all?.results.length, 20)
+  })
+
+  test('runs list newest first, summarised without loading their stacks', async () => {
+    const store = new FileScenarioRunStore({ dir })
+    await store.start(
+      record({ runId: 'older', startedAt: '2026-08-14T10:00:00.000Z' })
+    )
+    await store.start(
+      record({ runId: 'newer', startedAt: '2026-08-15T10:00:00.000Z' })
+    )
+    await store.recordScenario(
+      'newer',
+      result({
+        artifacts: [{ scenario: 'x', kind: 'video', path: 'x/admin.mp4' }],
+      })
+    )
+    await store.recordScenario('newer', result({ status: 'failed' }))
+    await store.finish('newer', {
+      status: 'failed',
+      finishedAt: '2026-08-15T10:00:05.000Z',
+      skipped: [{ name: 'held', reason: 'no browser' }],
+      hookFailures: [],
+    })
+
+    const runs = await store.list()
+
+    assert.deepEqual(
+      runs.map((r) => r.runId),
+      ['newer', 'older']
+    )
+    assert.deepEqual(
+      { ...runs[0] },
+      {
+        runId: 'newer',
+        environment: 'local',
+        surface: 'browser',
+        status: 'failed',
+        startedAt: '2026-08-15T10:00:00.000Z',
+        finishedAt: '2026-08-15T10:00:05.000Z',
+        durationMs: 5000,
+        passed: 1,
+        failed: 1,
+        skipped: 1,
+        artifacts: 1,
+      }
+    )
+  })
+
+  test('a limit takes the newest runs, not whichever the filesystem returned first', async () => {
+    const store = new FileScenarioRunStore({ dir })
+    for (const day of ['11', '12', '13']) {
+      await store.start(
+        record({
+          runId: `run-${day}`,
+          startedAt: `2026-08-${day}T10:00:00.000Z`,
+        })
+      )
+    }
+
+    const runs = await store.list({ limit: 2 })
+
+    assert.deepEqual(
+      runs.map((r) => r.runId),
+      ['run-13', 'run-12']
+    )
+  })
+
+  test('opening a run drops the oldest past the limit, with everything they filed', async () => {
+    const store = new FileScenarioRunStore({ dir, keep: 2 })
+    for (const day of ['11', '12', '13']) {
+      await store.start(
+        record({
+          runId: `run-${day}`,
+          startedAt: `2026-08-${day}T10:00:00.000Z`,
+        })
+      )
+      writeFileSync(join(dir, `run-${day}`, 'video.mp4'), 'x')
+    }
+
+    assert.deepEqual(
+      (await store.list()).map((r) => r.runId),
+      ['run-13', 'run-12']
+    )
+    assert.equal(
+      existsSync(join(dir, 'run-11')),
+      false,
+      'the pruned run takes its artifacts with it'
+    )
+  })
+
+  test('a keep of one still leaves the run being opened', async () => {
+    const store = new FileScenarioRunStore({ dir, keep: 1 })
+    await store.start(record({ runId: 'first' }))
+    await store.start(record({ runId: 'second' }))
+
+    assert.deepEqual(
+      (await store.list()).map((r) => r.runId),
+      ['second']
+    )
+  })
+
+  test('artifacts are filed against the scenario the run knows them by', async () => {
+    const store = new FileScenarioRunStore({ dir })
+    await store.start(record())
+    await store.recordScenario('run-1', result({ name: 'checkout › breaks' }))
+    await store.recordScenario('run-1', result({ name: 'checkout › works' }))
+
+    await store.attachArtifacts('run-1', [
+      { scenario: 'checkout › breaks', kind: 'video', path: 'a/admin.mp4' },
+      {
+        scenario: 'checkout › breaks',
+        kind: 'failure',
+        path: 'a/failure-admin.png',
+      },
+      { scenario: 'a scenario that never ran', kind: 'video', path: 'b/x.mp4' },
+    ])
+
+    const [broke, worked] = (await store.get('run-1'))!.results
+    assert.deepEqual(
+      broke?.artifacts?.map((a) => a.path),
+      ['a/admin.mp4', 'a/failure-admin.png']
+    )
+    assert.equal(
+      worked?.artifacts,
+      undefined,
+      'a scenario that produced nothing gets no empty list to render'
+    )
+  })
+
+  test('a run id from outside cannot read its way out of the store', async () => {
+    const store = new FileScenarioRunStore({ dir })
+    writeFileSync(join(dir, 'run.json'), JSON.stringify(record()))
+
+    assert.equal(await store.get('..'), undefined)
+    assert.equal(await store.get('../..'), undefined)
+    assert.equal(existsSync(join(dir, 'run.json')), true)
+
+    await store.remove('../..')
+    assert.equal(
+      existsSync(dir),
+      true,
+      'a traversing id must not delete the store itself'
+    )
+  })
+
+  test('an artifact is served with the type its extension implies', async () => {
+    const store = new FileScenarioRunStore({ dir })
+    await store.start(record())
+    mkdirSync(join(dir, 'run-1', 'checkout'))
+    writeFileSync(join(dir, 'run-1', 'checkout', 'admin.mp4'), 'footage')
+    writeFileSync(join(dir, 'run-1', 'checkout', '01-shot.png'), 'image')
+
+    const video = await store.readArtifact('run-1', 'checkout/admin.mp4')
+    const shot = await store.readArtifact('run-1', 'checkout/01-shot.png')
+
+    assert.equal(video?.contentType, 'video/mp4')
+    assert.equal(Buffer.from(video!.body).toString(), 'footage')
+    assert.equal(shot?.contentType, 'image/png')
+  })
+
+  test('an artifact path cannot climb out of its run', async () => {
+    const store = new FileScenarioRunStore({ dir })
+    await store.start(record())
+    writeFileSync(join(dir, 'secret.txt'), 'not yours')
+
+    assert.equal(await store.readArtifact('run-1', '../secret.txt'), undefined)
+    assert.equal(
+      await store.readArtifact('run-1', 'checkout/../../secret.txt'),
+      undefined
+    )
+    assert.equal(await store.readArtifact('run-1', '/etc/hosts'), undefined)
+    assert.equal(
+      await store.readArtifact('run-1', 'checkout/never-taken.png'),
+      undefined,
+      'and an artifact that was never filed is simply absent'
+    )
+  })
+
+  test('an artifact of a run that never existed is absent, not an error', async () => {
+    const store = new FileScenarioRunStore({ dir })
+
+    assert.equal(await store.readArtifact('run-1', 'a/b.png'), undefined)
+  })
+
+  test('a half-written run is skipped rather than failing the whole listing', async () => {
+    const store = new FileScenarioRunStore({ dir })
+    await store.start(record())
+    mkdirSync(join(dir, 'killed-mid-write'))
+    writeFileSync(join(dir, 'killed-mid-write', 'run.json'), '{"runId":')
+
+    const runs = await store.list()
+
+    assert.deepEqual(
+      runs.map((r) => r.runId),
+      ['run-1']
+    )
+  })
+
+  test('a store with nothing in it lists nothing rather than throwing', async () => {
+    const store = new FileScenarioRunStore({ dir: join(dir, 'never-created') })
+
+    assert.deepEqual(await store.list(), [])
+    assert.equal(await store.get('run-1'), undefined)
+  })
+
+  test('recording against a run that does not exist is ignored, not invented', async () => {
+    const store = new FileScenarioRunStore({ dir })
+
+    await store.recordScenario('never-started', result())
+
+    assert.deepEqual(await store.list(), [])
+  })
+
+  test('removing a run takes its whole folder', async () => {
+    const store = new FileScenarioRunStore({ dir })
+    await store.start(record())
+    writeFileSync(join(dir, 'run-1', 'video.mp4'), 'x')
+
+    await store.remove('run-1')
+
+    assert.equal(existsSync(join(dir, 'run-1')), false)
+  })
+})
+
+describe('scenarioRunSummary', () => {
+  test('a run still going has no duration to report', () => {
+    const summary = scenarioRunSummary(record({ results: [result()] }))
+
+    assert.equal(summary.durationMs, undefined)
+    assert.equal(summary.status, 'running')
+    assert.equal(summary.passed, 1)
+  })
+})