@pikku/core 0.12.83 → 0.12.86

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

@@ -0,0 +1,282 @@
+import { mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import type {
+  ScenarioArtifact,
+  ScenarioResult,
+  ScenarioRunRecord,
+  ScenarioRunStore,
+  ScenarioRunSummary,
+} from '../wirings/workflow/scenario-run.types.js'
+
+/** The record, beside the images and footage the same run produced. */
+const RECORD_FILE = 'run.json'
+
+/**
+ * A run id is a path segment, and `get('../../etc')` is a file read.
+ *
+ * Ids are generated here, so anything failing this arrived from outside and is
+ * refused rather than sanitised — a request for a run that cannot exist is a
+ * request for a run that does not exist.
+ */
+const SAFE_RUN_ID = /^[A-Za-z0-9][A-Za-z0-9_-]*$/
+
+/** Counts and duration, derived rather than stored so they cannot disagree. */
+export const scenarioRunSummary = (
+  record: ScenarioRunRecord
+): ScenarioRunSummary => ({
+  runId: record.runId,
+  environment: record.environment,
+  surface: record.surface,
+  status: record.status,
+  startedAt: record.startedAt,
+  finishedAt: record.finishedAt,
+  durationMs: record.finishedAt
+    ? new Date(record.finishedAt).getTime() -
+      new Date(record.startedAt).getTime()
+    : undefined,
+  passed: record.results.filter((r) => r.status === 'passed').length,
+  failed: record.results.filter((r) => r.status === 'failed').length,
+  skipped: record.skipped.length,
+  artifacts: record.results.reduce(
+    (total, result) => total + (result.artifacts?.length ?? 0),
+    0
+  ),
+})
+
+/**
+ * What a scenario artifact is served as.
+ *
+ * A short, closed list rather than a MIME database: a run produces images and
+ * recordings and nothing else, and anything unrecognised is served as bytes the
+ * browser is told not to interpret.
+ */
+const CONTENT_TYPES: Record<string, string> = {
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  webp: 'image/webp',
+  mp4: 'video/mp4',
+  webm: 'video/webm',
+}
+
+export const scenarioArtifactContentType = (path: string): string =>
+  CONTENT_TYPES[path.split('.').pop()?.toLowerCase() ?? ''] ??
+  'application/octet-stream'
+
+/**
+ * An artifact path is a content key from the record, but it arrives from a
+ * client and is joined onto a directory. Anything that could climb out of the
+ * run, or name something other than a file inside it, is refused.
+ */
+const SAFE_ARTIFACT_PATH =
+  /^[A-Za-z0-9][A-Za-z0-9._-]*(\/[A-Za-z0-9][A-Za-z0-9._-]*)*$/
+
+export interface FileScenarioRunStoreOptions {
+  /** The directory runs live under — one folder per run, named by its id. */
+  dir: string
+  /**
+   * How many runs to keep. Older ones are deleted, with their artifacts, as a
+   * new run opens.
+   *
+   * Bounded on purpose: a run with video is megabytes, and an unbounded history
+   * beside a project is a directory nobody notices until it is enormous.
+   */
+  keep?: number
+}
+
+const DEFAULT_KEEP = 20
+
+/**
+ * Scenario run history as files on disk — the OSS store.
+ *
+ * One folder per run holding its record and everything it filed, which makes a
+ * run a thing you can open, copy, attach to an issue or delete with `rm -rf`.
+ * A hosted project swaps this for a table and an object store; the console
+ * reads the same shapes from either.
+ *
+ * Writes are serialised through one chain. Scenarios finish one at a time, but
+ * `recordScenario` is read-modify-write on a single file, and a store that
+ * corrupts its own history the first time two things overlap is worse than no
+ * history.
+ */
+export class FileScenarioRunStore implements ScenarioRunStore {
+  private writes: Promise<unknown> = Promise.resolve()
+
+  constructor(private readonly options: FileScenarioRunStoreOptions) {}
+
+  async start(record: ScenarioRunRecord): Promise<void> {
+    await this.serialise(async () => {
+      await this.write(record)
+      await this.prune(record.runId)
+    })
+  }
+
+  async recordScenario(runId: string, result: ScenarioResult): Promise<void> {
+    await this.serialise(async () => {
+      const record = await this.read(runId)
+      if (!record) {
+        return
+      }
+      record.results.push(result)
+      await this.write(record)
+    })
+  }
+
+  async attachArtifacts(
+    runId: string,
+    artifacts: ScenarioArtifact[]
+  ): Promise<void> {
+    if (artifacts.length === 0) {
+      return
+    }
+    await this.serialise(async () => {
+      const record = await this.read(runId)
+      if (!record) {
+        return
+      }
+      for (const artifact of artifacts) {
+        const result = record.results.find(
+          (candidate) => candidate.name === artifact.scenario
+        )
+        // An artifact whose scenario is not in the results belongs to a
+        // scenario that never produced one — it is dropped rather than filed
+        // under a run-level bucket nothing renders.
+        if (result) {
+          result.artifacts = [...(result.artifacts ?? []), artifact]
+        }
+      }
+      await this.write(record)
+    })
+  }
+
+  async finish(
+    runId: string,
+    outcome: Pick<
+      ScenarioRunRecord,
+      'status' | 'finishedAt' | 'skipped' | 'hookFailures'
+    >
+  ): Promise<void> {
+    await this.serialise(async () => {
+      const record = await this.read(runId)
+      if (!record) {
+        return
+      }
+      await this.write({ ...record, ...outcome })
+    })
+  }
+
+  async readArtifact(
+    runId: string,
+    path: string
+  ): Promise<
+    { body: Uint8Array<ArrayBuffer>; contentType: string } | undefined
+  > {
+    if (!SAFE_RUN_ID.test(runId) || !SAFE_ARTIFACT_PATH.test(path)) {
+      return undefined
+    }
+    try {
+      const file = await readFile(
+        join(this.options.dir, runId, ...path.split('/'))
+      )
+      return {
+        body: new Uint8Array(file),
+        contentType: scenarioArtifactContentType(path),
+      }
+    } catch {
+      return undefined
+    }
+  }
+
+  async list(options: { limit?: number } = {}): Promise<ScenarioRunSummary[]> {
+    const summaries: ScenarioRunSummary[] = []
+    for (const runId of await this.runIds()) {
+      const record = await this.read(runId)
+      if (record) {
+        summaries.push(scenarioRunSummary(record))
+      }
+    }
+    summaries.sort((a, b) => b.startedAt.localeCompare(a.startedAt))
+    return options.limit ? summaries.slice(0, options.limit) : summaries
+  }
+
+  async get(runId: string): Promise<ScenarioRunRecord | undefined> {
+    return this.read(runId)
+  }
+
+  async remove(runId: string): Promise<void> {
+    if (!SAFE_RUN_ID.test(runId)) {
+      return
+    }
+    await rm(join(this.options.dir, runId), { recursive: true, force: true })
+  }
+
+  /** Where this run's artifacts live, for a driver writing into it. */
+  runDir(runId: string): string {
+    return join(this.options.dir, runId)
+  }
+
+  private serialise<T>(work: () => Promise<T>): Promise<T> {
+    const next = this.writes.then(work, work)
+    // Swallowed on the CHAIN only, so one failed write does not reject every
+    // later one; the caller still sees its own rejection through `next`.
+    this.writes = next.catch(() => {})
+    return next
+  }
+
+  private async read(runId: string): Promise<ScenarioRunRecord | undefined> {
+    if (!SAFE_RUN_ID.test(runId)) {
+      return undefined
+    }
+    try {
+      const raw = await readFile(
+        join(this.options.dir, runId, RECORD_FILE),
+        'utf-8'
+      )
+      return JSON.parse(raw) as ScenarioRunRecord
+    } catch {
+      // A folder with artifacts but no readable record is a run that was killed
+      // mid-write. It is not listable, and it is not an error either.
+      return undefined
+    }
+  }
+
+  private async write(record: ScenarioRunRecord): Promise<void> {
+    const dir = join(this.options.dir, record.runId)
+    await mkdir(dir, { recursive: true })
+    await writeFile(
+      join(dir, RECORD_FILE),
+      JSON.stringify(record, null, 2) + '\n'
+    )
+  }
+
+  private async runIds(): Promise<string[]> {
+    try {
+      const entries = await readdir(this.options.dir, { withFileTypes: true })
+      return entries
+        .filter((entry) => entry.isDirectory() && SAFE_RUN_ID.test(entry.name))
+        .map((entry) => entry.name)
+    } catch {
+      return []
+    }
+  }
+
+  /**
+   * Drop the oldest runs past the limit, never the one just opened — a `keep`
+   * of zero or one must still leave the run being started.
+   */
+  private async prune(keeping: string): Promise<void> {
+    const keep = this.options.keep ?? DEFAULT_KEEP
+    const dated: Array<{ runId: string; startedAt: string }> = []
+    for (const runId of await this.runIds()) {
+      if (runId === keeping) {
+        continue
+      }
+      const record = await this.read(runId)
+      dated.push({ runId, startedAt: record?.startedAt ?? '' })
+    }
+    dated.sort((a, b) => b.startedAt.localeCompare(a.startedAt))
+    for (const { runId } of dated.slice(Math.max(keep - 1, 0))) {
+      await rm(join(this.options.dir, runId), { recursive: true, force: true })
+    }
+  }
+}

package/src/services/http-personas-converse.test.ts

@@ -4,7 +4,7 @@ import { createServer, type Server } from 'node:http'
 
 import { createHttpPersonas } from './http-personas.js'
 import { pikkuState, resetPikkuState } from '../pikku-state.js'
-import type { AIAgentStepResult } from './ai-agent-runner-service.js'
+import type { AgentStepResult } from './agent-runner-service.js'
 
 /**
  * Minimal target app exposing the agent HTTP surface: actor sign-in, the agent
@@ -104,7 +104,7 @@ const scriptedRunner = () => {
   return {
     run: async (params: {
       outputSchema?: unknown
-    }): Promise<AIAgentStepResult> => {
+    }): Promise<AgentStepResult> => {
       const props =
         (params.outputSchema as { properties?: Record<string, unknown> })
           ?.properties ?? {}
@@ -135,7 +135,7 @@ const wireRunner = () => {
       error: () => {},
       debug: () => {},
     },
-    aiAgentRunner: scriptedRunner(),
+    agentRunner: scriptedRunner(),
   } as any)
 }
 

package/src/services/http-personas.ts

@@ -43,7 +43,7 @@ export interface HttpPersonasConfig {
   /**
    * Default model a persona thinks with when `converse(...)` is called without
    * an explicit `model`. Its own turns/approvals/evaluation run in-process via
-   * the configured `aiAgentRunner`.
+   * the configured `agentRunner`.
    */
   model?: string
 }
