@pikku/core 0.12.91 → 0.12.93

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,

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;