@pikku/core 0.12.72 → 0.12.74

package/dist/schema.js

@@ -1,31 +1,13 @@
 import { MissingSchemaError, UnprocessableContentError, } from './errors/errors.js';
 import { pikkuState, getAllPackageStates } from './pikku-state.js';
 const schemaKey = (name, packageName) => packageName ? `${packageName}:${name}` : name;
-/**
- * Adds a schema to the schemas map for a specific package.
- * @param name - The name of the schema.
- * @param value - The schema value.
- * @param packageName - The package name (null for main package, '@scope/package' for addon packages).
- * @ignore
- */
 export const addSchema = (name, value, packageName = null) => {
     const schema = value?.default ?? value;
     pikkuState(packageName, 'misc', 'schemas').set(name, schema);
 };
-/**
- * Retrieves a schema from the schemas map for a specific package.
- * @param name - The name of the schema.
- * @param packageName - The package name (null for main package, '@scope/package' for addon packages).
- * @returns The schema value or undefined if not found.
- * @ignore
- */
 export const getSchema = (name, packageName = null) => {
     return pikkuState(packageName, 'misc', 'schemas').get(name);
 };
-/**
- * Loads a schema and compiles it into a validator.
- * @param logger - A logger for logging information.
- */
 export const compileAllSchemas = (logger, schemaService) => {
     if (!schemaService) {
         schemaService = pikkuState(null, 'package', 'singletonServices')?.schema;
@@ -66,27 +48,11 @@ const validateAllSchemasLoaded = (logger, schemaService) => {
     }
 };
 /**
- * Fill in absent top-level properties from their schema `default`.
- *
- * A `default` reaches the generated JSON Schema and keeps the property out of
- * `required`, so omitting it validates — but nothing was ever filling it in.
- * JSON Schema validators are pure by specification and none of the ones Pikku
- * ships with (`@cfworker/json-schema`, and Ajv unless `useDefaults` is set)
- * annotate the instance, so the function received `undefined` for a property
- * its generated type declares as present. That is the worst shape a mismatch
- * can take: validation permits the omission, the type says the value is there,
- * and the body reads `undefined`.
- *
- * Applied unconditionally rather than alongside `coerceTopLevelDataFromSchema`,
- * whose `coerceDataFromSchema` flag is about decoding transport-encoded values
- * (a query string's `"1,2"` into an array). Defaults are a property of the
- * schema, not of how the call arrived, so gating them on that flag would apply
- * them over HTTP and skip them on a direct RPC invocation.
- *
- * Returns the data to use, which is a new object only when defaults had to be
- * added to a nullish input — a call made with no arguments at all still gets
- * them. Values are cloned so an object or array default (`[]`, `{}`) is never
- * shared as one mutable instance across every request.
+ * Fills in absent top-level properties from their schema `default`. Applied
+ * unconditionally: a default belongs to the schema, not to the transport the
+ * call arrived on, and runs before coercion so a defaulted and a supplied
+ * value are treated identically from here on. Values are cloned so an object
+ * or array default is never shared as one mutable instance across requests.
  */
 export const applyDefaultsFromSchema = (schemaName, data, packageName = null) => {
     const schema = pikkuState(packageName, 'misc', 'schemas').get(schemaName);

package/dist/scopes.d.ts

@@ -1,31 +1,12 @@
 import type { CoreUserSession } from './types/core.types.js';
 /**
- * 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 declare const hasScopes: (required: readonly string[] | undefined, held: Iterable<string> | undefined) => boolean;
 /**
- * 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 declare const verifyScopes: (required: readonly string[] | undefined, session: CoreUserSession | undefined) => void;

package/dist/scopes.js

@@ -2,13 +2,9 @@ import { MissingScopeError } from './errors/errors.js';
 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) => {
     const segments = scope.split(SEPARATOR);
@@ -21,26 +17,8 @@ const satisfyingGrants = (scope) => {
     }
     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, scope) => 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, held) => {
     if (!required || required.length === 0) {
         return null;
@@ -54,33 +32,14 @@ const firstUnsatisfied = (required, held) => {
     return null;
 };
 /**
- * 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, held) => 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, session) => {
     const missing = firstUnsatisfied(required, session?.scopes);

package/dist/services/ai-agent-runner-service.d.ts

@@ -12,6 +12,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 = {
     text: string;

package/dist/services/ai-embedding-service.d.ts

@@ -1,31 +1,8 @@
-/**
- * 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.
- */
 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/dist/services/audit-service.js

@@ -14,8 +14,7 @@ class DisabledInvocationAudit {
     async write(_event) {
         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.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/dist/services/content-service.d.ts

@@ -1,23 +1,14 @@
-/**
- * Arguments for signing a content key into a time-limited URL.
- */
 export interface SignContentKeyArgs<TBucket extends string = string> {
     bucket: TBucket;
     contentKey: string;
     dateLessThan: Date;
     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;
@@ -25,66 +16,30 @@ export interface GetUploadURLArgs<TBucket extends string = string> {
     size?: number;
     visibility?: 'private' | 'public';
 }
-/**
- * Result of minting a presigned upload URL.
- */
 export interface UploadURLResult {
     uploadUrl: string;
     assetKey: string;
     uploadHeaders?: Record<string, string>;
     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> {
     fromAbsolutePath: string;
 }
 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/dist/services/credential-service.d.ts

@@ -1,51 +1,14 @@
 /**
- * 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/dist/services/deployment-service.d.ts

@@ -16,15 +16,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, data: unknown, session?: unknown, traceId?: string): Promise<unknown>;
 }

package/dist/services/gateway-service.d.ts

@@ -1,19 +1,4 @@
-/**
- * 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/dist/services/http-personas.d.ts

@@ -0,0 +1,80 @@
+import type { ScenarioPersona, ResolvedPersona, ScenarioPersonas, ScenarioInvokeOptions, ScenarioHttpResponse } from './personas-service.js';
+import type { ConverseOptions, ActorFlowVerdict } from '../wirings/actor-flow/actor-flow.types.js';
+export interface HttpPersonasConfig {
+    /**
+     * Base API URL of the target app, INCLUDING the HTTP prefix — e.g.
+     * `https://app.example.com/api` or `http://localhost:4000/api`. Sign-in is
+     * reached at `${apiUrl}${signInPath}` and exposed RPCs at
+     * `${apiUrl}${rpcPath}/:rpcName`.
+     */
+    apiUrl: string;
+    /**
+     * The impersonation secret. Sign-in only ever works for user rows flagged
+     * `actor: true` — knowing the secret never impersonates real users.
+     */
+    secret: string;
+    /** Persona id → the declaration with its address filled in. */
+    personas: Record<string, ResolvedPersona>;
+    /** Sign-in path under apiUrl. Default: the actor plugin's `/auth/sign-in/actor`. */
+    signInPath?: string;
+    /** Where the session (and its roles) is read back. Default `/auth/get-session`. */
+    sessionPath?: string;
+    /** Exposed-RPC path prefix under apiUrl. Default `/rpc`. */
+    rpcPath?: string;
+    /**
+     * 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`.
+     */
+    model?: string;
+}
+/**
+ * Default HTTP-backed persona. Signs in lazily on first invoke via the Better
+ * Auth actor plugin (`POST /auth/sign-in/actor` with `{ email, secret }` —
+ * the plugin upserts the actor-flagged user row and mints a session whose
+ * `actor` flag flows into audits/analytics). Holds the session cookies for
+ * its lifetime; a 401 mid-run re-logs-in once (long health-check runs can
+ * outlive a session).
+ */
+export declare class HttpPersona implements ScenarioPersona {
+    readonly name: string;
+    private persona;
+    private config;
+    private jar;
+    /**
+     * Whether `login()` has succeeded since the last time the session was
+     * dropped. The jar cannot answer this — a target may set a cookie before
+     * anyone signs in, and it would then look like a session that was never
+     * established.
+     */
+    private signedIn;
+    constructor(name: string, persona: ResolvedPersona, config: HttpPersonasConfig);
+    get email(): string;
+    invoke(rpcName: string, data: unknown): Promise<unknown>;
+    invokeRaw(rpcName: string, data: unknown, options?: ScenarioInvokeOptions): Promise<ScenarioHttpResponse>;
+    converse(options: ConverseOptions): Promise<ActorFlowVerdict>;
+    /**
+     * The roles the stage says this session holds.
+     *
+     * Read from better-auth's `get-session`, which is what most pikku apps are
+     * running and where its admin plugin puts `role` — on the user, as a
+     * comma-separated list. A target that answers something else returns `null`
+     * rather than an empty list, because "this stage does not report roles" and
+     * "this person has none" call for opposite responses from the caller.
+     */
+    sessionRoles(): Promise<string[] | null>;
+    /** Start/continue the target agent's run over HTTP as this persona. */
+    private agentRun;
+    /** Answer the target agent's pending approvals over HTTP and continue. */
+    private agentApprove;
+    private postAgent;
+    private postRpc;
+    /** Drop the session, so the next call signs in again before it goes out. */
+    private signOut;
+    private login;
+}
+/**
+ * Build the injected `personas` service from the declared personas: id → lazy
+ * HTTP persona. Wire the result as the `personas` singleton service.
+ */
+export declare function createHttpPersonas(config: HttpPersonasConfig): ScenarioPersonas;