@pikku/core 0.12.92 → 0.12.94

package/CHANGELOG.md

@@ -1,3 +1,91 @@
+## 0.12.94
+
+### Patch Changes
+
+- 0b1bf53: Provision the app a persona signs into as a grant, not just a declaration.
+
+  `CorePersona.app` decided where a browser run navigated and nothing else, so
+  "which frontend may this person reach" was a fact only the test runner held and
+  the deployment could not enforce. It is now a scope: the CLI derives an `app`
+  tree from the apps the personas name, and `provisionPersonas` grants
+  `app:<name>` alongside the roles.
+
+  Carried as a scope rather than a per-app column so it resolves at the session
+  boundary like every other grant — revocable at runtime from the console, not
+  inherited by a restricted API key, and one query for which apps a user may
+  reach instead of a migration per frontend. A single-frontend product declares
+  nothing and is unaffected.
+
+  `app` is reserved as a scope root: a `defineScope` call that also declares it
+  now fails the build rather than shadowing the derived tree.
+
+## 0.12.93
+
+### Patch Changes
+
+- 4058c3a: `addFunction` accepts a config carrying its schemas. It typed the parameter with
+  two type arguments where the schema-carrying overloads of
+  `CorePikkuFunctionConfig` need five, so every generated scenario registration
+  failed to typecheck — invisible until a real project was compiled in CI.
+- 4058c3a: authBearer, authCookie and authAPIKey now come from `#pikku/middleware`, so nothing needs `@pikku/core`
+- 4058c3a: `pikku doc` takes several topics at once, so an agent that needs two exports
+  spends one round-trip rather than two.
+
+  A variadic positional validated at runtime but not in the types: `[files...]`
+  resolved to a key literally named `files...`, so declaring one was a type error.
+
+- 4058c3a: `pikku doc` keeps a door screen to a door: exports, what each is for, and either
+  its signature or a pointer to its keys — never the keys themselves. `#pikku/function`
+  was 9.4k tokens and is now under 1k.
+
+  Error classes carry their registered HTTP status again. The scrape read only the
+  program, and a surveyed project consumes pikku as `.d.ts`, which has no statements —
+  so all 49 came back bare.
+
+- 4058c3a: Give every export `pikku doc` lists a line saying what it is for, and gate it at zero
+- 4058c3a: Point the doc's examples at real template source instead of restating it. An `@example snippet: name` names a `// @snippet start name` region in `templates/functions` or `templates/function-addon`, and the surface build resolves it — so every example the doc shows is code that compiled, and renaming an option breaks the build rather than the docs. `wireHTTP`, `wireChannel`, `wireScheduler`, `wireQueueWorker`, `defineSecret`, `defineVariable` and `addError` now carry one.
+- 114c079: Answer 401, not 403, when a function requires a session and no session exists.
+
+  `MissingSessionError` has been in the error table at 401 since forever and was never thrown — the runner threw `ForbiddenError('Authentication required')` instead, so "you are not signed in" and "you are signed in but not allowed" both came back 403. The two mean opposite things to a client: the first is worth retrying after re-authenticating, the second never is.
+
+  That made pikku's own recovery unreachable. `HttpPersona` re-logs-in once on a 401 mid-run, for exactly the case its comment describes — a long run outliving its session. Against a stage using `betterAuthStatelessSession`, the signed cookie cache expires on the app's `cookieCache.maxAge` (5 minutes is the common setting), and from that moment every RPC in the run failed with 403 "Authentication required" while the retry watched for a 401 that could never arrive. A 32-minute scenario run failed everything after its first five minutes.
+
+  Permission and scope denials are untouched and stay 403.
+
+- 4450b2a: Name the missing key when a secret is not found.
+
+  Every `SecretService` threw a bare `Requested secret not found`. In a deployed
+  runtime the stack is minified, so the message was the only evidence there was —
+  and it identified neither the key nor the service. Each implementation now names
+  the key it looked for; the better-auth middlewares that skip on an absent secret
+  match the prefix through one shared predicate instead of the whole string.
+
+- 4058c3a: Every `@example` in the public surface now names a snippet from `examples/online-shop`,
+  and `@pikku/cli` ships the regions themselves as `snippets.json` beside `surface.json`.
+
+  One running application is the only source: the code a reader is shown is code that
+  compiles, migrates and passes `pikku` in CI, and it cannot drift from the API it
+  illustrates. 80 of the 85 app-entrypoint callables now carry an example, up from 34.
+
+- 4058c3a: Say what each wiring key is for, and gate it so it stays said
+
+  The public surface doc listed keys as a name and a type. `schedule: string`
+  is a shape; what a caller needs is that it wants a cron expression. Written
+  as JSDoc where the type is declared, it reaches `pikku doc`, the IDE and the
+  console at once — 31% of keys carried one, now 64%.
+
+  `CoreHTTPFunctionWiring` was six near-identical union branches, so its keys
+  could not be documented once. It is now a shared object intersected with the
+  two unions that are genuinely correlated: `auth` with the kind of function it
+  admits, and the method with `sse` and `query`.
+
+  A test reads the shipped surface and holds three numbers: keys that say what
+  they are for can only go up, and references to a `Core*` internal or to a type
+  the doc never describes can only go down.
+
+  Drops `eventChannel` from HTTP wirings and `graph` from triggers; nothing read
+  either.
+
 ## 0.12.92
 
 ### Patch Changes