@@ -107,8 +107,8 @@ export class HttpPersona implements ScenarioPersona {
   }
 
   async converse(options: ConverseOptions): Promise<ActorFlowVerdict> {
-    const { aiAgentRunner } = getSingletonServices()
-    if (!aiAgentRunner) {
+    const { agentRunner } = getSingletonServices()
+    if (!agentRunner) {
       throw new AIProviderNotConfiguredError()
     }
     const model = options.model ?? this.config.model
@@ -129,7 +129,7 @@ export class HttpPersona implements ScenarioPersona {
       approvals: options.approvals,
       model,
       maxTurns: options.maxTurns,
-      llm: (params) => aiAgentRunner.run(params),
+      llm: (params) => agentRunner.run(params),
       target: {
         run: (message) =>
           this.agentRun(options.agent, message, threadId, resourceId),

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

@@ -1,17 +1,17 @@
 import type {
-  AIRunStateService,
+  AgentRunStateService,
   CreateRunInput,
   SaveScoreInput,
-} from './ai-run-state-service.js'
+} from './agent-run-state-service.js'
 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 class InMemoryAIRunStateService implements AIRunStateService {
+export class InMemoryAgentRunStateService implements AgentRunStateService {
   private runs = new Map<string, AgentRunState>()
-  private scores = new Map<string, AIRunScore[]>()
+  private scores = new Map<string, AgentRunScore[]>()
   private counter = 0
 
   async createRun(run: CreateRunInput): Promise<string> {
@@ -81,7 +81,7 @@ export class InMemoryAIRunStateService implements AIRunStateService {
     this.scores.set(score.runId, existing)
   }
 
-  async getScores(runId: string): Promise<AIRunScore[]> {
+  async getScores(runId: string): Promise<AgentRunScore[]> {
     return [...(this.scores.get(runId) ?? [])]
   }
 }

package/src/services/in-memory-workflow-service.ts

@@ -1,7 +1,7 @@
 import { randomUUID } from 'crypto'
 import { PikkuWorkflowService } from '../wirings/workflow/pikku-workflow-service.js'
 import { isExpectedError } from '../errors/error-handler.js'
-import type { SerializedError } from '../types/core.types.js'
+import type { SerializedError } from '../errors/serialized-error.js'
 import type {
   WorkflowPlannedStep,
   WorkflowQueueOptions,

package/src/services/index.ts

@@ -20,8 +20,14 @@ export {
 } from './queue-webhook-service.js'
 export { InMemoryQueueService } from './in-memory-queue-service.js'
 export { InMemoryTriggerService } from './in-memory-trigger-service.js'
-export { InMemoryAIRunStateService } from './in-memory-ai-run-state-service.js'
+export { InMemoryAgentRunStateService } from './in-memory-agent-run-state-service.js'
 export { LocalGatewayService } from './local-gateway-service.js'
+export {
+  FileScenarioRunStore,
+  scenarioArtifactContentType,
+  scenarioRunSummary,
+  type FileScenarioRunStoreOptions,
+} from './file-scenario-run-store.js'
 export type {
   ContentService,
   SignContentKeyArgs,
@@ -67,8 +73,8 @@ export type { SessionService } from './user-session-service.js'
 export type {
   ScheduledTaskSummary,
   ScheduledTaskInfo,
-  SchedulerService,
 } from './scheduler-service.js'
+export { SchedulerService } from './scheduler-service.js'
 export type { TriggerService } from './trigger-service.js'
 export type { GatewayService } from './gateway-service.js'
 export type {
@@ -77,19 +83,19 @@ export type {
   DeploymentInfo,
   DeploymentServiceConfig,
 } from './deployment-service.js'
-export type { AIStorageService } from './ai-storage-service.js'
+export type { AgentStorageService } from './agent-storage-service.js'
 export type {
-  AIAgentRunnerParams,
-  AIAgentRunnerResult,
-  AIAgentStepResult,
-  AIAgentRunnerService,
-} from './ai-agent-runner-service.js'
+  AgentRunnerParams,
+  AgentRunnerResult,
+  AgentStepResult,
+  AgentRunnerService,
+} from './agent-runner-service.js'
 export type { AIEmbeddingService } from './ai-embedding-service.js'
 export type {
   CreateRunInput,
   SaveScoreInput,
-  AIRunStateService,
-} from './ai-run-state-service.js'
+  AgentRunStateService,
+} from './agent-run-state-service.js'
 export type { CredentialMeta } from './typed-secret-service.js'
 export type { CredentialService } from './credential-service.js'
 export { TypedCredentialService } from './typed-credential-service.js'
@@ -151,3 +157,9 @@ export {
   SecretHostNotAllowedError,
   assertSecretAllowedForHost,
 } from './secret-host-binding.js'
+export type {
+  AuditFacets,
+  AuditQuery,
+  AuditQueryResult,
+} from './audit-service.js'
+export { SecretAccessDeniedError, withoutSecrets } from './secretless.js'

package/src/services/local-content-request-handler.ts

@@ -78,8 +78,7 @@ const text = (status: number, body: string) =>
   })
 
 export type SignedContentVerification =
-  | { ok: true }
-  | { ok: false; status: number; body: string }
+  { ok: true } | { ok: false; status: number; body: string }
 
 /**
  * Verifies a signed content URL — the one function that decides whether a

package/src/services/local-secrets.ts

@@ -2,7 +2,7 @@ import {
   createSecretValue,
   isSecretValue,
   type SecretValue,
-} from '../secret-value.js'
+} from '../classification/secret-value.js'
 import { LocalVariablesService } from './local-variables.js'
 import type { SecretService, SecretValues } from './secret-service.js'
 import type { VariablesService } from './variables-service.js'

package/src/services/logger.ts

@@ -1,12 +1,12 @@
-import type { Safe } from '../secret-value.js'
+import type { Safe } from '../classification/secret-value.js'
 
 export enum LogLevel {
-  'trace',
-  'debug',
-  'info',
-  'warn',
-  'error',
-  'critical',
+  trace,
+  debug,
+  info,
+  warn,
+  error,
+  critical,
 }
 
 /**

package/src/services/meta-service.ts

@@ -27,10 +27,10 @@ import type { VariableDefinitionsMeta } from '../wirings/variable/variable.types
 import type {
   FunctionMeta,
   FunctionsMeta,
-  MiddlewareMetadata,
   PermissionMetadata,
-} from '../types/core.types.js'
-import type { AIAgentMeta } from '../wirings/ai-agent/ai-agent.types.js'
+} from '../function/function-meta.types.js'
+import type { MiddlewareMetadata } from '../middleware/middleware.types.js'
+import type { AgentsMeta } from '../wirings/agent/agent.types.js'
 import type { GatewaysMeta } from '../wirings/gateway/gateway.types.js'
 
 export type {
@@ -39,8 +39,8 @@ export type {
   MiddlewareMetadata as MiddlewareMeta,
   PermissionMetadata as PermissionMeta,
 }
-export type AgentsMeta = AIAgentMeta
-export type AgentMeta = AIAgentMeta[string]
+export type { AgentsMeta }
+export type AgentMeta = AgentsMeta[string]
 
 export interface MCPMeta {
   resources: MCPResourceMeta

package/src/services/queue-webhook-service.test.ts

@@ -14,7 +14,7 @@ import { InMemoryQueueService } from './in-memory-queue-service.js'
 import { wireQueueWorker } from '../wirings/queue/queue-runner.js'
 import { resetPikkuState, pikkuState } from '../pikku-state.js'
 import type { JobOptions } from '../wirings/queue/queue.types.js'
-import { createSecretValue } from '../secret-value.js'
+import { createSecretValue } from '../classification/secret-value.js'
 
 const noopLogger = { error() {}, info() {}, warn() {}, debug() {} }
 

package/src/services/scoped-secret-service.ts

@@ -1,4 +1,4 @@
-import type { SecretValue } from '../secret-value.js'
+import type { SecretValue } from '../classification/secret-value.js'
 import type { SecretService, SecretValues } from './secret-service.js'
 
 export class ScopedSecretService implements SecretService {

package/src/services/secret-service.ts

@@ -1,4 +1,4 @@
-import type { SecretValue } from '../secret-value.js'
+import type { SecretValue } from '../classification/secret-value.js'
 
 /** A record of secrets, each still wrapped. */
 export type SecretValues<T> = { [K in keyof T]: SecretValue<T[K]> }

package/src/services/typed-secret-service.test.ts

@@ -124,4 +124,56 @@ describe('TypedSecretService', () => {
     assert.strictEqual(missing.length, 1)
     assert.strictEqual(missing[0].secretId, 'GITHUB_TOKEN')
   })
+
+  test('an optional secret that is missing resolves undefined instead of throwing', async () => {
+    // getSecret throws for a missing secret, which is right for a required one:
+    // the app cannot run without it. An optional secret's absence is a supported
+    // state, so throwing forces every caller into a `.catch(() => null)` that
+    // also swallows a real vault failure.
+    const service = new TypedSecretService(createMockSecrets(), {
+      SCENARIO_ACTOR_SECRET: {
+        name: 'scenarioActor',
+        displayName: 'Scenario Actor Secret',
+        optional: true,
+      },
+    })
+    assert.strictEqual(await service.getSecret('SCENARIO_ACTOR_SECRET'), undefined)
+  })
+
+  test('an optional secret that IS set resolves its value', async () => {
+    const store = new Map([['SCENARIO_ACTOR_SECRET', '"shh"']])
+    const service = new TypedSecretService(createMockSecrets(store), {
+      SCENARIO_ACTOR_SECRET: {
+        name: 'scenarioActor',
+        displayName: 'Scenario Actor Secret',
+        optional: true,
+      },
+    })
+    assert.strictEqual(await service.getSecret('SCENARIO_ACTOR_SECRET'), 'shh')
+  })
+
+  test('a missing secret still throws unless it declared itself optional', async () => {
+    const service = new TypedSecretService(createMockSecrets(), {
+      STRIPE_KEY: { name: 'stripe', displayName: 'Stripe' },
+    })
+    await assert.rejects(() => service.getSecret('STRIPE_KEY'))
+  })
+
+  test('an optional secret does not re-hit the store once resolved', async () => {
+    let reads = 0
+    const base = createMockSecrets()
+    const service = new TypedSecretService(
+      {
+        ...base,
+        hasSecret: async (key: string) => {
+          reads++
+          return base.hasSecret(key)
+        },
+      },
+      { OPTIONAL: { name: 'opt', displayName: 'Optional', optional: true } }
+    )
+    await service.getSecret('OPTIONAL')
+    await service.getSecret('OPTIONAL')
+    assert.strictEqual(reads, 1)
+  })
 })

package/src/services/typed-secret-service.ts

@@ -1,6 +1,17 @@
-import type { SecretValue } from '../secret-value.js'
+import type { SecretValue } from '../classification/secret-value.js'
 import type { SecretService, SecretValues } from './secret-service.js'
 
+/**
+ * The wrapper, or `undefined` when the generated map declares the key as an
+ * optional property. The `undefined` has to be lifted OUT of `SecretValue` —
+ * a missing optional secret resolves to `undefined` itself, not to a wrapper
+ * around it, so `SecretValue<T | undefined>` would type a value that never
+ * exists and hide the `undefined` behind a `.reveal()` the caller never reaches.
+ */
+export type SecretResult<T> = undefined extends T
+  ? SecretValue<Exclude<T, undefined>> | undefined
+  : SecretValue<T>
+
 export interface CredentialStatus {
   secretId: string
   name: string
@@ -12,6 +23,12 @@ export interface CredentialStatus {
 export type CredentialMeta = {
   name: string
   displayName: string
+  /**
+   * Declared `optional: true`, so absence is a supported state rather than a
+   * misconfiguration. The generated map types the key as an optional property,
+   * which is what puts `undefined` in `getSecret`'s return type.
+   */
+  optional?: boolean
   oauth2?: { tokenSecretId: string }
 }
 
@@ -28,12 +45,19 @@ export class TypedSecretService<
 
   async getSecret<K extends keyof TMap & string>(
     key: K
-  ): Promise<SecretValue<TMap[K]>>
+  ): Promise<SecretResult<TMap[K]>>
   async getSecret<T = string>(key: string): Promise<SecretValue<T>>
   async getSecret(key: string): Promise<unknown> {
     if (this.cache.has(key)) {
       return this.cache.get(key)
     }
+    if (
+      this.credentialsMeta[key]?.optional &&
+      !(await this.secrets.hasSecret(key))
+    ) {
+      this.cache.set(key, undefined)
+      return undefined
+    }
     const value = await this.secrets.getSecret(key)
     this.cache.set(key, value)
     return value

package/src/services/webhook-service.ts

@@ -1,6 +1,6 @@
 import { NotImplementedError } from '../errors/errors.js'
 import { hmacSha256Hex, timingSafeStringEqual } from '../utils/hmac.js'
-import type { Safe } from '../secret-value.js'
+import type { Safe } from '../classification/secret-value.js'
 
 export interface SendWebhookInput {
   url: string

package/src/services/workflow-service.ts

@@ -1,4 +1,5 @@
-import type { CoreUserSession, SerializedError } from '../types/core.types.js'
+import type { CoreUserSession } from '../types/core.types.js'
+import type { SerializedError } from '../errors/serialized-error.js'
 import type {
   WorkflowRun,
   WorkflowPlannedStep,