@pikku/core 0.12.92 → 0.12.93

package/dist/wirings/scheduler/scheduler.types.d.ts

@@ -7,10 +7,15 @@ export type ScheduledTasksMeta<UserSession extends CoreUserSession = any> = Reco
     session?: UserSession;
 }>;
 export type CoreScheduledTask<PikkuFunctionConfig = CorePikkuFunctionConfig<CorePikkuFunctionSessionless<void, void>>, PikkuMiddleware = CorePikkuMiddleware<any>> = {
+    /** Unique across the project. It is how the task is addressed in logs, in `pikku meta`, and by a scheduler service asked to run it now. */
     name: string;
+    /** A five-field cron expression: minute, hour, day of month, month, day of week. `0 9 * * 1` is 09:00 every Monday. Interpreted in the deployment's timezone, not the author's. */
     schedule: string;
+    /** The function to run. It receives no session and no input: a scheduled task has no caller, so it must be sessionless. */
     func: PikkuFunctionConfig;
+    /** Filters this task in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
     tags?: string[];
+    /** Wraps every execution. There is no request to read from, so this is for tracing, locking and teardown rather than auth. */
     middleware?: PikkuMiddleware[];
 };
 export interface PikkuScheduledTask {

package/dist/wirings/secret/secret.types.d.ts

@@ -4,21 +4,9 @@ export type CoreSecret<T = unknown> = {
     description?: string;
     secretId: string;
     schema: T;
-    /**
-     * A secret is REQUIRED by default because `getSecret` throws when the value is
-     * missing — a deploy without it is a runtime failure waiting to happen, so the
-     * deploy gate refuses it. Mark a secret `optional` when absence is a supported
-     * state the app handles (a feature that simply stays off): the generated map
-     * emits it as an optional property and `getSecret` resolves `undefined`
-     * instead of throwing.
-     */
+    /** Required by default: this says absence is a supported state, and `getSecret` resolves `undefined` rather than throwing. */
     optional?: boolean;
-    /**
-     * Where a user goes to obtain this value — a provider's API-key page, a setup
-     * guide, an internal runbook. Consoles and deploy UIs surface it beside a
-     * missing value. The same field on every credential/variable definition means
-     * the same thing.
-     */
+    /** Where a user goes to obtain this value, surfaced beside a missing one. */
     docsUrl?: string;
     /** Rotation cadence as a duration string, e.g. `'1d'`, `'30day'`, `'1w'`. */
     rotationPeriod?: string;
@@ -59,4 +47,11 @@ export type SecretDefinitionMeta = {
 };
 export type SecretDefinitionsMeta = Record<string, SecretDefinitionMeta>;
 export type SecretDefinitions = SecretDefinitionMeta[];
+/**
+ * Declares a secret this project needs, with the shape of its value. The CLI
+ * collects every declaration into `CredentialsMap`, which is what makes
+ * `secrets.getSecret('NAME')` return the right type instead of `unknown`.
+ *
+ * @example snippet: secrets
+ */
 export declare const defineSecret: <T>(_config: CoreSecret<T>) => void;

package/dist/wirings/secret/secret.types.js

@@ -1 +1,8 @@
+/**
+ * Declares a secret this project needs, with the shape of its value. The CLI
+ * collects every declaration into `CredentialsMap`, which is what makes
+ * `secrets.getSecret('NAME')` return the right type instead of `unknown`.
+ *
+ * @example snippet: secrets
+ */
 export const defineSecret = (_config) => { };

package/dist/wirings/trigger/trigger.types.d.ts

@@ -28,11 +28,14 @@ export type CorePikkuTriggerFunctionConfig<TInput = unknown, TOutput = unknown,
 };
 export declare const pikkuTriggerFunc: <TInput = unknown, TOutput = unknown, Services extends CoreSingletonServices = CoreSingletonServices, InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined>(triggerOrConfig: CorePikkuTriggerFunction<TInput, TOutput, Services> | CorePikkuTriggerFunctionConfig<TInput, TOutput, Services, InputSchema, OutputSchema>) => CorePikkuTriggerFunctionConfig<TInput, TOutput, Services, InputSchema, OutputSchema>;
 export interface CoreTrigger<PikkuFunctionConfig = any> {
+    /** What a `wireTriggerSource` points at to fire this trigger. It is the contract between the two, so both must spell it the same. */
     name: string;
+    /** The function to run each time the trigger fires. */
     func: PikkuFunctionConfig;
+    /** What firing this trigger means, for whoever is reading the wiring rather than writing it. */
     description?: string;
+    /** Filters this trigger in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
     tags?: string[];
-    graph?: true;
 }
 export interface TriggerInstance {
     name: string;

package/dist/wirings/variable/variable.types.d.ts

@@ -1,23 +1,17 @@
 export type CoreVariable<T = unknown> = {
+    /** How the variable is asked for in code. Generated into `VariablesMap`, so it is what `variables.get` autocompletes. */
     name: string;
+    /** The name shown to whoever configures the deployment. */
     displayName: string;
+    /** What the value does, for the person setting it rather than the one reading it. */
     description?: string;
+    /** The environment variable this reads, which is the name that has to exist on the host. */
     variableId: string;
+    /** The shape of the value. It arrives as a string, so this is also what parses it. */
     schema: T;
-    /**
-     * A variable is REQUIRED by default, and marking it `optional` is how a
-     * declaration says its absence is a supported state. Same flag, same
-     * polarity and same meaning as `CoreSecret.optional` — one word to learn
-     * rather than two with opposite senses.
-     *
-     * Defaulting to required rather than following `variables.get`'s
-     * `T | undefined` return is deliberate. That signature describes what a
-     * caller must HANDLE, not whether a deployment is correct without the value:
-     * an undefined feature flag is fine, an undefined API base URL is an outage
-     * that the type system cannot tell apart. Declaring the difference is the
-     * point of the flag, and the safe default for an undeclared one is to ask.
-     */
+    /** Required by default: this says the deployment is still correct without it. */
     optional?: boolean;
+    /** Where to go to work out what to set this to. */
     docsUrl?: string;
 };
 export type VariableDefinitionMeta = {
@@ -32,4 +26,11 @@ export type VariableDefinitionMeta = {
 };
 export type VariableDefinitionsMeta = Record<string, VariableDefinitionMeta>;
 export type VariableDefinitions = VariableDefinitionMeta[];
+/**
+ * Declares an environment variable this project needs, with the shape of its
+ * value. The CLI collects every declaration into `VariablesMap`, which is what
+ * makes `variables.get('NAME')` return the right type instead of `unknown`.
+ *
+ * @example snippet: variables
+ */
 export declare const defineVariable: <T>(_config: CoreVariable<T>) => void;

package/dist/wirings/variable/variable.types.js

@@ -1 +1,8 @@
+/**
+ * Declares an environment variable this project needs, with the shape of its
+ * value. The CLI collects every declaration into `VariablesMap`, which is what
+ * makes `variables.get('NAME')` return the right type instead of `unknown`.
+ *
+ * @example snippet: variables
+ */
 export const defineVariable = (_config) => { };

package/dist/wirings/workflow/graph/wire-workflow-graph.d.ts

@@ -1,10 +1,17 @@
 export interface PikkuWorkflowGraphConfig<FuncMap extends Record<string, string>, T> {
+    /** Keeps the graph in the codebase but out of the build. */
     disabled?: true;
+    /** Unique across the project. It is how the graph is started and how its runs are grouped. */
     name?: string;
+    /** What the graph does, for whoever is reading it rather than editing it. */
     description?: string;
+    /** Filters this graph in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
     tags?: string[];
+    /** The graph's steps, keyed by node id, each naming a function. `pikku meta` lists the names available here. */
     nodes: FuncMap;
+    /** Per-node settings — retries, timeouts, the edges between them. */
     config?: T;
+    /** Free text carried onto the rendered graph, for a reader who needs the reasoning the shape cannot show. */
     notes?: string[];
 }
 export interface PikkuWorkflowGraphResult {

package/dist/wirings/workflow/scenario-cookie-jar.d.ts

@@ -3,4 +3,10 @@ export interface ScenarioCookieJar {
     clear(): void;
     readonly empty: boolean;
 }
+/**
+ * A cookie store for a scenario run, so a step that signs in leaves the session
+ * cookie behind for the steps after it.
+ *
+ * @example snippet: scenarioCookieJar
+ */
 export declare const createCookieJar: (apiUrl: string) => ScenarioCookieJar;

package/dist/wirings/workflow/scenario-cookie-jar.js

@@ -1,3 +1,9 @@
+/**
+ * A cookie store for a scenario run, so a step that signs in leaves the session
+ * cookie behind for the steps after it.
+ *
+ * @example snippet: scenarioCookieJar
+ */
 export const createCookieJar = (apiUrl) => {
     const jar = new Map();
     const origin = new URL(apiUrl).origin;

package/dist/wirings/workflow/scenario-poll.d.ts

@@ -2,4 +2,10 @@ export interface PollOptions {
     timeoutMs?: number;
     intervalMs?: number;
 }
+/**
+ * Retries an assertion until it passes or the timeout runs out — for the
+ * eventually-consistent parts of a scenario (a queued job, a projection).
+ *
+ * @example snippet: scenarioPolling
+ */
 export declare const pollUntil: <T>(attempt: () => Promise<T | undefined> | T | undefined, { timeoutMs, intervalMs }?: PollOptions) => Promise<T | undefined>;

package/dist/wirings/workflow/scenario-poll.js

@@ -1,3 +1,9 @@
+/**
+ * Retries an assertion until it passes or the timeout runs out — for the
+ * eventually-consistent parts of a scenario (a queued job, a projection).
+ *
+ * @example snippet: scenarioPolling
+ */
 export const pollUntil = async (attempt, { timeoutMs = 15_000, intervalMs = 250 } = {}) => {
     const deadline = Date.now() + timeoutMs;
     for (;;) {

package/dist/wirings/workflow/scenario-step-guards.d.ts

@@ -1,2 +1,8 @@
 import type { PikkuScenarioStepWire, ScenarioEnvironment } from './scenario-step.types.js';
+/**
+ * The environment the current scenario run targets, or a throw explaining that
+ * the run carries none. Use it in a step that needs the target's URLs.
+ *
+ * @example snippet: scenarioHttpStep
+ */
 export declare const requireScenarioEnv: (scenarioStep: PikkuScenarioStepWire | undefined) => ScenarioEnvironment;

package/dist/wirings/workflow/scenario-step-guards.js

@@ -1,3 +1,9 @@
+/**
+ * The environment the current scenario run targets, or a throw explaining that
+ * the run carries none. Use it in a step that needs the target's URLs.
+ *
+ * @example snippet: scenarioHttpStep
+ */
 export const requireScenarioEnv = (scenarioStep) => {
     const env = scenarioStep?.env;
     if (!env) {

package/dist/wirings/workflow/workflow-errors.d.ts

@@ -9,6 +9,10 @@ export declare class WorkflowAsyncException extends Error {
     readonly stepName: string;
     constructor(runId: string, stepName: string);
 }
+/**
+ * Thrown inside a workflow step when the run has been cancelled, so the step
+ * stops rather than finishing work nobody wants.
+ */
 export declare class WorkflowCancelledException extends Error {
     readonly runId: string;
     readonly reason?: string | undefined;

package/dist/wirings/workflow/workflow-errors.js

@@ -13,6 +13,10 @@ export class WorkflowAsyncException extends Error {
         this.name = 'WorkflowAsyncException';
     }
 }
+/**
+ * Thrown inside a workflow step when the run has been cancelled, so the step
+ * stops rather than finishing work nobody wants.
+ */
 export class WorkflowCancelledException extends Error {
     runId;
     reason;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.92",
+  "version": "0.12.93",
   "description": "The Pikku runtime — functions, wirings, services, middleware and types",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",

package/src/app-leaf-surface.test.ts

@@ -124,12 +124,12 @@ const barrelSpecifiers = (file: string) => {
  * it otherwise never imports.
  */
 const namesOwnedByALeaf = new Map<string, string>([
-  ['defineCredential', '#pikku/credentials'],
+  ['defineCredential', '#pikku/auth'],
   ['defineSecret', '#pikku/secrets'],
   ['defineVariable', '#pikku/variables'],
   ['defineScope', '#pikku/scopes'],
   ['defineSystemRole', '#pikku/scopes'],
-  ['cors', '#pikku/http'],
+  ['cors', '#pikku/middleware'],
   ['InvalidOriginError', '#pikku/error'],
 ])
 

package/src/errors/error-handler.ts

@@ -13,19 +13,30 @@ export class PikkuError extends Error {
  * survives serialization across a workflow step boundary and rehydration as a
  * plain `Error`. Callers log the message alone for these, the full stack for
  * everything else.
+ *
+ * @example snippet: isExpectedError
  */
 export const isExpectedError = (error: unknown): boolean =>
   error instanceof PikkuError ||
   (error as { expected?: unknown } | null)?.expected === true
 
 export interface ErrorDetails {
+  /** The HTTP status this error answers with, instead of a 500. */
   status: number
+  /** What the caller is told. It leaves the process, so it must not name anything internal. */
   message: string
+  /** The JSON-RPC code an MCP client is given, where the HTTP status has no equivalent. */
   mcpCode?: number
 }
 
 export type PikkuErrorConstructor = new (...args: any[]) => Error
 
+/**
+ * Registers one of your own error classes with the HTTP status and message it
+ * should produce, so throwing it maps to a real response instead of a 500.
+ *
+ * @example snippet: addError
+ */
 export const addError = (
   error: any,
   { status, message, mcpCode }: ErrorDetails

package/src/errors/serialized-error.ts

@@ -1,6 +1,9 @@
 export interface SerializedError {
+  /** What went wrong, carried across a boundary that cannot carry an Error. */
   message: string
+  /** Present only where the failure was unexpected; a deliberate error is logged by its message alone. */
   stack?: string
+  /** The error class's registered name, which is what a caller matches on rather than the message. */
   code?: string
   // Set for a deliberate PikkuError; survives step-boundary rehydration so
   // the workflow runner logs the message alone rather than a stack trace.

package/src/function/function-runner.ts

@@ -29,7 +29,7 @@ import type { CorePikkuFunctionConfig } from './functions.types.js'
 import { parseVersionedId } from '../version.js'
 import type { SessionService } from '../services/user-session-service.js'
 import { PikkuSessionService } from '../services/user-session-service.js'
-import { ForbiddenError, ReadonlySessionError } from '../errors/errors.js'
+import { MissingSessionError, ReadonlySessionError } from '../errors/errors.js'
 import { verifyScopes } from '../scopes.js'
 import {
   PikkuCredentialWireService,
@@ -83,7 +83,7 @@ async function resolveSession(
 
 export const addFunction = (
   funcName: string,
-  funcConfig: CorePikkuFunctionConfig<any, any>,
+  funcConfig: CorePikkuFunctionConfig<any, any, any, any, any>,
   packageName: string | null = null
 ) => {
   pikkuState(packageName, 'function', 'functions').set(funcName, funcConfig)
@@ -329,7 +329,7 @@ export const runPikkuFunc = async <In = any, Out = any>(
         resolveAddonAuth(packageName, addonInstance?.namespace)
       ) {
         if (!session) {
-          throw new ForbiddenError('Authentication required')
+          throw new MissingSessionError('Authentication required')
         }
       }
     } else {
@@ -339,7 +339,7 @@ export const runPikkuFunc = async <In = any, Out = any>(
         )
       }
       if (!session) {
-        throw new ForbiddenError('Authentication required')
+        throw new MissingSessionError('Authentication required')
       }
     }
 

package/src/function/functions.types.ts

@@ -193,30 +193,38 @@ export type CorePikkuFunctionConfig<
   OutputSchema extends StandardSchemaV1 | undefined = undefined,
   Scope extends string = string,
 > = {
+  /** A human name for this function, shown wherever it is listed rather than called. */
   title?: string
+  /** What the function does. An agent choosing between tools reads this, so it is worth more care than a comment would be. */
   description?: string
   /** Explicit logical name override; lets multiple exports share a versioned base */
   override?: string
+  /** Which version of this contract this export is. Two exports sharing an `override` and differing here are the same function at two versions. */
   version?: number
+  /** Filters this function in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
   tags?: string[]
+  /** Makes the function callable from outside as `POST /rpc/<name>`. Without a session requirement, a permission or an addon gate, that means callable by anyone. */
   expose?: boolean
   /**
-   * The permission check for this function lives in its body — verifying a
-   * signed token, checking a webhook signature, matching an invite code — so
-   * it is not open despite declaring no session, scope or permission.
-   *
-   * A last resort. Prefer `permissions`, which are declared, inspectable, and
-   * reusable; reach for this only when the check cannot be expressed as one.
-   *
-   * Purely declarative — it grants nothing, and asserting it falsely disables
-   * the audit that would have caught the mistake. Requires
-   * `allow.permissionsInBody` in `pikku.config.json`.
+   * Declares that the body does its own permission check, so the function is
+   * not open despite naming no session, scope or permission. It grants
+   * nothing — asserting it falsely just disables the audit that would have
+   * caught the mistake. Requires `allow.permissionsInBody` in the config.
    */
   permissionsInBody?: boolean
+  /** Publishes the function in this package's remote surface, which is what a `wireRemoteAddon` consumer gets a typed client for. */
   remote?: boolean
+  /** Offers the function to MCP clients as a tool, without a separate `wireMCPTool`. */
   mcp?: boolean
+  /**
+   * Declares that the function only reads. It is enforced rather than
+   * decorative: a read-only session is refused any function without it, and an
+   * agent may call one without asking permission first.
+   */
   readonly?: boolean
+  /** Where this function is deployed when the build can go either way. `auto` lets the analyser decide from what the function touches. */
   deploy?: 'serverless' | 'server' | 'auto'
+  /** Under an agent's `explicit` approval policy, calling this pauses for a human to approve it. */
   approvalRequired?: boolean
   /** When true, workflow steps calling this function are dispatched via the queue. No queue service configured is a hard error. Defaults to false (inline). */
   workflowQueued?: boolean
@@ -230,18 +238,21 @@ export type CorePikkuFunctionConfig<
    * and report how much of the flow each surface actually covers.
    */
   surfaces?: ScenarioSurface[]
+  /** Scenario steps only, and set by the definer rather than by hand: this step needs a persona, so the runner injects `wire.actor`. */
+  requiresActor?: boolean
   /**
-   * Scenario steps only: this step is driven by a persona, so the runner injects
-   * `wire.actor` and refuses to dispatch it without one. Set by the definer from
-   * a `browser` binding or an explicit `actor: true`, never written by hand.
+   * Records every call in the audit log. `transactional` durability writes the
+   * entry in the same transaction as the work, so the two cannot disagree;
+   * `best-effort` does not hold the request up for it.
    */
-  requiresActor?: boolean
   audit?:
     | boolean
     | {
         durability?: 'best-effort' | 'transactional'
       }
+  /** Builds the sentence a human is shown when asked to approve a call, from that call's own input. */
   approvalDescription?: any
+  /** The body. Its first parameter is the services it needs, destructured inline so the build can tree-shake the rest away. */
   func: PikkuFunction
   /**
    * Scenarios only: runs before the scenario body, with the scenario's own
@@ -260,20 +271,21 @@ export type CorePikkuFunctionConfig<
    * as skipped rather than quietly omitted; naming it in `--flows` runs it.
    */
   skip?: string
+  /** Whether calling this requires a session, wherever it is wired. A wiring can be more permissive than the function, never less. */
   auth?: boolean
-  /**
-   * Scopes the session must hold; all are required (AND) and checked before
-   * `permissions`, which OR together — a scope can only narrow access.
-   * Narrowed to the generated `ScopeId` union, so an undeclared scope is a
-   * compile error. Requires a session — see
-   * {@link CorePikkuSessionlessFunctionConfig}.
-   */
+  /** Scopes the session must hold. All are required, and checked before `permissions`, which OR together — a scope only narrows access. */
   scopes?: Scope[]
+  /** Checks that run before the body. Grouped names OR together, so any one passing admits the caller; use `scopes` to require rather than offer. */
   permissions?: CorePermissionGroup<PikkuPermission>
+  /** Wraps this function wherever it is called from, unlike wiring middleware which only wraps one route into it. */
   middleware?: PikkuMiddleware[]
+  /** The input schema, which is also the input type — there is no separate generic to keep in step with it. */
   input?: InputSchema
+  /** The output schema, which is also the return type. Naming a type here instead is what produces PKU463. */
   output?: OutputSchema
+  /** Presentation for this function as a node in a workflow graph. */
   node?: CoreNodeConfig
+  /** Error classes this may throw, so each one's registered HTTP status is used instead of a 500. */
   errors?: Array<typeof PikkuError>
 }
 

package/src/middleware/auth-apikey.ts

@@ -2,7 +2,14 @@ import {
   pikkuMiddleware,
   pikkuMiddlewareFactory,
 } from './middleware-factories.js'
+/**
+ * Reads an API key from the request and JWT-decodes it into a session. Leaves
+ * an existing session alone, so it composes with other auth middleware.
+ *
+ * @example snippet: machineAuth
+ */
 export const authAPIKey = pikkuMiddlewareFactory<{
+  /** Where to look: the `x-api-key` header, the `apiKey` query param, or both. */
   source: 'header' | 'query' | 'all'
 }>(({ source }) =>
   pikkuMiddleware(

package/src/middleware/auth-bearer.ts

@@ -17,8 +17,11 @@ const constantTimeEqual = (a: string, b: string): boolean => {
  * Validates a bearer token: JWT-decoded by default, or compared in constant
  * time against a static `value` or a `secretId` resolved through the secrets
  * service per request.
+ *
+ * @example snippet: machineAuth
  */
 export const authBearer = pikkuMiddlewareFactory<{
+  /** Omit to JWT-decode the token. Set it to accept one fixed token instead, matched in constant time. */
   token?:
     | {
         value: string

package/src/middleware/auth-cookie.ts

@@ -6,10 +6,6 @@ import {
 import type { RelativeTimeInput } from '../time-utils.js'
 import { getRelativeTimeOffsetFromNow } from '../time-utils.js'
 
-/**
- * Reads a JWT session from a cookie, and re-issues the cookie after the
- * request whenever the session changed (e.g. after login).
- */
 /** Standard JWT registered claims — present on a token even with no session. */
 const JWT_REGISTERED_CLAIMS = new Set([
   'iat',
@@ -31,9 +27,18 @@ const hasSessionIdentity = (session: unknown): boolean => {
   return Object.keys(session).some((key) => !JWT_REGISTERED_CLAIMS.has(key))
 }
 
+/**
+ * Reads a JWT session from a cookie, and re-issues the cookie after the
+ * request whenever the session changed (e.g. after login).
+ *
+ * @example snippet: machineAuth
+ */
 export const authCookie = pikkuMiddlewareFactory<{
+  /** Cookie name to read and write. */
   name: string
+  /** Serialize options merged over the defaults, which are httpOnly and sameSite lax. */
   options: SerializeOptions
+  /** How long the re-issued cookie lives, as a relative time such as `'7d'`. */
   expiresIn: RelativeTimeInput
 }>(({ name, options, expiresIn }) => {
   const mergedOptions: SerializeOptions = {

package/src/middleware/cors.ts

@@ -8,13 +8,21 @@ import {
  * matching origin and otherwise sends no `Access-Control-Allow-Origin` at all,
  * so the browser reports "origin not allowed" rather than an origin mismatch
  * against whichever entry happened to be first.
+ *
+ * @example snippet: corsMiddleware
  */
 export const cors = pikkuMiddlewareFactory<{
+  /** Which origins may call. Defaults to `*`, which the browser rejects alongside `credentials: true` — name the origins instead. */
   origin?: string | string[] | true
+  /** Methods a cross-origin caller may use. Defaults to the common six; a method missing here fails preflight rather than the request. */
   methods?: string[]
+  /** Request headers a caller may send. Defaults to content-type, authorization and x-api-key. */
   headers?: string[]
+  /** Response headers the browser will let the caller's JavaScript read. Everything else is hidden from it even on a 200. */
   exposeHeaders?: string[]
+  /** Whether cookies and auth headers ride along. Requires a named origin, never `*`. */
   credentials?: boolean
+  /** Seconds the browser may cache this preflight. Defaults to a day. */
   maxAge?: number
 }>(
   ({

package/src/middleware/middleware-factories.ts

@@ -39,6 +39,10 @@ export const pikkuMiddlewareFactory = <In = any>(
   return factory
 }
 
+/**
+ * Declares middleware for a channel — it runs around the connection and its
+ * messages rather than around a single request.
+ */
 export const pikkuChannelMiddleware = <
   SingletonServices extends CoreSingletonServices = CoreSingletonServices,
   Event = unknown,
@@ -48,12 +52,22 @@ export const pikkuChannelMiddleware = <
   return middleware
 }
 
+/**
+ * Declares channel middleware that takes options, so one definition can be
+ * wired several times with different configuration.
+ *
+ * @example snippet: channelMiddlewareFactory
+ */
 export const pikkuChannelMiddlewareFactory = <In = any>(
   factory: CorePikkuChannelMiddlewareFactory<In>
 ): CorePikkuChannelMiddlewareFactory<In> => {
   return factory
 }
 
+/**
+ * Declares middleware for an agent run — hooks around the model call, its tool
+ * calls and the run's state.
+ */
 export const pikkuAgentMiddleware = <
   State extends Record<string, unknown> = Record<string, unknown>,
   SingletonServices extends CoreSingletonServices = CoreSingletonServices,

package/src/services/local-secrets.test.ts

@@ -22,7 +22,7 @@ describe('LocalSecretService', () => {
     const vars = new LocalVariablesService({})
     const service = new LocalSecretService(vars)
     await assert.rejects(() => service.getSecret('MISSING'), {
-      message: 'Requested secret not found',
+      message: 'Requested secret not found: MISSING',
     })
   })
 
@@ -44,7 +44,7 @@ describe('LocalSecretService', () => {
     const vars = new LocalVariablesService({})
     const service = new LocalSecretService(vars)
     await assert.rejects(() => service.getSecret('MISSING'), {
-      message: 'Requested secret not found',
+      message: 'Requested secret not found: MISSING',
     })
   })
 

package/src/services/local-secrets.ts

@@ -32,7 +32,7 @@ export class LocalSecretService implements SecretService {
     if (value) {
       return createSecretValue(this.parseSecret<T>(value))
     }
-    throw new Error('Requested secret not found')
+    throw new Error(`Requested secret not found: ${key}`)
   }
 
   public async setSecret(key: string, value: unknown): Promise<void> {

package/src/services/personas-service.ts

@@ -38,6 +38,8 @@ export interface ScenarioHttpResponse<T = unknown> {
  * `invokeRaw` returns this, and a step that has to reach past a persona — a
  * route with no RPC, an identity no persona can hold — reaches for this rather
  * than writing the same record by hand.
+ *
+ * @example snippet: scenarioPolling
  */
 export const readScenarioHttpResponse = async <T = unknown>(
   res: Response
@@ -84,6 +86,8 @@ export interface ScenarioJsonRequest {
  * outright when the target answers an empty body or an HTML error page. A
  * refusal is the expected outcome of a permissions scenario, so it has to
  * survive as data.
+ *
+ * @example snippet: scenarioHttpStep
  */
 export const postScenarioJson = async <T = unknown>(
   url: string,

package/src/services/secret-service.ts

@@ -4,7 +4,6 @@ import type { SecretValue } from '../classification/secret-value.js'
 export type SecretValues<T> = { [K in keyof T]: SecretValue<T[K]> }
 
 export interface SecretService {
-  /** Throws if the secret is not found. Unwrap the result with `.reveal()`. */
   getSecret<T = string>(key: string): Promise<SecretValue<T>>
   /** Answers for any key, including a disallowed one — it must not throw. */
   hasSecret(key: string): Promise<boolean>

package/src/testing/service-tests/secret-service-tests.ts

@@ -44,7 +44,7 @@ export const defineSecretServiceTests = (
     test('getSecret throws for missing key', async () => {
       const service = await factory({ key: kek })
       await assert.rejects(() => service.getSecret('nonexistent'), {
-        message: 'Requested secret not found',
+        message: 'Requested secret not found: nonexistent',
       })
     })