package/dist/errors/error-handler.d.ts

@@ -6,14 +6,25 @@ export declare 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 declare const isExpectedError: (error: unknown) => boolean;
 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 declare const addError: (error: any, { status, message, mcpCode }: ErrorDetails) => void;
 export declare const addErrors: (errors: Array<[error: any, details: ErrorDetails]>) => void;
 export declare const getErrorResponse: (error: Error) => {

package/dist/errors/error-handler.js

@@ -11,9 +11,17 @@ 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) => error instanceof PikkuError ||
     error?.expected === true;
+/**
+ * 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, { status, message, mcpCode }) => {
     pikkuState(null, 'misc', 'errors').set(error, mcpCode === undefined ? { status, message } : { status, message, mcpCode });
 };

package/dist/errors/serialized-error.d.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;
     expected?: boolean;
     [key: string]: any;

package/dist/function/function-runner.d.ts

@@ -5,7 +5,7 @@ import type { CorePikkuFunctionConfig } from './functions.types.js';
 import type { SessionService } from '../services/user-session-service.js';
 import { PikkuCredentialWireService } from '../services/credential-wire-service.js';
 import type { AddonInstance } from '../wirings/addon/addon-runner.js';
-export declare const addFunction: (funcName: string, funcConfig: CorePikkuFunctionConfig<any, any>, packageName?: string | null) => void;
+export declare const addFunction: (funcName: string, funcConfig: CorePikkuFunctionConfig<any, any, any, any, any>, packageName?: string | null) => void;
 export declare const getFunctionNames: (packageName?: string | null) => string[];
 export declare const getAllFunctionNames: () => string[];
 export declare const runPikkuFunc: <In = any, Out = any>(wireType: PikkuWiringTypes, wireId: string, funcName: string, { singletonServices, createWireServices, data, auth: wiringAuth, inheritedMiddleware, wireMiddleware, inheritedChannelMiddleware, wireChannelMiddleware, coerceDataFromSchema, wire, sessionService, credentialWireService, packageName, addonInstance, }: {

package/dist/function/function-runner.js

@@ -7,7 +7,7 @@ import { pikkuState } from '../pikku-state.js';
 import { applyDefaultsFromSchema, coerceTopLevelDataFromSchema, validateSchema, } from '../schema.js';
 import { parseVersionedId } from '../version.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, createWireServicesCredentialWireProps, } from '../services/credential-wire-service.js';
 import { defaultPikkuUserIdResolver } from '../services/pikku-user-id.js';
@@ -182,7 +182,7 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
                 funcConfig.auth === true ||
                 resolveAddonAuth(packageName, addonInstance?.namespace)) {
                 if (!session) {
-                    throw new ForbiddenError('Authentication required');
+                    throw new MissingSessionError('Authentication required');
                 }
             }
         }
@@ -191,7 +191,7 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
                 resolvedSingletonServices.logger.warn(`Function '${funcName}' requires a session but auth was explicitly disabled — use pikkuSessionlessFunc instead.`);
             }
             if (!session) {
-                throw new ForbiddenError('Authentication required');
+                throw new MissingSessionError('Authentication required');
             }
         }
         if (session?.readonly && !funcMeta.readonly) {

package/dist/function/functions.types.d.ts

@@ -48,30 +48,38 @@ export type CorePermissionGroup<PikkuPermission = CorePikkuPermission<any>> = Re
  */
 export type CorePikkuFunctionHook<Services = any, Data = any, Wire = any> = (services: Services, data: Data, wire: Wire) => Promise<void> | void;
 export type CorePikkuFunctionConfig<PikkuFunction extends CorePikkuFunction<any, any, any, any, any> | CorePikkuFunctionSessionless<any, any, any, any, any>, PikkuPermission extends CorePikkuPermission<any, any, any> = CorePikkuPermission<any>, PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<any, any>, InputSchema extends StandardSchemaV1 | undefined = undefined, 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;
