@pikku/core 0.12.91 → 0.12.93

package/CHANGELOG.md

@@ -1,3 +1,105 @@
+## 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
+
+- b521f1b: Resolve the persona to impersonate during the fabric operator sign-in.
+
+  `POST /sign-in/fabric` now takes an optional
+  `actAs: { email, name?, create?, role? }`
+  and returns `actAs: { userId }` — the stage's own id for that address, looked up
+  before creating and created only when asked.
+
+  It has to happen there. Impersonation names a user id, a persona only knows an
+  email, and since better-auth's `admin()` plugin was dropped no HTTP endpoint
+  lists users — so the two calls the scenario runner made to resolve one
+  (`/auth/admin/list-users`, then `/auth/admin/create-user`) had nothing left to
+  reach and every deployed persona failed with `YOU_ARE_NOT_ALLOWED_TO_LIST_USERS`.
+  The adapter is already in hand on the sign-in request and the operator token has
+  already been verified, so the lookup is free and gated by the same check that
+  mints the session.
+
+  A created row gets a `role` only when the caller names one. pikku has no `role`
+  column of its own any more, but an app may still run better-auth's `admin()`
+  plugin and constrain that column, so the persona's first role is passed through
+  for those.
+
+  `OperatorSignInOptions.adminPath` is removed; nothing points at it any more.
+
+  A Fabric operator row now also satisfies the default impersonation gate.
+  `fabric()` grants the `admin` scope only when handed a `ScopeService`, and no
+  app template wires one — so the operator signed in holding nothing and every
+  impersonated request fell back to the operator's own session. The `fabric`
+  column is written by nothing but that sign-in, after an RS256 verification
+  against the stage's public key, so the row's existence is the authorization.
+  The scope half of the gate still fails closed.
+
 ## 0.12.91
 
 ### 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/persona-sign-in.d.ts

@@ -59,8 +59,6 @@ export interface OperatorSignInOptions {
      * for. Turn it on for throwaway stages.
      */
     createMissing?: boolean;
-    /** Admin endpoint prefix under apiUrl. Default `/auth/admin`. */
-    adminPath?: string;
     /** Fabric operator sign-in path under apiUrl. Default `/auth/sign-in/fabric`. */
     signInPath?: string;
 }

package/dist/services/persona-sign-in.js

@@ -67,7 +67,15 @@ export const establishOperatorSession = async (fetchImpl, apiUrl, persona, optio
     const res = await fetchImpl(`${apiUrl}${signInPath}`, {
         method: 'POST',
         headers: { 'content-type': 'application/json', ...extraHeaders },
-        body: JSON.stringify({ token }),
+        body: JSON.stringify({
+            token,
+            actAs: {
+                email: persona.email,
+                name: persona.name,
+                create: options.createMissing ?? false,
+                ...(persona.roles[0] ? { role: persona.roles[0] } : {}),
+            },
+        }),
     });
     if (!res.ok) {
         throw await failed('operator sign-in', persona.id, res);
@@ -76,72 +84,13 @@ export const establishOperatorSession = async (fetchImpl, apiUrl, persona, optio
     if (setCookies.length === 0) {
         throw new Error(`[scenario] operator sign-in for '${persona.id}' returned no session cookie`);
     }
-    // The lookup runs on the session this handshake just established, and a
-    // plain `fetch` keeps no cookies — the browser path in particular hands the
-    // jar's contents to Playwright only after this returns. Forwarding them
-    // explicitly is what keeps the admin calls authenticated for every caller.
-    const session = setCookies
-        .map((raw) => raw.split(';')[0])
-        .filter((pair) => Boolean(pair))
-        .join('; ');
-    const userId = await resolveUserId(fetchImpl, apiUrl, persona, options, {
-        ...extraHeaders,
-        cookie: session,
-    });
-    return { setCookies, userId };
-};
-/**
- * The target's own id for this persona's address, since impersonation names a
- * user id and a persona only knows an email.
- *
- * Looked up before creating, so a persona that already exists is never
- * duplicated and the run reads as "act as this person" rather than "make one".
- */
-const resolveUserId = async (fetchImpl, apiUrl, persona, options, extraHeaders) => {
-    const adminPath = options.adminPath ?? '/auth/admin';
-    const query = new URLSearchParams({
-        filterField: 'email',
-        filterValue: persona.email,
-        filterOperator: 'eq',
-        limit: '1',
-    });
-    const found = await fetchImpl(`${apiUrl}${adminPath}/list-users?${query}`, {
-        headers: { accept: 'application/json', ...extraHeaders },
-    });
-    if (!found.ok) {
-        throw await failed('persona lookup', persona.id, found);
-    }
-    const listed = (await found.json().catch(() => null));
-    const existing = listed?.users?.find((u) => u.email === persona.email);
-    if (existing?.id) {
-        return String(existing.id);
-    }
-    if (!options.createMissing) {
-        throw new Error(`[scenario] no account on the target for persona '${persona.id}' (${persona.email}) — ` +
-            'provision it, or set createMissing on the operator credentials');
-    }
-    const created = await fetchImpl(`${apiUrl}${adminPath}/create-user`, {
-        method: 'POST',
-        headers: { 'content-type': 'application/json', ...extraHeaders },
-        body: JSON.stringify({
-            email: persona.email,
-            name: persona.name,
-            // Never used and never returned: the run impersonates rather than signs
-            // in, so the account is reachable only by someone already holding an
-            // operator token. A derivable password would undo exactly that.
-            password: globalThis.crypto.randomUUID(),
-            ...(persona.roles[0] ? { role: persona.roles[0] } : {}),
-        }),
-    });
-    if (!created.ok) {
-        throw await failed('persona creation', persona.id, created);
-    }
-    const body = (await created.json().catch(() => null));
-    const id = body?.user?.id;
-    if (!id) {
-        throw new Error(`[scenario] creating persona '${persona.id}' returned no user id`);
+    const body = (await res.json().catch(() => null));
+    const userId = body?.actAs?.userId;
+    if (!userId) {
+        throw new Error(`[scenario] operator sign-in for '${persona.id}' returned no user to act as — ` +
+            'the target is running a @pikku/better-auth too old to resolve one');
     }
-    return String(id);
+    return { setCookies, userId: String(userId) };
 };
 /**
  * Sign a persona in on a DEPLOYED stage, by having a Fabric operator act as

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>;