@pikku/core 0.12.72 → 0.12.74

package/src/scopes.ts

@@ -5,13 +5,9 @@ const SEPARATOR = ':'
 const WILDCARD = '*'
 
 /**
- * Builds every grant that would satisfy `scope`: the scope itself, a 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 — holding a parent scope grants everything nested beneath it.
- *
- * For `admin:invoices:create` that is:
- *   admin:invoices:create, admin:invoices:create:*, *, admin:*, admin:invoices:*,
- *   admin, admin:invoices
+ * ancestor id.
  */
 const satisfyingGrants = (scope: string): string[] => {
   const segments = scope.split(SEPARATOR)
@@ -25,28 +21,10 @@ const satisfyingGrants = (scope: string): string[] => {
   return grants
 }
 
-/**
- * Checks whether `held` satisfies a single required scope.
- *
- * A grant satisfies a requirement when it is the scope itself, a plain ancestor
- * (`admin` covers `admin:invoices:create`), a wildcard at or above it (`admin:*`
- * covers `admin` and `admin:invoices:create`), or the bare `*`. A narrower grant
- * never satisfies a broader requirement — `admin:invoices` does not grant
- * `admin`.
- */
 const holds = (held: ReadonlySet<string>, scope: string): boolean =>
   satisfyingGrants(scope).some((grant) => held.has(grant))
 
-/**
- * The first required scope a set of held grants does not satisfy, or `null`
- * when every one is satisfied.
- *
- * Scopes are an AND gate: every entry in `required` must be satisfied. This is
- * deliberately distinct from `permissions`, which OR together — a scope can
- * only ever narrow access, so adding one to a function can never widen it.
- *
- * Fails closed: an absent `held` satisfies nothing.
- */
+/** The first required scope `held` does not satisfy, or `null`. Fails closed. */
 const firstUnsatisfied = (
   required: readonly string[] | undefined,
   held: Iterable<string> | undefined
@@ -65,17 +43,8 @@ const firstUnsatisfied = (
 }
 
 /**
- * Whether a set of held grants satisfies every required scope.
- *
  * The non-throwing counterpart to {@link verifyScopes}, for deciding rather
- * than enforcing — an authorization gate that falls back to another check when
- * it is not satisfied, rather than rejecting the request outright.
- *
- * Fails closed: an absent or empty `held` satisfies nothing. An empty
- * `required` is satisfied by anything.
- *
- * @param required - Scopes to check for. Empty means no gate.
- * @param held - The grants held, e.g. `session.scopes`. May be undefined.
+ * than enforcing. Fails closed; an empty `required` is satisfied by anything.
  */
 export const hasScopes = (
   required: readonly string[] | undefined,
@@ -83,19 +52,9 @@ export const hasScopes = (
 ): boolean => firstUnsatisfied(required, held) === null
 
 /**
- * Verifies that a session holds every required scope, throwing on the first
- * one it does not.
- *
- * Scopes are an AND gate: every entry in `required` must be satisfied. This is
- * deliberately distinct from `permissions`, which OR together — a scope can
- * only ever narrow access, so adding one to a function can never widen it.
- *
- * Fails closed: a session without a `scopes` field, or no session at all,
- * satisfies nothing.
- *
- * @param required - Scopes the function declares. Empty means no gate.
- * @param session - The session to check. May be undefined.
- * @throws {MissingScopeError} Naming the first unsatisfied scope.
+ * 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,

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

@@ -19,6 +19,26 @@ export type AIAgentRunnerParams = {
   /** 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
+   * `streamAIAgent` 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 AIAgentRunnerResult = {

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

@@ -1,31 +1,9 @@
-/**
- * A narrow, dedicated embedding service.
- *
- * Vector stores (Qdrant, Pinecone, Supabase/pgvector, …) depend on this to turn
- * text into vectors, at BOTH index time (ingest) and query time (search). The
- * embedding model is fixed at construction so those two moments cannot drift
- * into different vector spaces — a mismatch would silently break similarity
- * search. Provider addons (e.g. `@pikku/addon-openai`) implement it; the app
- * wires a single instance into `singletonServices.aiEmbedding`.
- *
- * This is deliberately smaller than {@link AIAgentRunnerService} (whose optional
- * `embed`/`embedMany` take a per-call model): a vector store should not have to
- * pull in the whole agent-runner tool loop just to embed, and pinning the model
- * to the service is what guarantees index/query consistency.
- *
- * Documents (ingested corpus) and queries (search text) are embedded through
- * separate methods because some models are asymmetric — Cohere's `input_type`,
- * E5's `query:`/`passage:` prefixes, BGE's query instruction — and must know
- * which side they are embedding to produce comparable vectors. Symmetric
- * providers (e.g. OpenAI) point both methods at the same call.
- */
+// knowledge: decisions/internals/the-embedding-model-is-pinned-per-service-and-doc-query-embedding-is-split.md
 export interface AIEmbeddingService {
-  /** The embedding model backing this service. Index and query share it. */
   readonly model: string
-  /** The vector dimensionality this model produces, when known. */
   readonly dimensions?: number
-  /** Embed corpus documents (index time), preserving input order. */
+  /** Index time. Preserves input order. */
   embedDocuments(values: string[]): Promise<number[][]>
-  /** Embed a search query (query time) into a vector. */
+  /** Query time. */
   embedQuery(value: string): Promise<number[]>
 }

package/src/services/audit-service.ts

@@ -76,8 +76,7 @@ class DisabledInvocationAudit implements AuditLog {
   async write(_event: AuditLogWriteInput): Promise<void> {
     if (!this.warned) {
       this.warned = true
-      // Fall back to the singleton logger — wires rarely carry their own, and
-      // a dropped audit write must never be invisible.
+      // knowledge: decisions/security/a-dropped-audit-write-is-always-logged.md
       const logger = (this.wire as any).logger ?? this.logger
       logger?.warn?.(
         `audit.write() dropped for '${this.wire.functionId ?? 'unknown function'}' — the function has no audit config (set audit: true on it)`

package/src/services/content-service.ts

@@ -1,6 +1,3 @@
-/**
- * Arguments for signing a content key into a time-limited URL.
- */
 export interface SignContentKeyArgs<TBucket extends string = string> {
   bucket: TBucket
   contentKey: string
@@ -8,18 +5,12 @@ export interface SignContentKeyArgs<TBucket extends string = string> {
   dateGreaterThan?: Date
 }
 
-/**
- * Arguments for signing an arbitrary URL.
- */
 export interface SignURLArgs {
   url: string
   dateLessThan: Date
   dateGreaterThan?: Date
 }
 
-/**
- * Arguments for minting a presigned upload URL.
- */
 export interface GetUploadURLArgs<TBucket extends string = string> {
   bucket: TBucket
   fileKey: string
@@ -28,9 +19,6 @@ export interface GetUploadURLArgs<TBucket extends string = string> {
   visibility?: 'private' | 'public'
 }
 
-/**
- * Result of minting a presigned upload URL.
- */
 export interface UploadURLResult {
   uploadUrl: string
   assetKey: string
@@ -38,26 +26,17 @@ export interface UploadURLResult {
   uploadMethod?: 'PUT' | 'POST'
 }
 
-/**
- * Arguments for an operation that targets a single object by key.
- */
 export interface BucketKeyArgs<TBucket extends string = string> {
   bucket: TBucket
   key: string
 }
 
-/**
- * Arguments for writing a stream to storage.
- */
 export interface WriteFileArgs<
   TBucket extends string = string,
 > extends BucketKeyArgs<TBucket> {
   stream: ReadableStream | NodeJS.ReadableStream
 }
 
-/**
- * Arguments for copying a local file into storage.
- */
 export interface CopyFileArgs<
   TBucket extends string = string,
 > extends BucketKeyArgs<TBucket> {
@@ -65,46 +44,22 @@ export interface CopyFileArgs<
 }
 
 export interface ContentService<TBucket extends string = string> {
-  /**
-   * Signs a content key to generate a secure, time-limited access URL.
-   */
   signContentKey(args: SignContentKeyArgs<TBucket>): Promise<string>
 
-  /**
-   * Signs an arbitrary URL to generate a secure, time-limited access URL.
-   */
   signURL(args: SignURLArgs): Promise<string>
 
-  /**
-   * Generates a signed URL for uploading a file directly to storage.
-   * Bucket policy (size limits, MIME allowlist) is enforced by the implementation.
-   */
+  /** Bucket policy (size limits, MIME allowlist) is enforced by the implementation, not the caller. */
   getUploadURL(args: GetUploadURLArgs<TBucket>): Promise<UploadURLResult>
 
-  /**
-   * Deletes a file from the storage backend.
-   */
   deleteFile(args: BucketKeyArgs<TBucket>): Promise<boolean>
 
-  /**
-   * Uploads a file stream to storage under the specified bucket + key.
-   */
   writeFile(args: WriteFileArgs<TBucket>): Promise<boolean>
 
-  /**
-   * Copies a file from a local absolute path into storage.
-   */
   copyFile(args: CopyFileArgs<TBucket>): Promise<boolean>
 
-  /**
-   * Reads a file from storage as a readable stream.
-   */
   readFile(
     args: BucketKeyArgs<TBucket>
   ): Promise<ReadableStream | NodeJS.ReadableStream>
 
-  /**
-   * Reads an entire file from storage into a Buffer.
-   */
   readFileAsBuffer(args: BucketKeyArgs<TBucket>): Promise<Buffer>
 }

package/src/services/credential-service.ts

@@ -1,57 +1,20 @@
 /**
- * Interface for managing dynamic/managed credentials.
- * Used for OAuth tokens, per-user API keys, and other credentials
- * that change at runtime (as opposed to SecretService which is for
- * static, developer-configured values).
+ * Dynamic credentials — OAuth tokens, per-user API keys — that change at
+ * runtime, as opposed to `SecretService`'s static developer-configured values.
+ * Throughout, an omitted `userId` means the platform-level credential.
  */
 export interface CredentialService {
-  /**
-   * Retrieves a credential by name and optional user ID.
-   * @param name - The credential name (e.g. 'stripe', 'google-sheets').
-   * @param userId - Optional user ID for per-user credentials. Omit for platform-level.
-   * @returns The credential value, or null if not found.
-   */
   get<T = unknown>(name: string, userId?: string): Promise<T | null>
 
-  /**
-   * Stores a credential.
-   * @param name - The credential name.
-   * @param value - The credential value to store.
-   * @param userId - Optional user ID for per-user credentials. Omit for platform-level.
-   */
   set(name: string, value: unknown, userId?: string): Promise<void>
 
-  /**
-   * Deletes a credential.
-   * @param name - The credential name.
-   * @param userId - Optional user ID for per-user credentials. Omit for platform-level.
-   */
   delete(name: string, userId?: string): Promise<void>
 
-  /**
-   * Checks if a credential exists.
-   * @param name - The credential name.
-   * @param userId - Optional user ID for per-user credentials. Omit for platform-level.
-   */
   has(name: string, userId?: string): Promise<boolean>
 
-  /**
-   * Retrieves all credentials for a user.
-   * @param userId - The user ID.
-   * @returns A record of credential name to value.
-   */
   getAll(userId: string): Promise<Record<string, unknown>>
 
-  /**
-   * Lists all user IDs that have a specific credential configured.
-   * @param name - The credential name.
-   * @returns Array of user IDs.
-   */
   getUsersWithCredential(name: string): Promise<string[]>
 
-  /**
-   * Lists all unique user IDs that have any credential configured.
-   * @returns Array of user IDs.
-   */
   getAllUsers(): Promise<string[]>
 }

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

@@ -29,9 +29,7 @@ describe('PikkuCredentialWireService', () => {
   test('should return sync after first load (no credential service)', async () => {
     const service = new PikkuCredentialWireService()
     service.set('foo', 'bar')
-    // First call triggers lazy load (no-op without credentialService)
     await service.getAll()
-    // Second call should be sync
     const result = service.getAll()
     assert.ok(!(result instanceof Promise), 'expected sync return')
     assert.deepStrictEqual(result, { foo: 'bar' })

package/src/services/deployment-service.ts

@@ -19,15 +19,9 @@ export interface DeploymentService {
   start(config: DeploymentConfig): Promise<void>
   stop(): Promise<void>
   /**
-   * Dispatch a remote RPC call to a function.
-   * The deployment service owns the full transport:
-   * - Resolving the target (endpoint, service binding, etc.)
-   * - Session propagation (JWT signing, headers)
-   * - The actual network call
-   *
-   * @param funcName - The function to invoke
-   * @param data - Input data for the function
-   * @param session - User session to propagate (optional)
+   * The implementation owns the whole transport: resolving the target
+   * (endpoint, service binding), propagating the session (JWT signing,
+   * headers) and making the call. Callers supply no transport detail.
    */
   invoke(
     funcName: string,

package/src/services/gateway-service.ts

@@ -1,20 +1,5 @@
-/**
- * Abstract GatewayService interface.
- *
- * Implementations manage listener gateway lifecycle — initializing adapters
- * and delivering messages to handler functions.
- *
- * A `LocalGatewayService` starts all listeners unconditionally;
- * a distributed implementation could check leader election first.
- */
 export interface GatewayService {
-  /**
-   * Start all listener gateways
-   */
   start(): Promise<void>
 
-  /**
-   * Stop all listener gateways
-   */
   stop(): Promise<void>
 }

package/src/services/{http-scenario-actors-converse.test.ts → http-personas-converse.test.ts}

@@ -2,7 +2,7 @@ import { describe, test, after } from 'node:test'
 import assert from 'node:assert/strict'
 import { createServer, type Server } from 'node:http'
 
-import { createHttpScenarioActors } from './http-scenario-actors.js'
+import { createHttpPersonas } from './http-personas.js'
 import { pikkuState, resetPikkuState } from '../pikku-state.js'
 import type { AIAgentStepResult } from './ai-agent-runner-service.js'
 
@@ -139,7 +139,7 @@ const wireRunner = () => {
   } as any)
 }
 
-describe('HttpScenarioActor.converse', async () => {
+describe('HttpPersona.converse', async () => {
   const target = await startAgentTarget()
   after(() => {
     target.server.close()
@@ -150,12 +150,21 @@ describe('HttpScenarioActor.converse', async () => {
     wireRunner()
     target.reset()
 
-    const actors = createHttpScenarioActors({
+    const actors = createHttpPersonas({
       apiUrl: target.apiUrl,
       secret: 'impersonation-secret',
       model: 'test/test-model',
-      actors: {
-        pm: { email: 'pm@actors.local', name: 'Priya', personality: 'concise' },
+      personas: {
+        pm: {
+          id: 'pm',
+          name: 'Priya',
+          email: 'pm@personas.invalid',
+          personality: 'concise',
+          roles: [],
+          goals: [],
+          tags: [],
+          runnable: true,
+        },
       },
     })
 
@@ -179,11 +188,21 @@ describe('HttpScenarioActor.converse', async () => {
     wireRunner()
     target.reset({ authRequired: true })
 
-    const actors = createHttpScenarioActors({
+    const actors = createHttpPersonas({
       apiUrl: target.apiUrl,
       secret: 'impersonation-secret',
       model: 'test/test-model',
-      actors: { pm: { email: 'pm@actors.local' } },
+      personas: {
+        pm: {
+          id: 'pm',
+          name: 'Priya',
+          email: 'pm@personas.invalid',
+          roles: [],
+          goals: [],
+          tags: [],
+          runnable: true,
+        },
+      },
     })
 
     const verdict = await actors.pm!.converse({
@@ -208,11 +227,21 @@ describe('HttpScenarioActor.converse', async () => {
       },
     } as any)
 
-    const actors = createHttpScenarioActors({
+    const actors = createHttpPersonas({
       apiUrl: target.apiUrl,
       secret: 'impersonation-secret',
       model: 'test/test-model',
-      actors: { pm: { email: 'pm@actors.local' } },
+      personas: {
+        pm: {
+          id: 'pm',
+          name: 'Priya',
+          email: 'pm@personas.invalid',
+          roles: [],
+          goals: [],
+          tags: [],
+          runnable: true,
+        },
+      },
     })
 
     await assert.rejects(

package/src/services/{http-scenario-actors.test.ts → http-personas.test.ts}

@@ -2,10 +2,10 @@ import { describe, test, after } from 'node:test'
 import assert from 'node:assert/strict'
 import { createServer, type Server } from 'node:http'
 
-import { createHttpScenarioActors } from './http-scenario-actors.js'
+import { createHttpPersonas } from './http-personas.js'
 
-// Minimal target app: actor sign-in endpoint + exposed RPC endpoint, session
-// via cookie. Mirrors the Better Auth actor plugin's contract.
+// Minimal target app mirroring the Better Auth actor plugin's contract:
+// sign-in endpoint, exposed RPC endpoint, session by cookie.
 const startTarget = async () => {
   let logins = 0
   let expireNext = false
@@ -78,29 +78,46 @@ const startTarget = async () => {
   }
 }
 
-describe('HttpScenarioActor', async () => {
+describe('HttpPersona', async () => {
   const target = await startTarget()
   after(() => target.server.close())
 
-  const makeActors = (secret = 'impersonation-secret') =>
-    createHttpScenarioActors({
+  const makePersonas = (secret = 'impersonation-secret') =>
+    createHttpPersonas({
       apiUrl: target.apiUrl,
       secret,
-      actors: {
-        customer: { email: 'customer@actors.local', jobTitle: 'Buyer' },
-        manager: { email: 'manager@actors.local' },
+      personas: {
+        customer: {
+          id: 'customer',
+          name: 'Customer',
+          email: 'customer@personas.invalid',
+          jobTitle: 'Buyer',
+          roles: [],
+          goals: [],
+          tags: [],
+          runnable: true,
+        },
+        manager: {
+          id: 'manager',
+          name: 'Manager',
+          email: 'manager@personas.invalid',
+          roles: [],
+          goals: [],
+          tags: [],
+          runnable: true,
+        },
       },
     })
 
-  test('builds one lazy actor per config entry', () => {
-    const actors = makeActors()
+  test('builds one lazy persona per declaration', () => {
+    const actors = makePersonas()
     assert.deepEqual(Object.keys(actors).sort(), ['customer', 'manager'])
     assert.equal(actors.customer!.name, 'customer')
     assert.equal(target.loginCount(), 0, 'no login until first invoke')
   })
 
   test('logs in lazily once and replays the session cookie on RPCs', async () => {
-    const actors = makeActors()
+    const actors = makePersonas()
 
     const first = (await actors.customer!.invoke('createTodo', {
       title: 'x',
@@ -120,7 +137,7 @@ describe('HttpScenarioActor', async () => {
   })
 
   test('re-logs-in once when the session expires mid-run', async () => {
-    const actors = makeActors()
+    const actors = makePersonas()
     await actors.manager!.invoke('ping', {})
     const loginsBefore = target.loginCount()
 
@@ -132,7 +149,7 @@ describe('HttpScenarioActor', async () => {
   })
 
   test('invokeRaw returns the status and body instead of throwing', async () => {
-    const actors = makeActors()
+    const actors = makePersonas()
 
     // A refusal is the expected outcome of a permissions scenario, so the
     // status and the payload that names the missing scope both have to survive.
@@ -147,7 +164,7 @@ describe('HttpScenarioActor', async () => {
   })
 
   test('invokeRaw reports a success the same way', async () => {
-    const actors = makeActors()
+    const actors = makePersonas()
     const res = await actors.manager!.invokeRaw('listTodos', { page: 2 })
 
     assert.equal(res.status, 200)
@@ -156,7 +173,7 @@ describe('HttpScenarioActor', async () => {
   })
 
   test('invokeRaw carries the response text so a step can search it', async () => {
-    const actors = makeActors()
+    const actors = makePersonas()
     const res = await actors.customer!.invokeRaw('forbidden', {})
 
     assert.match(res.serialized, /MissingScopeError/)
@@ -164,7 +181,7 @@ describe('HttpScenarioActor', async () => {
   })
 
   test('invokeRaw keeps a non-JSON error body instead of failing to parse it', async () => {
-    const actors = makeActors()
+    const actors = makePersonas()
     const res = await actors.manager!.invokeRaw('html-error', {})
 
     assert.equal(res.status, 500)
@@ -174,14 +191,14 @@ describe('HttpScenarioActor', async () => {
   })
 
   test('invokeRaw reports an empty body as an empty string', async () => {
-    const actors = makeActors()
+    const actors = makePersonas()
     const res = await actors.manager!.invokeRaw('listTodos', {})
 
     assert.equal(typeof res.serialized, 'string')
   })
 
   test('invokeRaw passes extra headers through', async () => {
-    const actors = makeActors()
+    const actors = makePersonas()
     const res = await actors.manager!.invokeRaw(
       'whoAmI',
       {},
@@ -192,7 +209,7 @@ describe('HttpScenarioActor', async () => {
   })
 
   test('invoke still throws on a refusal, naming the status and body', async () => {
-    const actors = makeActors()
+    const actors = makePersonas()
     await assert.rejects(
       actors.customer!.invoke('forbidden', {}),
       /'forbidden' as 'customer' returned 403.*MissingScopeError/
@@ -200,10 +217,10 @@ describe('HttpScenarioActor', async () => {
   })
 
   test('a wrong impersonation secret surfaces status and body', async () => {
-    const actors = makeActors('wrong-secret')
+    const actors = makePersonas('wrong-secret')
     await assert.rejects(
       actors.customer!.invoke('ping', {}),
-      /actor sign-in failed for 'customer' \(401\).*bad actor secret/
+      /persona sign-in failed for 'customer' \(401\).*bad actor secret/
     )
   })
 })