@@ -85,16 +93,19 @@ export type CorePikkuFunctionConfig<PikkuFunction extends CorePikkuFunction<any,
      * 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
@@ -113,20 +124,21 @@ export type CorePikkuFunctionConfig<PikkuFunction extends CorePikkuFunction<any,
      * 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/dist/middleware/auth-apikey.d.ts

@@ -1,3 +1,10 @@
+/**
+ * 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 declare const authAPIKey: import("./middleware.types.js").CorePikkuMiddlewareFactory<{
+    /** Where to look: the `x-api-key` header, the `apiKey` query param, or both. */
     source: "header" | "query" | "all";
 }>;

package/dist/middleware/auth-apikey.js

@@ -1,4 +1,10 @@
 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(({ source }) => pikkuMiddleware(async ({ jwt: jwtService }, { http, setSession, session }, next) => {
     if (!http?.request || !setSession || session) {
         return next();

package/dist/middleware/auth-bearer.d.ts

@@ -3,8 +3,11 @@ import type { CoreUserSession } from '../types/core.types.js';
  * 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 declare const authBearer: import("./middleware.types.js").CorePikkuMiddlewareFactory<{
+    /** Omit to JWT-decode the token. Set it to accept one fixed token instead, matched in constant time. */
     token?: {
         value: string;
         userSession: CoreUserSession;

package/dist/middleware/auth-bearer.js

@@ -13,6 +13,8 @@ const constantTimeEqual = (a, b) => {
  * 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(({ token } = {}) => pikkuMiddleware(async ({ jwt: jwtService, secrets }, { http, setSession, session }, next) => {
     if (!http?.request || !setSession || session) {

package/dist/middleware/auth-cookie.d.ts

@@ -1,7 +1,16 @@
 import type { SerializeOptions } from 'cookie';
 import type { RelativeTimeInput } 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).
+ *
+ * @example snippet: machineAuth
+ */
 export declare const authCookie: import("./middleware.types.js").CorePikkuMiddlewareFactory<{
+    /** 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;
 }>;

package/dist/middleware/auth-cookie.js

@@ -1,9 +1,5 @@
 import { pikkuMiddleware, pikkuMiddlewareFactory, } from './middleware-factories.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',
@@ -24,6 +20,12 @@ const hasSessionIdentity = (session) => {
         return false;
     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(({ name, options, expiresIn }) => {
     const mergedOptions = {
         httpOnly: true,

package/dist/middleware/cors.d.ts

@@ -4,12 +4,20 @@
  * 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 declare const cors: import("./middleware.types.js").CorePikkuMiddlewareFactory<{
+    /** 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/dist/middleware/cors.js

@@ -5,6 +5,8 @@ import { pikkuMiddleware, pikkuMiddlewareFactory, } from './middleware-factories
  * 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(({ origin = '*', methods = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'], headers = ['Content-Type', 'Authorization', 'x-api-key'], exposeHeaders = [], credentials = false, maxAge = 86400, } = {}) => {
     if (origin === '*' && credentials) {

package/dist/middleware/middleware-factories.d.ts

@@ -4,6 +4,20 @@ import type { PikkuAgentMiddlewareHooks } from '../wirings/agent/agent.types.js'
 import type { CorePikkuMiddleware, CorePikkuMiddlewareConfig, CorePikkuMiddlewareFactory } from './middleware.types.js';
 export declare const pikkuMiddleware: <SingletonServices extends CoreSingletonServices = CoreSingletonServices, UserSession extends CoreUserSession = CoreUserSession>(middleware: CorePikkuMiddleware<SingletonServices, UserSession> | CorePikkuMiddlewareConfig<SingletonServices, UserSession>) => CorePikkuMiddleware<SingletonServices, UserSession>;
 export declare const pikkuMiddlewareFactory: <In = any>(factory: CorePikkuMiddlewareFactory<In>) => CorePikkuMiddlewareFactory<In>;
+/**
+ * Declares middleware for a channel — it runs around the connection and its
+ * messages rather than around a single request.
+ */
 export declare const pikkuChannelMiddleware: <SingletonServices extends CoreSingletonServices = CoreSingletonServices, Event = unknown>(middleware: CorePikkuChannelMiddleware<SingletonServices, Event>) => CorePikkuChannelMiddleware<SingletonServices, Event>;
+/**
+ * Declares channel middleware that takes options, so one definition can be
+ * wired several times with different configuration.
+ *
+ * @example snippet: channelMiddlewareFactory
+ */
 export declare const pikkuChannelMiddlewareFactory: <In = any>(factory: CorePikkuChannelMiddlewareFactory<In>) => CorePikkuChannelMiddlewareFactory<In>;
+/**
+ * Declares middleware for an agent run — hooks around the model call, its tool
+ * calls and the run's state.
+ */
 export declare const pikkuAgentMiddleware: <State extends Record<string, unknown> = Record<string, unknown>, SingletonServices extends CoreSingletonServices = CoreSingletonServices>(hooks: PikkuAgentMiddlewareHooks<State, SingletonServices>) => PikkuAgentMiddlewareHooks<State, SingletonServices>;

package/dist/middleware/middleware-factories.js

@@ -10,10 +10,24 @@ export const pikkuMiddleware = (middleware) => {
 export const pikkuMiddlewareFactory = (factory) => {
     return factory;
 };
+/**
+ * Declares middleware for a channel — it runs around the connection and its
+ * messages rather than around a single request.
+ */
 export const pikkuChannelMiddleware = (middleware) => {
     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 = (factory) => {
     return factory;
 };
+/**
+ * Declares middleware for an agent run — hooks around the model call, its tool
+ * calls and the run's state.
+ */
 export const pikkuAgentMiddleware = (hooks) => hooks;

package/dist/services/local-secrets.js

@@ -23,7 +23,7 @@ export class LocalSecretService {
         if (value) {
             return createSecretValue(this.parseSecret(value));
         }
-        throw new Error('Requested secret not found');
+        throw new Error(`Requested secret not found: ${key}`);
     }
     async setSecret(key, value) {
         // Storing the wrapper would serialize it to '[secret]', so unwrap first —

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

@@ -33,6 +33,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 declare const readScenarioHttpResponse: <T = unknown>(res: Response) => Promise<ScenarioHttpResponse<T>>;
 /** How to send one JSON request, for `postScenarioJson`. */
@@ -59,6 +61,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 declare const postScenarioJson: <T = unknown>(url: string, { body, headers, method, fetch: send, }?: ScenarioJsonRequest) => Promise<ScenarioHttpResponse<T>>;
 /** Per-call transport options. */

package/dist/services/personas-service.js

@@ -5,6 +5,8 @@
  * `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 (res) => {
     const text = res.status === 204 ? '' : await res.text().catch(() => '');
@@ -32,6 +34,8 @@ const parseJsonBody = (text) => {
  * 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 (url, { body, headers, method = 'POST', fetch: send = fetch, } = {}) => readScenarioHttpResponse(await send(url, {
     method,

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

@@ -4,7 +4,6 @@ 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/dist/testing/service-tests/secret-service-tests.js

@@ -31,7 +31,7 @@ export const defineSecretServiceTests = (name, secretService) => {
         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',
             });
         });
         test('setSecret upserts existing key', async () => {

package/dist/types/core.types.d.ts

@@ -271,10 +271,15 @@ export type ServerLifecycle<SingletonServices extends CoreSingletonServices = Co
 export type CommonWireMeta = {
     pikkuFuncId: string;
     packageName?: string;
+    /** A human name for this wiring, shown wherever it is listed rather than called. */
     title?: string;
+    /** Filters this wiring in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
     tags?: string[];
+    /** A one-line description for listings, where the full `description` is too long. */
     summary?: string;
+    /** What this does, for whoever is reading the wiring rather than writing it. */
     description?: string;
+    /** Names of error classes this may throw, so each one's registered status is used instead of a 500. */
     errors?: string[];
     middleware?: MiddlewareMetadata[];
     permissions?: PermissionMetadata[];

package/dist/wirings/addon/wire-addon.d.ts

@@ -1,34 +1,30 @@
 import type { CorePikkuMiddleware } from '../../middleware/middleware.types.js';
 export type WireAddonConfig = {
+    /** How this instance is addressed. One package may be wired more than once, and the name is what tells the instances apart. */
     name: string;
+    /** The npm package the addon ships in. */
     package: string;
+    /** Where to reach the addon when it runs as its own service rather than in-process. */
     rpcEndpoint?: string;
+    /** Requires a session for every function in the addon, whatever each one declares. Gates an addon whose functions are individually open. */
     auth?: boolean;
+    /** Offers the addon's functions to MCP clients as tools, without wiring each one. */
     mcp?: boolean;
+    /** Filters this addon in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
     tags?: string[];
     /** Required of every function in the addon, on top of the function's own. */
     scopes?: string[];
+    /** Points a secret the addon reads at a different key in this deployment, so two instances can hold different credentials. */
     secretOverrides?: Record<string, string>;
+    /** Points a variable the addon reads at a different key in this deployment. */
     variableOverrides?: Record<string, string>;
+    /** Points a credential the addon reads at a different key in this deployment. */
     credentialOverrides?: Record<string, string>;
-    /**
-     * Secrets this instance may read on top of the ones it declared, named as the
-     * addon reads them — the scope check runs before `secretOverrides` renames
-     * them, so an overridden secret is named here by its addon-side key. Listing
-     * one in `secretOverrides` grants it too.
-     *
-     * For an addon whose secret names come off its input rather than its own
-     * source, this is how the host lends names the addon could not declare.
-     */
+    /** Extra secrets this instance may read, named as the addon reads them — the scope check runs before `secretOverrides` renames them. */
     secretGrants?: string[];
     /** Credentials this instance may read on top of the ones it declared. */
     credentialGrants?: string[];
-    /**
-     * Hands this instance the whole `SecretService` instead of one scoped to the
-     * secrets it declared. The value is the reason, recorded in the deploy
-     * manifest — an addon that names secrets at runtime cannot be scoped, and
-     * only the consuming app, never the addon, can grant it.
-     */
+    /** Hands over the whole `SecretService` unscoped. The value is the reason, recorded in the deploy manifest. */
     globalSecrets?: string;
     /**
      * Hands this instance the whole `CredentialService` instead of one narrowed
@@ -37,6 +33,12 @@ export type WireAddonConfig = {
      */
     globalCredentials?: string;
 };
+/**
+ * Installs an addon into this project: its functions, wirings and scopes become
+ * part of the app, under the namespace and options given here.
+ *
+ * @example snippet: addonWiring
+ */
 export declare const wireAddon: (config: WireAddonConfig) => void;
 /**
  * knowledge: decisions/security/addon-scopes-are-resolved-where-the-function-runs.md

package/dist/wirings/addon/wire-addon.js

@@ -1,5 +1,11 @@
 import { pikkuState } from '../../pikku-state.js';
 import { getTagGroups } from '../../utils.js';
+/**
+ * Installs an addon into this project: its functions, wirings and scopes become
+ * part of the app, under the namespace and options given here.
+ *
+ * @example snippet: addonWiring
+ */
 export const wireAddon = (config) => {
     pikkuState(null, 'addons', 'packages').set(config.name, {
         package: config.package,

package/dist/wirings/addon/wire-remote-addon.d.ts

@@ -19,4 +19,8 @@ export type WireRemoteAddonConfig = {
     remoteName?: (fn: string) => string;
     tags?: string[];
 };
+/**
+ * Installs an addon that runs as its own deployed service: the contract is
+ * local, the calls go over the wire to the addon's own host.
+ */
 export declare const wireRemoteAddon: (config: WireRemoteAddonConfig) => void;

package/dist/wirings/addon/wire-remote-addon.js

@@ -1,4 +1,8 @@
 import { pikkuState } from '../../pikku-state.js';
+/**
+ * Installs an addon that runs as its own deployed service: the contract is
+ * local, the calls go over the wire to the addon's own host.
+ */
 export const wireRemoteAddon = (config) => {
     pikkuState(null, 'addons', 'packages').set(config.name, {
         package: config.package,