@pikku/core 0.12.92 → 0.12.94

package/dist/wirings/agent/agent-prepare.js

@@ -1,7 +1,7 @@
 import { PikkuError } from '../../errors/error-handler.js';
 import { checkAuthPermissions, runPermissions, } from '../../permissions.js';
 import { AIProviderNotConfiguredError } from '../../errors/errors.js';
-import { ForbiddenError } from '../../errors/errors.js';
+import { ForbiddenError, MissingSessionError } from '../../errors/errors.js';
 import { verifyScopes } from '../../scopes.js';
 import { pikkuState, getSingletonServices } from '../../pikku-state.js';
 import { createMiddlewareSessionWireProps } from '../../services/user-session-service.js';
@@ -166,7 +166,7 @@ export async function assertAgentAuthorized(agent, params, packageName) {
         ? await params.sessionService.get()
         : undefined;
     if (agent.auth === true && !session) {
-        throw new ForbiddenError('Authentication required');
+        throw new MissingSessionError('Authentication required');
     }
     verifyScopes(agent.scopes, session);
     const singletonServices = getSingletonServices();

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

@@ -171,6 +171,7 @@ export interface AgentToolDef extends Partial<ApprovalPolicy> {
     forwardsApproval?: boolean;
 }
 export interface PikkuAgentMiddlewareHooks<State extends Record<string, unknown> = Record<string, unknown>, SingletonServices extends CoreSingletonServices = CoreSingletonServices> {
+    /** Rewrites what the model is about to see — messages and instructions — before each turn. */
     modifyInput?: (services: SingletonServices, ctx: {
         messages: AgentMessage[];
         instructions: string;
@@ -198,6 +199,7 @@ export interface PikkuAgentMiddlewareHooks<State extends Record<string, unknown>
         messages: AgentMessage[];
         instructions: string;
     };
+    /** Sees the model's output as it streams, for redaction or live inspection. Keeps its own `state` across chunks, unlike the shared run notes. */
     modifyOutputStream?: (services: SingletonServices, ctx: {
         event: AgentStreamEvent;
         allEvents: readonly AgentStreamEvent[];
@@ -242,6 +244,7 @@ export interface PikkuAgentMiddlewareHooks<State extends Record<string, unknown>
      * and handed to anything that grades the run, and scrubbing the reply alone
      * leaves them untouched.
      */
+    /** Rewrites the finished output of a turn, after streaming has completed. */
     modifyOutput?: (services: SingletonServices, ctx: {
         text: string;
         messages: AgentMessage[];
@@ -259,6 +262,7 @@ export interface PikkuAgentMiddlewareHooks<State extends Record<string, unknown>
         messages: AgentMessage[];
         toolCalls?: NonNullable<AgentStep['toolCalls']>;
     };
+    /** Runs before a tool executes, and may rewrite the arguments the model chose. Returning nothing leaves them as they are. */
     beforeToolCall?: (services: SingletonServices, ctx: {
         toolName: string;
         toolCallId: string;
@@ -268,6 +272,7 @@ export interface PikkuAgentMiddlewareHooks<State extends Record<string, unknown>
     } | void> | {
         args: Record<string, unknown>;
     } | void;
+    /** Runs once a tool has returned, and may replace its result before the model sees it. */
     afterToolCall?: (services: SingletonServices, ctx: {
         toolName: string;
         toolCallId: string;
@@ -279,6 +284,7 @@ export interface PikkuAgentMiddlewareHooks<State extends Record<string, unknown>
     } | void> | {
         result: unknown;
     } | void;
+    /** Runs at the end of each model turn. For observation — it cannot change what happened. */
     afterStep?: (services: SingletonServices, ctx: {
         stepNumber: number;
         text: string;
@@ -300,6 +306,7 @@ export interface PikkuAgentMiddlewareHooks<State extends Record<string, unknown>
         };
         finishReason: string;
     }) => Promise<void> | void;
+    /** Runs when a turn throws, with the step it failed on. For logging and cleanup; it does not swallow the error. */
     onError?: (services: SingletonServices, ctx: {
         error: Error;
         stepNumber: number;
@@ -314,58 +321,51 @@ export type AgentMemoryConfig = {
     workingMemory?: unknown;
 };
 export type CoreAgent<PikkuPermission = CorePikkuPermission<any, any>, PikkuMiddleware = CorePikkuMiddleware<any>, Scope extends string = string, Scorer extends string = string> = {
+    /** Unique across the project. It is how the agent is invoked and how its runs are grouped. */
     name: string;
+    /** What the agent is for. Another agent choosing whether to delegate to this one reads it, so write it for that reader. */
     description: string;
+    /** A one-line description for listings, where the full `description` is too long. */
     summary?: string;
+    /** Names of error classes this may throw, so each one's registered status is used instead of a 500. */
     errors?: string[];
-    /**
-     * The three fields below are the system prompt. `buildInstructions` joins
-     * whichever are set with a blank line, always in this order — role, then
-     * personality, then goal — and appends the tool-usage rules if the agent has
-     * tools. Nothing checks them against each other: the split is there to keep a
-     * prompt legible, and text put in the wrong one still reaches the model.
-     *
-     * Who the agent is. 'You are a support engineer triaging inbound bugs.'
-     */
+    /** Who the agent is. Joined with `personality` and `goal`, in that order, to form the system prompt. */
     role?: string;
     /** How it should sound: tone, vocabulary, how much it says at a time. */
     personality?: string;
     /** What it is for — the only one of the three that is required. */
     goal: string;
+    /** Which model to run on, as the provider names it. */
     model: string;
+    /** How much the model is allowed to vary its answer. Lower is more repeatable, which is what a tool-driving agent usually wants. */
     temperature?: number;
     /** Ownership/partitioning of this agent's threads and runs. Defaults to `'user'`. */
     sessionScope?: SessionScope;
+    /** Functions the model may call, given to it as tools. A `readonly` one may be called without asking first. */
     tools?: unknown[];
+    /** Other agents this one may hand work to. `agentMode` decides whether it delegates or supervises. */
     agents?: unknown[];
+    /** Workflows the model may start, for work too long to sit inside one agent run. */
     workflows?: unknown[];
-    /**
-     * Grades this agent's finished runs on live traffic, named by the generated
-     * `ScorerName` union rather than by `ref()` — a scorer is not a function, so
-     * there is nothing in the function map for a ref to resolve against.
-     *
-     * A reference-based judge listed here is never sampled: live traffic has no
-     * answer key. Scenarios name scorers directly and may grade with scorers an
-     * agent does not ship with.
-     */
+    /** Grades finished runs on live traffic. A reference-based judge is never sampled here — live traffic has no answer key. */
     scorers?: Scorer[];
+    /** `delegate` hands a sub-agent the task and takes its answer; `supervise` keeps this agent in the loop over each step. */
     agentMode?: 'delegate' | 'supervise';
+    /** What the agent carries between runs, and how much of it. */
     memory?: AgentMemoryConfig;
+    /** How many model turns a single run may take before it is stopped. The guard against a tool loop that never converges. */
     maxSteps?: number;
+    /** Whether the model may answer without calling a tool (`auto`), must call one (`required`), or may not (`none`). */
     toolChoice?: 'auto' | 'required' | 'none';
-    /**
-     * Per-provider model settings, keyed by provider id and passed through
-     * untouched — for anything only one vendor offers, which the fields above
-     * deliberately do not try to unify.
-     *
-     * `{ openai: { reasoningEffort: 'minimal' } }` is the one that matters for
-     * voice: on gpt-5-mini it measured 0.9s to first token against 2.5s at the
-     * default, and a spoken reply is waited through rather than skimmed.
-     */
+    /** Per-provider settings passed through untouched, for what only one vendor offers. */
     providerOptions?: AIProviderOptions;
+    /** The schema of what starts a run, which is also its input type. */
     input?: unknown;
+    /** The schema the final answer must match, which is also its return type. Without one the agent returns free text. */
     output?: unknown;
+    /** Filters this agent in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
     tags?: string[];
+    /** Runs before each model turn, to change what that turn sees or to stop the run. This is where a step budget or a tool narrowing goes. */
     prepareStep?: (ctx: {
         stepNumber: number;
         messages: AgentMessage[];
@@ -374,8 +374,11 @@ export type CoreAgent<PikkuPermission = CorePikkuPermission<any, any>, PikkuMidd
         model: string;
         stop: () => void;
     }) => void | Promise<void>;
+    /** Wraps the whole run: auth, tracing, spend limits. */
     middleware?: PikkuMiddleware[];
+    /** Wraps each message when the agent is driven over a channel. */
     channelMiddleware?: CorePikkuChannelMiddleware<any, any>[];
+    /** Hooks around each step and each tool call — the place to inspect, rewrite or veto what the model is about to do. */
     agentMiddleware?: PikkuAgentMiddlewareHooks<any, any>[];
     /**
      * Whether a session is required to run this agent. Defaults to `false`, since
@@ -394,6 +397,7 @@ export type CoreAgent<PikkuPermission = CorePikkuPermission<any, any>, PikkuMidd
      * `#pikku/scopes`, so an undeclared scope is a compile error.
      */
     scopes?: Scope[];
+    /** Checks that run before the agent starts. Grouped names OR together, so any one passing admits the caller. */
     permissions?: CorePermissionGroup<PikkuPermission>;
 };
 export type AgentStreamEvent = {

package/dist/wirings/agent-scorer/agent-scorer.d.ts

@@ -2,6 +2,8 @@ import type { JudgeToolCallDisclosure, PikkuAgentScorer, ScorerInput, ScorerOutp
 /**
  * A heuristic scorer: pure code over the finished run, no model call, so it
  * grades on the fast lane.
+ *
+ * @example snippet: agentScorer
  */
 export declare const pikkuAgentScorer: <Services = any>(config: {
     name: string;
@@ -22,6 +24,8 @@ export declare const pikkuAgentScorer: <Services = any>(config: {
  * The rubric field is `goal`, matching `pikkuAgent`'s prompt vocabulary — a
  * judge is a degenerate agent, and should use the same word for the same thing.
  * `prompt` is the escape hatch for non-standard framing.
+ *
+ * @example snippet: agentJudge
  */
 export declare const pikkuAgentJudge: <Services = any>(config: {
     name: string;

package/dist/wirings/agent-scorer/agent-scorer.js

@@ -9,6 +9,8 @@ const assertSampleRate = (name, sampleRate) => {
 /**
  * A heuristic scorer: pure code over the finished run, no model call, so it
  * grades on the fast lane.
+ *
+ * @example snippet: agentScorer
  */
 export const pikkuAgentScorer = (config) => ({
     name: config.name,
@@ -25,6 +27,8 @@ export const pikkuAgentScorer = (config) => ({
  * The rubric field is `goal`, matching `pikkuAgent`'s prompt vocabulary — a
  * judge is a degenerate agent, and should use the same word for the same thing.
  * `prompt` is the escape hatch for non-standard framing.
+ *
+ * @example snippet: agentJudge
  */
 export const pikkuAgentJudge = (config) => ({
     name: config.name,

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

@@ -48,8 +48,11 @@ export interface ChannelMeta {
 }
 export type ChannelsMeta = Record<string, ChannelMeta>;
 export type CoreChannel<ChannelData, Channel extends string, ChannelConnect = CorePikkuFunctionConfig<CorePikkuFunction<void, unknown> | CorePikkuFunctionSessionless<void, unknown>, CorePikkuPermission<void>, CorePikkuMiddleware>, ChannelDisconnect = CorePikkuFunctionConfig<CorePikkuFunction<void, void> | CorePikkuFunctionSessionless<void, void>, CorePikkuPermission<void>, CorePikkuMiddleware>, ChannelFunctionMessage = CorePikkuFunctionConfig<CorePikkuFunction<unknown, unknown> | CorePikkuFunctionSessionless<unknown, unknown>, CorePikkuPermission<unknown>, CorePikkuMiddleware>, PikkuPermission = CorePikkuPermission<ChannelData>, PikkuMiddleware = CorePikkuMiddleware> = {
+    /** Unique across the project. It is how the channel is addressed in `pikku meta` and by the generated client. */
     name: string;
+    /** The path a client opens the socket on. */
     route: Channel;
+    /** Runs once when a client connects, before any message. Its return value is sent as the first message. */
     onConnect?: ChannelConnect | {
         func?: ChannelConnect;
         middleware?: PikkuMiddleware[];
@@ -58,17 +61,25 @@ export type CoreChannel<ChannelData, Channel extends string, ChannelConnect = Co
         func?: ChannelDisconnect;
         middleware?: PikkuMiddleware[];
     };
+    /** Handles any message that no `onMessageWiring` entry claimed. Without one, an unrouted message is dropped. */
     onMessage?: ChannelFunctionMessage;
+    /** Routes messages by a key in their payload: the outer key is the field to switch on, the inner key its value. This is how one socket carries many operations. */
     onMessageWiring?: Record<string, Record<string, ChannelFunctionMessage | {
         func: ChannelFunctionMessage;
         auth?: boolean;
         middleware?: PikkuMiddleware[];
     }>>;
+    /** Wraps the connection: it runs on connect, where the session is established, not on every message. */
     middleware?: PikkuMiddleware[];
+    /** Wraps every message, which is where per-message concerns like rate limiting belong. */
     channelMiddleware?: Array<CorePikkuChannelMiddleware | CorePikkuChannelMiddlewareFactory>;
+    /** Whether opening the channel requires a session. Defaults to true — a channel is closed unless it says otherwise. */
     auth?: boolean;
+    /** Whether this channel carries binary frames. Text frames are still parsed as JSON. */
     binary?: boolean | null;
+    /** Handles binary frames, which never reach `onMessage` because they are not JSON. Return a value to reply in kind. */
     onBinaryMessage?: (services: any, data: BinaryData, channel: PikkuChannel<ChannelData, any>) => Promise<BinaryData | void> | BinaryData | void;
+    /** Filters this channel in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
     tags?: string[];
 };
 /**

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

@@ -127,13 +127,18 @@ type StripBrackets<S extends string> = S extends `<${infer Inner}>` ? Inner : S
  * Split string by spaces
  */
 type SplitBySpace<S extends string> = S extends `${infer First} ${infer Rest}` ? [First, ...SplitBySpace<Rest>] : S extends '' ? [] : [S];
+/**
+ * Strip the `...` a variadic positional carries, so `[files...]` validates
+ * against the `files` key the runtime parser fills.
+ */
+type StripVariadic<S extends string> = S extends `${infer Name}...` ? Name : S;
 /**
  * Recursively build a tuple by stripping brackets from each element
  */
 type BuildParamsTuple<Parts extends readonly string[]> = Parts extends readonly [
     infer First extends string,
     ...infer Rest extends string[]
-] ? [StripBrackets<First>, ...BuildParamsTuple<Rest>] : [];
+] ? [StripVariadic<StripBrackets<First>>, ...BuildParamsTuple<Rest>] : [];
 /**
  * Extract parameter names from CLI parameter string into a tuple
  * Example: "<env> [region]" => ["env", "region"]
@@ -152,16 +157,39 @@ export type ValidateParameters<Params extends string, Input> = AllParamsValid<Ex
  * This is a helper type for creating type-safe CLI commands.
  */
 export type CoreCLICommandConfig<FuncConfig, PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<any, any>, PikkuCLIRender extends CorePikkuCLIRender<any, any, any> = CorePikkuCLIRender<any, any>, Params extends string = string> = {
+    /**
+     * Positional arguments, written the way `--help` prints them: `<env>` is
+     * required, `[region]` optional. Each name must be a key of the function's
+     * input schema, so a typo is a compile error rather than an argument that
+     * silently never arrives.
+     */
     parameters?: ValidateParameters<Params, ExtractFunctionInput<FuncConfig>>;
+    /** The function to run. Omit it on a command that exists only to hold `subcommands`. */
     func?: FuncConfig;
+    /** The heading shown above this command's own help. */
     title?: string;
+    /** The one-line summary listed beside the command name. */
     description?: string;
+    /**
+     * Prints the result. The function returns data and this is the only thing
+     * that writes to stdout, which is what lets one command serve both a human
+     * reading it and a script parsing it.
+     */
     render?: PikkuCLIRender;
+    /**
+     * Flags, keyed by the input field each one fills. A field with no entry is
+     * still accepted as `--field`; an entry is how it gets a short form, a
+     * default, or help text.
+     */
     options?: {
         [K in keyof ExtractFunctionInput<FuncConfig>]?: {
+            /** What this flag is for, as `--help` prints it. */
             description?: string;
+            /** A single-letter alias, so `--verbose` can also be `-v`. */
             short?: string;
+            /** How the argument is parsed. Inferred from the input schema when omitted. */
             type?: CLIOptionType;
+            /** Used when the flag is absent, and shown in `--help` so nobody has to guess it. */
             default?: ExtractFunctionInput<FuncConfig>[K];
             /**
              * The values this option accepts. Rejected by the parser and listed in
@@ -171,10 +199,15 @@ export type CoreCLICommandConfig<FuncConfig, PikkuMiddleware extends CorePikkuMi
             choices?: ReadonlyArray<ExtractFunctionInput<FuncConfig>[K]>;
         };
     };
+    /** Wraps every run of this command. */
     middleware?: PikkuMiddleware[];
+    /** Nested commands, keyed by the word that selects them: `deploy plan` is `deploy` with a `plan` subcommand. */
     subcommands?: Record<string, CoreCLICommandConfig<any, PikkuMiddleware, PikkuCLIRender, any>>;
+    /** Whether running this requires a logged-in session. Defaults to true — a command is closed unless it says otherwise. */
     auth?: boolean;
+    /** Permission checks run before the function, for a command that not every logged-in user may run. */
     permissions?: any[];
+    /** Runs when the parent is invoked with no subcommand named. */
     isDefault?: boolean;
 };
 /**
@@ -203,14 +236,23 @@ export type CLICommandShorthand<In, Out, PikkuFunctionConfig extends CorePikkuFu
  * CLI wiring configuration
  */
 export interface CoreCLI<Commands extends Record<string, CoreCLICommandConfig<any, any, any>>, Options, PikkuMiddleware, PikkuCLIRender> {
+    /** The command name a user types. It is also what `--help` prints as the program. */
     program: string;
+    /** What the program is for, shown at the top of `--help`. */
     description?: string;
+    /** Top-level commands, keyed by the word that selects them. */
     commands: Commands;
+    /** Flags accepted before any command, for things that apply to the whole program. */
     options?: CLIOptions<Options>;
+    /** Wraps every command. */
     middleware?: PikkuMiddleware[];
+    /** The fallback printer for commands that declare none of their own. */
     render?: PikkuCLIRender;
+    /** A one-line description for listings, where the full `description` is too long. */
     summary?: string;
+    /** Names of error classes any command may throw, so each one's registered exit behaviour is used. */
     errors?: string[];
+    /** Filters this program in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
     tags?: string[];
     /**
      * Requires a session on the websocket serving this program remotely. Has no

package/dist/wirings/cli/define-cli-commands.d.ts

@@ -1,3 +1,8 @@
 import type { CoreCLICommandConfig } from './cli.types.js';
-/** Identity at runtime; exists so a commands record can be typed and composed before `wireCLI`. */
+/**
+ * Identity at runtime; exists so a commands record can be typed and composed
+ * before `wireCLI`.
+ *
+ * @example snippet: cliCommandContract
+ */
 export declare function defineCLICommands<T extends Record<string, CoreCLICommandConfig<any, any, any, any>>>(commands: T): T;

package/dist/wirings/cli/define-cli-commands.js

@@ -1,4 +1,9 @@
-/** Identity at runtime; exists so a commands record can be typed and composed before `wireCLI`. */
+/**
+ * Identity at runtime; exists so a commands record can be typed and composed
+ * before `wireCLI`.
+ *
+ * @example snippet: cliCommandContract
+ */
 export function defineCLICommands(commands) {
     return commands;
 }

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

@@ -1,11 +1,18 @@
 import type { OAuth2CredentialConfig } from '../secret/secret.types.js';
 export type CoreCredential<T = unknown> = {
+    /** How the credential is asked for in code. Generated into `CredentialsMap`, so it is what `credentials.get` autocompletes. */
     name: string;
+    /** The name shown to whoever has to supply the value, who is often not the person who wrote this. */
     displayName: string;
+    /** What the credential is for and where to obtain one. */
     description?: string;
+    /** `singleton` is one value for the whole deployment; `wire` is one per user, supplied by them and stored against their account. */
     type: 'singleton' | 'wire';
+    /** The shape of the value, validated when it is supplied rather than when it is first used. */
     schema: T;
+    /** Where to go to create one, shown next to the field asking for it. */
     docsUrl?: string;
+    /** Makes this an OAuth connection rather than a value pasted in: the user is sent to the provider and the tokens are stored for them. */
     oauth2?: OAuth2CredentialConfig & {
         appCredentialSecretId: string;
     };

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

@@ -9,6 +9,10 @@ export interface GatewayAttachment {
     mimeType?: string;
     filename?: string;
 }
+/**
+ * One message arriving from a gateway, normalised: who sent it, in which
+ * conversation, and what they said.
+ */
 export interface GatewayInboundMessage {
     /** Platform-specific: a phone number, a Slack user id, and so on. */
     senderId: string;
@@ -17,17 +21,29 @@ export interface GatewayInboundMessage {
     attachments?: GatewayAttachment[];
     metadata?: Record<string, unknown>;
 }
+/**
+ * One message to send back through a gateway — plain text, or the provider's
+ * own rich content.
+ */
 export interface GatewayOutboundMessage {
     text?: string;
     richContent?: Record<string, unknown>;
     attachments?: GatewayAttachment[];
 }
+/**
+ * What a gateway's `verifyWebhook` returns — verified, with the response the
+ * provider expects back, or not.
+ */
 export type WebhookVerificationResult = {
     verified: true;
     response: unknown;
 } | {
     verified: false;
 };
+/**
+ * What a gateway integration implements: parse an incoming event into a
+ * message, send one back, and open and close the connection.
+ */
 export interface GatewayAdapter {
     name: string;
     /** Return null to ignore the event, e.g. a delivery receipt. */
@@ -49,14 +65,21 @@ export interface PikkuGateway {
 /** 'webhook' the platform POSTs to us, 'websocket' the client connects to us, 'listener' no route at all. */
 export type GatewayTransportType = 'webhook' | 'websocket' | 'listener';
 export type CoreGateway<PikkuFunctionConfig = CorePikkuFunctionConfig<any, any>, PikkuMiddleware extends CorePikkuMiddleware = CorePikkuMiddleware> = Partial<Pick<CommonWireMeta, 'title' | 'summary' | 'description' | 'errors'>> & {
+    /** Unique across the project. It is how the gateway is addressed in `pikku meta` and in logs. */
     name: string;
+    /** How the platform reaches us: a `webhook` it posts to, a `websocket` it holds open, or a `listener` we open outward. */
     type: GatewayTransportType;
     /** Required for 'webhook' and 'websocket'; unused for 'listener'. */
     route?: string;
+    /** Which service this speaks to — slack, whatsapp, discord. It selects the adapter's dialect, not the transport. */
     platform?: string;
+    /** Translates between the platform's message format and pikku's. A factory is called with services, for an adapter that needs a token or a client. */
     adapter: GatewayAdapter | GatewayAdapterFactory;
+    /** The function to run per inbound message. It receives the normalised message, not the platform's raw payload. */
     func: PikkuFunctionConfig;
+    /** Wraps every inbound message: signature verification, tracing, rate limiting. */
     middleware?: CorePikkuMiddlewareGroup<any, any>;
+    /** Filters this gateway in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
     tags?: string[];
     /** Unset lets the handler's own `auth` govern; gateway handlers are sessionless by default. */
     auth?: boolean;

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

@@ -26,14 +26,18 @@ export type RunHTTPWiringOptions = Partial<{
 export type HTTPMethod = 'post' | 'get' | 'delete' | 'patch' | 'head' | 'put' | 'options';
 export type HTTPHeadersSchema = StandardSchemaV1<Record<string, string | string[] | undefined>>;
 export type HTTPRouteBaseConfig = {
+    /** How the body is serialised. Defaults to JSON; `xml` is for routes a caller you do not control insists on. */
     contentType?: 'xml' | 'json';
+    /** Seconds before the request is abandoned. Work that can outlast a request should be dispatched instead, not given a longer timeout. */
     timeout?: number;
+    /** Filters this route in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
     tags?: string[];
+    /** A schema the request headers are validated against, so a missing or malformed header fails before the function body runs. */
     headers?: HTTPHeadersSchema;
 };
 export type CoreHTTPFunction = HTTPRouteBaseConfig & {
     route: string;
-    eventChannel?: false;
+    /** Sends the returned value as-is rather than JSON-encoding it, for a route whose body is binary or already serialised. */
     returnsJSON?: false;
 };
 export interface PikkuHTTP<In = unknown> {
@@ -41,51 +45,61 @@ export interface PikkuHTTP<In = unknown> {
     response?: PikkuHTTPResponse;
 }
 export type PikkuQuery<T = Record<string, string | undefined>> = Record<string, string | T | null | Array<T | null>>;
-export type CoreHTTPFunctionWiring<In, Out, R extends string, PikkuFunction extends CorePikkuFunction<In, Out, any, any, any> = CorePikkuFunction<In, Out>, PikkuFunctionSessionless extends CorePikkuFunctionSessionless<In, Out, any, any, any> = CorePikkuFunctionSessionless<In, Out>, PikkuPermission extends CorePikkuPermission<In, any, any> = CorePikkuPermission<In, any, any>, PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<any, any>> = (CoreHTTPFunction & {
+/**
+ * The keys every HTTP wiring takes, whatever it is wired to. The three that
+ * are not here — `method`, `auth` and `func` — are correlated rather than
+ * independent, and live in the unions below.
+ */
+type HTTPWiringShared<R extends string, PikkuMiddleware extends CorePikkuMiddleware<any, any>> = CoreHTTPFunction & {
+    /**
+     * The path this wiring answers on. `:name` marks a parameter, and every
+     * parameter in the path must be a key of the function's input schema —
+     * a mismatch is a compile error rather than a 404 at runtime.
+     */
     route: R;
-    method: HTTPMethod;
-    func: CorePikkuFunctionConfig<PikkuFunction, PikkuPermission, PikkuMiddleware>;
-    auth?: true;
+    /** Wraps every request to this route: auth, tracing, rate limiting. Runs before the permissions on `func`. */
     middleware?: PikkuMiddleware[];
-    sse?: undefined;
-}) | (CoreHTTPFunction & {
-    route: R;
-    method: HTTPMethod;
-    func: CorePikkuFunctionConfig<PikkuFunctionSessionless, PikkuPermission, PikkuMiddleware>;
+};
+/**
+ * `auth` decides which kind of function this route can point at, so the two
+ * travel together: a route that requires a session gets a function that is
+ * handed one, and an open route gets a sessionless function that has none to
+ * read. Splitting them would let a function ask for a session the route never
+ * establishes.
+ */
+type HTTPWiringAuth<In, Out, PikkuFunction extends CorePikkuFunction<In, Out, any, any, any>, PikkuFunctionSessionless extends CorePikkuFunctionSessionless<In, Out, any, any, any>, PikkuPermission extends CorePikkuPermission<In, any, any>, PikkuMiddleware extends CorePikkuMiddleware<any, any>> = {
+    /** Whether reaching this route requires a session. Defaults to true — a route is closed unless it says otherwise. */
+    auth?: true;
+    /** The function to run. It is handed the session this route required. */
+    func: CorePikkuFunctionConfig<PikkuFunction, PikkuPermission, PikkuMiddleware>;
+} | {
+    /** Whether reaching this route requires a session. Defaults to true — a route is closed unless it says otherwise. */
     auth?: false;
-    middleware?: PikkuMiddleware[];
+    /** On an open route there is no session, so this must be a sessionless function. */
+    func: CorePikkuFunctionConfig<PikkuFunctionSessionless, PikkuPermission, PikkuMiddleware>;
+};
+/**
+ * `sse` and `query` are each valid on one method only, so the method carries
+ * them: streaming is a GET, and naming which input keys arrive in the query
+ * string is only a question on a POST, where the rest of the input is a body.
+ */
+type HTTPWiringMethod<In> = {
+    /** The HTTP method. A route and method together address one wiring. */
+    method: HTTPMethod;
     sse?: undefined;
-}) | (CoreHTTPFunction & {
-    route: R;
-    method: 'get';
-    func: CorePikkuFunctionConfig<PikkuFunction, PikkuPermission, PikkuMiddleware>;
-    auth?: true;
-    middleware?: PikkuMiddleware[];
-    sse?: boolean;
-}) | (CoreHTTPFunction & {
-    route: R;
+} | {
+    /** The HTTP method. A route and method together address one wiring. */
     method: 'get';
-    func: CorePikkuFunctionConfig<PikkuFunctionSessionless, PikkuPermission, PikkuMiddleware>;
-    auth?: false;
-    middleware?: PikkuMiddleware[];
+    /** Streams the response as server-sent events instead of returning it once. GET only. */
     sse?: boolean;
-}) | (CoreHTTPFunction & {
-    route: R;
+} | {
+    /** The HTTP method. A route and method together address one wiring. */
     method: 'post';
-    func: CorePikkuFunctionConfig<PikkuFunction, PikkuPermission, PikkuMiddleware>;
-    auth?: true;
-    middleware?: PikkuMiddleware[];
+    /** Input keys that arrive in the query string rather than the body. POST only, where the body is the default home for input. */
     query?: Array<keyof In>;
     sse?: undefined;
-}) | (CoreHTTPFunction & {
-    route: R;
-    method: 'post';
-    func: CorePikkuFunctionConfig<PikkuFunctionSessionless, PikkuPermission, PikkuMiddleware>;
-    auth?: false;
-    middleware?: PikkuMiddleware[];
-    query?: Array<keyof In>;
-    sse?: undefined;
-});
+};
+export type CoreHTTPFunctionWiring<In, Out, R extends string, PikkuFunction extends CorePikkuFunction<In, Out, any, any, any> = CorePikkuFunction<In, Out>, PikkuFunctionSessionless extends CorePikkuFunctionSessionless<In, Out, any, any, any> = CorePikkuFunctionSessionless<In, Out>, PikkuPermission extends CorePikkuPermission<In, any, any> = CorePikkuPermission<In, any, any>, PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<any, any>> = HTTPWiringShared<R, PikkuMiddleware> & HTTPWiringAuth<In, Out, PikkuFunction, PikkuFunctionSessionless, PikkuPermission, PikkuMiddleware> & HTTPWiringMethod<In>;
 export type HTTPFunctionMetaInputTypes = {
     params?: string;
     query?: string;

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

@@ -40,36 +40,63 @@ export type MCPPromptMeta = Record<string, Omit<CoreMCPPrompt, 'func' | 'middlew
     middleware?: MiddlewareMetadata[];
 }>;
 export type CoreMCPResource<PikkuFunctionConfig = CorePikkuFunctionConfig<CorePikkuFunctionSessionless<any, any>>, PikkuPermission = CorePikkuPermission<any, any>, PikkuMiddleware = CorePikkuMiddleware<any>> = {
+    /** How the client addresses this resource. `{name}` marks a parameter, and every parameter must be a key of the function's input schema. */
     uri: string;
+    /** The name a human sees in a client's resource list. */
     title: string;
+    /** What the resource holds, written for the model deciding whether to read it. */
     description: string;
+    /** A one-line description for listings, where the full `description` is too long. */
     summary?: string;
+    /** Names of error classes this may throw, so the client is told which failures are its own fault. */
     errors?: string[];
+    /** The media type of what the function returns, so the client knows whether it is text, JSON or an image. */
     mimeType?: string;
+    /** Size in bytes, where it is known ahead of the read. A client uses it to decide whether to fetch at all. */
     size?: number;
+    /** Whether the function returns the content in chunks rather than at once. */
     streaming?: boolean;
+    /** The function to run. It is sessionless: an MCP client is not a logged-in user. */
     func: PikkuFunctionConfig;
+    /** Filters this wiring in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
     tags?: string[];
+    /** Wraps every call: tracing, rate limiting, whatever the transport does not do. */
     middleware?: PikkuMiddleware[];
 };
 export type CoreMCPTool<PikkuFunctionConfig = CorePikkuFunctionConfig<CorePikkuFunctionSessionless<any, any>>, PikkuPermission = CorePikkuPermission<any, any>, PikkuMiddleware = CorePikkuMiddleware<any>> = {
+    /** How the model calls this tool. It is the tool's identity, so renaming it breaks any client that already knows it. */
     name: string;
+    /** The name a human sees, where the calling `name` is not readable. */
     title?: string;
+    /** What the tool does and when to reach for it. This is what the model decides on, so it earns more care than the rest of this object. */
     description?: string;
+    /** A one-line description for listings, where the full `description` is too long. */
     summary?: string;
+    /** Names of error classes this may throw, so the client is told which failures are its own fault. */
     errors?: string[];
+    /** The function to run. It is sessionless: an MCP client is not a logged-in user. */
     func: PikkuFunctionConfig;
+    /** Filters this wiring in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
     tags?: string[];
+    /** Whether the function returns its result in chunks rather than at once. */
     streaming?: boolean;
+    /** Wraps every call: tracing, rate limiting, whatever the transport does not do. */
     middleware?: PikkuMiddleware[];
 };
 export type CoreMCPPrompt<PikkuFunctionConfig = CorePikkuFunctionConfig<CorePikkuFunctionSessionless<any, MCPPromptResponse>>, PikkuPermission = CorePikkuPermission<any, any>, PikkuMiddleware = CorePikkuMiddleware<any>> = {
+    /** How the client asks for this prompt. */
     name: string;
+    /** What the prompt is for, written for the human picking it out of a list. */
     description: string;
+    /** A one-line description for listings, where the full `description` is too long. */
     summary?: string;
+    /** Names of error classes this may throw, so the client is told which failures are its own fault. */
     errors?: string[];
+    /** The function to run. It is sessionless: an MCP client is not a logged-in user. */
     func: PikkuFunctionConfig;
+    /** Filters this wiring in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
     tags?: string[];
+    /** Wraps every call: tracing, rate limiting, whatever the transport does not do. */
     middleware?: PikkuMiddleware[];
 };
 export type JsonRpcRequest = {

package/dist/wirings/persona/index.d.ts

@@ -4,6 +4,7 @@ export type { RoleVerification } from './validate-personas.js';
 export { personaEnvironmentErrors, personaEnvironmentRefusal, } from './persona-environments.js';
 export type { PersonaEnvironment, PersonaEnvironmentSubject, } from './persona-environments.js';
 export { personaEmail, personaEmails } from './persona-email.js';
+export { APP_SCOPE_ROOT, appScopeId, buildAppScopeDefinition, } from './persona-app-scopes.js';
 export type { MailboxAllowlist, PersonaMailbox, ReceivedEmail, } from './persona-mailbox.js';
 export type { CorePersona, CorePersonas, PersonaAccountMeta, PersonaDefinitions, PersonaMeta, PersonasMeta, } from './persona.types.js';
 /**