@pikku/core 0.12.143 → 0.12.145

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

@@ -5,6 +5,22 @@ import { type AgentInterruption, type AgentInterruptResult } from './agent-inter
 export declare function checkForApprovals(stepResult: AgentStepResult, tools: AgentRunnerParams['tools']): ToolApprovalRequired[];
 export declare function checkForCredentialRequests(stepResult: AgentStepResult): ToolCredentialRequired[];
 export declare function appendStepMessages(runnerParams: AgentRunnerParams, stepResult: AgentStepResult): void;
+/**
+ * Runs an agent and streams its progress (text deltas, tool calls, approvals, usage) to `channel`.
+ *
+ * Authorization and thread partitioning are as for `runAgent`. A tool needing approval or a
+ * credential ends the stream with an `approval-request` or `credential-request` event and leaves the run
+ * suspended for `resumeAgent`.
+ *
+ * @param agentName - The agent to run.
+ * @param input - The user message, thread and resource ids, and optional model overrides.
+ * @param channel - Receives the `AgentStreamEvent`s.
+ * @param params - The caller's session and credential access.
+ * @param agentSessionMap - Sub-agent session ids, shared across delegated calls in one run.
+ * @param options - Approval policy and a run-created callback.
+ * @returns The full text of the streamed reply.
+ * @throws As `runAgent` does, before the stream starts.
+ */
 export declare function streamAgent(agentName: string, input: {
     message: string;
     threadId: string;
@@ -34,6 +50,20 @@ export declare function interruptAgent(input: {
     runId: string;
     reason?: AgentInterruption['reason'];
 }, params: RunAgentParams): Promise<AgentInterruptResult>;
+/**
+ * Answers one pending approval on a suspended run and streams the continuation to `channel`.
+ * Backs `rpc.agent.resume`.
+ *
+ * Only the run's owner may resume it, and the agent is re-authorized. The approval is claimed
+ * atomically, so a second concurrent resume fails instead of running the tool again.
+ *
+ * @param input - The run, the tool call being answered and the decision.
+ * @param channel - Receives the continuation's `AgentStreamEvent`s.
+ * @param params - The caller's session.
+ * @param options - Approval policy for the rest of the run.
+ * @throws ForbiddenError when the caller does not own the run; Error when the run or its pending
+ * approval is missing, or the approval was already resolved.
+ */
 export declare function resumeAgent(input: {
     runId: string;
     toolCallId: string;

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

@@ -1,10 +1,10 @@
 import { finalizeAgentRun, lastUserMessageText } from './agent-finalize.js';
 import { pikkuState, getSingletonServices } from '../../pikku-state.js';
-import { applyInputMiddleware } from './agent-turn.js';
+import { applyInputMiddleware, describeApprovals } from './agent-turn.js';
 import { AIProviderNotConfiguredError } from '../../errors/errors.js';
 import { deniedToolResult, randomUUID } from './agent-utils.js';
 import { SPOKEN_TRANSCRIPT } from './voice-input.js';
-import { combineChannelMiddleware, wrapChannelWithMiddleware, } from '../channel/channel-middleware-runner.js';
+import { combineChannelMiddleware, wrapChannelWithMiddleware, } from '../../channel-middleware-runner.js';
 import { resolveMemoryServices, loadContextMessages, trimMessages, getWorkingMemoryMiddleware, } from './agent-memory.js';
 import { prepareAgentRun, resolveAgent, buildInstructions, buildToolDefs, createScopedChannel, resolveOwnerResourceId, agentSessionScope, assertResourceOwner, assertResourcePrincipalOwner, assertAgentAuthorized, ToolApprovalRequired, ToolCredentialRequired, APPROVAL_REQUIRED, CREDENTIAL_REQUIRED, } from './agent-prepare.js';
 import { resolveModelConfig } from './agent-model-config.js';
@@ -285,15 +285,7 @@ async function runStreamStepLoop(params) {
             break;
         const approvalsNeeded = checkForApprovals(stepResult, runnerParams.tools);
         if (approvalsNeeded.length > 0) {
-            for (const approval of approvalsNeeded) {
-                const toolDef = runnerParams.tools.find((t) => t.name === approval.toolName);
-                if (toolDef?.approvalDescriptionFn && !approval.reason) {
-                    try {
-                        approval.reason = await toolDef.approvalDescriptionFn(approval.args);
-                    }
-                    catch { }
-                }
-            }
+            await describeApprovals(approvalsNeeded, runnerParams.tools);
             return { outcome: 'approval', approvals: approvalsNeeded };
         }
         const credentialRequests = checkForCredentialRequests(stepResult);
@@ -461,6 +453,22 @@ function handleCredentialRequests(requests, runId, channel, agentRunState, persi
         await channel.close();
     })();
 }
+/**
+ * Runs an agent and streams its progress (text deltas, tool calls, approvals, usage) to `channel`.
+ *
+ * Authorization and thread partitioning are as for `runAgent`. A tool needing approval or a
+ * credential ends the stream with an `approval-request` or `credential-request` event and leaves the run
+ * suspended for `resumeAgent`.
+ *
+ * @param agentName - The agent to run.
+ * @param input - The user message, thread and resource ids, and optional model overrides.
+ * @param channel - Receives the `AgentStreamEvent`s.
+ * @param params - The caller's session and credential access.
+ * @param agentSessionMap - Sub-agent session ids, shared across delegated calls in one run.
+ * @param options - Approval policy and a run-created callback.
+ * @returns The full text of the streamed reply.
+ * @throws As `runAgent` does, before the stream starts.
+ */
 export async function streamAgent(agentName, input, channel, params, agentSessionMap, options) {
     const sessionMap = agentSessionMap ?? new Map();
     const normalizedInput = {
@@ -713,6 +721,20 @@ export async function interruptAgent(input, params) {
     // model call does nothing to a tool already executing.
     return { stopped, inFlightTools: getInFlightTools(input.runId) };
 }
+/**
+ * Answers one pending approval on a suspended run and streams the continuation to `channel`.
+ * Backs `rpc.agent.resume`.
+ *
+ * Only the run's owner may resume it, and the agent is re-authorized. The approval is claimed
+ * atomically, so a second concurrent resume fails instead of running the tool again.
+ *
+ * @param input - The run, the tool call being answered and the decision.
+ * @param channel - Receives the continuation's `AgentStreamEvent`s.
+ * @param params - The caller's session.
+ * @param options - Approval policy for the rest of the run.
+ * @throws ForbiddenError when the caller does not own the run; Error when the run or its pending
+ * approval is missing, or the approval was already resolved.
+ */
 export async function resumeAgent(input, channel, params, options) {
     const singletonServices = getSingletonServices();
     const { agentRunState } = singletonServices;

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

@@ -11,6 +11,10 @@ import type { PikkuRawWire } from '../../types/core.types.js';
 import type { PikkuRPC } from '../rpc/rpc-types.js';
 import type { SessionService } from '../../services/user-session-service.js';
 import type { CoreUserSession } from '../../types/core.types.js';
+/**
+ * What `wire.rpc.agent` needs from the invocation: the caller's session service.
+ * @internal
+ */
 export type AgentRPCOptions = {
     sessionService?: SessionService<CoreUserSession>;
 };
@@ -20,6 +24,10 @@ export type AgentRPCOptions = {
  * without naming the agent runtime.
  */
 export type AgentRPCFactory = (wire: PikkuRawWire, options: AgentRPCOptions) => PikkuRPC['agent'];
+/**
+ * A conversation thread. `resourceId` is its owner partition: the session principal, or a
+ * `principal:` sub-partition of it.
+ */
 export interface AgentThread {
     id: string;
     resourceId: string;
@@ -28,6 +36,7 @@ export interface AgentThread {
     createdAt: Date;
     updatedAt: Date;
 }
+/** One part of a multi-part message: text, an image, a file (audio included) or named data. */
 export type AgentContentPart = {
     type: 'text';
     text: string;
@@ -67,6 +76,7 @@ export interface AgentToolResult {
      */
     error?: string;
 }
+/** A message on an agent thread, as stored and as sent to the model. */
 export interface AgentMessage {
     id: string;
     role: 'system' | 'user' | 'assistant' | 'tool';
@@ -93,6 +103,7 @@ export interface AgentMessage {
     undelivered?: boolean;
     createdAt: Date;
 }
+/** One model step of a run: its token usage and the tool calls it made. */
 export interface AgentStep {
     usage: {
         inputTokens: number;
@@ -113,6 +124,10 @@ export interface AgentInputAttachment {
     mediaType?: string;
     filename?: string;
 }
+/**
+ * What a caller sends to run an agent. `resourceId` is partitioned under the session principal
+ * before use, so it cannot address another user's threads.
+ */
 export interface AgentInput {
     message: string;
     threadId: string;
@@ -190,6 +205,10 @@ export interface AgentToolDef extends Partial<ApprovalPolicy> {
      */
     forwardsApproval?: boolean;
 }
+/**
+ * Hooks an agent middleware can implement: rewrite the model input, observe each step, transform
+ * the output stream, or handle errors. Build one with `pikkuAgentMiddleware`.
+ */
 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: {
@@ -333,6 +352,10 @@ export interface PikkuAgentMiddlewareHooks<State extends Record<string, unknown>
         messages: AgentMessage[];
     }) => Promise<void> | void;
 }
+/**
+ * An agent's memory: which storage, vector store and embedder services to use, how many recent
+ * messages to load, and an optional working-memory schema.
+ */
 export type AgentMemoryConfig = {
     storage?: string;
     vector?: string;
@@ -340,6 +363,10 @@ export type AgentMemoryConfig = {
     lastMessages?: number;
     workingMemory?: unknown;
 };
+/**
+ * The configuration an agent is declared with (`pikkuAgent`): model, instructions, tools,
+ * sub-agents, memory, auth and middleware.
+ */
 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;
@@ -420,6 +447,10 @@ export type CoreAgent<PikkuPermission = CorePikkuPermission<any, any>, PikkuMidd
     /** Checks that run before the agent starts. Grouped names OR together, so any one passing admits the caller. */
     permissions?: CorePermissionGroup<PikkuPermission>;
 };
+/**
+ * An event a streamed agent run sends: step starts, text and reasoning deltas, tool calls and
+ * results, approval and credential requests, usage, errors and `done`.
+ */
 export type AgentStreamEvent = {
     type: 'step-start';
     stepNumber: number;
@@ -555,8 +586,13 @@ export type AgentStreamEvent = {
 } | {
     type: 'done';
 };
+/** The channel a streamed agent run writes `AgentStreamEvent`s to. */
 export interface AgentStreamChannel extends PikkuChannel<unknown, AgentStreamEvent> {
 }
+/**
+ * A tool call a suspended run is waiting on: a direct tool call, a sub-agent's call surfaced to
+ * the parent, or a missing credential.
+ */
 export type PendingApproval = {
     type: 'tool-call';
     toolCallId: string;
@@ -578,6 +614,7 @@ export type PendingApproval = {
     credentialType: 'oauth2' | 'apikey';
     connectUrl?: string;
 };
+/** A run's persisted state: status, why it is suspended, its pending approvals and token usage. */
 export interface AgentRunState {
     runId: string;
     agentName: string;
@@ -596,6 +633,7 @@ export interface AgentRunState {
     createdAt: Date;
     updatedAt: Date;
 }
+/** A run as listed by `AgentRunService`, with usage flattened into columns. */
 export interface AgentRunRow {
     runId: string;
     agentName: string;
@@ -611,6 +649,10 @@ export interface AgentRunRow {
     createdAt: Date;
     updatedAt: Date;
 }
+/**
+ * Read and delete access to stored threads, messages and runs, for consoles and thread APIs.
+ * Pass `owners` from the session (see `threadOwnerConstraint`) whenever results go back to a client.
+ */
 export interface AgentRunService {
     listThreads(options?: {
         agentName?: string;
@@ -635,6 +677,7 @@ export interface AgentRunService {
     deleteThread(threadId: string): Promise<boolean>;
     getDistinctAgentNames(): Promise<string[]>;
 }
+/** Inspector-generated metadata for every agent, keyed by name, without its runtime-only fields. */
 export type AgentsMeta = Record<string, Omit<CoreAgent, 'input' | 'output' | 'tools' | 'agents' | 'workflows' | 'middleware' | 'channelMiddleware' | 'agentMiddleware' | 'permissions'> & {
     tools?: string[];
     agents?: string[];

package/dist/wirings/agent/voice-input.d.ts

@@ -54,6 +54,18 @@ export declare const SPOKEN_TURN = "voice:spokenTurn";
  * bubble followed by an answer to a question they cannot see.
  */
 export declare const SPOKEN_TRANSCRIPT = "voice:transcript";
+/**
+ * Agent middleware that transcribes audio parts of the user's message before the model sees them,
+ * using the `agentRunner`'s transcription support. Records whether the turn was spoken, which
+ * `voiceOutput` reads to decide whether to answer aloud.
+ *
+ * Audio sent by URL is fetched with `safeFetch`: only the `allowedAudioHosts` when given, otherwise
+ * any host that is not private or loopback. Audio over the size limit is rejected.
+ *
+ * @param config - The transcription model (required once audio arrives), language, and hosts audio
+ * URLs may be fetched from.
+ * @throws Error when audio arrives with no `model` configured, or the audio is too large.
+ */
 export declare const voiceInput: (config?: {
     language?: string;
     model?: string;

package/dist/wirings/agent/voice-input.js

@@ -78,6 +78,18 @@ export const SPOKEN_TURN = 'voice:spokenTurn';
  * bubble followed by an answer to a question they cannot see.
  */
 export const SPOKEN_TRANSCRIPT = 'voice:transcript';
+/**
+ * Agent middleware that transcribes audio parts of the user's message before the model sees them,
+ * using the `agentRunner`'s transcription support. Records whether the turn was spoken, which
+ * `voiceOutput` reads to decide whether to answer aloud.
+ *
+ * Audio sent by URL is fetched with `safeFetch`: only the `allowedAudioHosts` when given, otherwise
+ * any host that is not private or loopback. Audio over the size limit is rejected.
+ *
+ * @param config - The transcription model (required once audio arrives), language, and hosts audio
+ * URLs may be fetched from.
+ * @throws Error when audio arrives with no `model` configured, or the audio is too large.
+ */
 export const voiceInput = (config) => pikkuAgentMiddleware({
     modifyInput: async (services, { messages, instructions, shared }) => {
         const agentRunner = services.agentRunner;

package/dist/wirings/agent/voice-output.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Per-reply state `voiceOutput` keeps while synthesizing: unspoken text and the audio emission chain.
+ * @internal
+ */
 export type VoiceOutputState = {
     textBuffer?: string;
     /**
@@ -42,6 +46,16 @@ export declare const unspeakableScripts: (text: string, speakable: SpeakableScri
  * happens to be written in.
  */
 export declare const voiceForText: (text: string, speakable: SpeakableScripts, fallback?: string) => string | undefined;
+/**
+ * Agent middleware that synthesizes the streamed reply to speech sentence by sentence, using the
+ * `agentRunner`'s `generateSpeech`, and sends the audio as it is ready, in order.
+ *
+ * By default it speaks only replies to spoken turns (see `voiceInput`); set `always` to speak every
+ * reply. Text in a script outside `speakableScripts` is left unspoken and reported once.
+ *
+ * @param config - Speech model, voice, format and the other synthesis options.
+ * @throws Error when the `agentRunner` has no `generateSpeech` support.
+ */
 export declare const voiceOutput: (config?: {
     model?: string;
     format?: string;

package/dist/wirings/agent/voice-output.js

@@ -100,6 +100,16 @@ async function synthesizeAudio(agentRunner, input) {
         format: result.audio.format || input.format || 'pcm16',
     };
 }
+/**
+ * Agent middleware that synthesizes the streamed reply to speech sentence by sentence, using the
+ * `agentRunner`'s `generateSpeech`, and sends the audio as it is ready, in order.
+ *
+ * By default it speaks only replies to spoken turns (see `voiceInput`); set `always` to speak every
+ * reply. Text in a script outside `speakableScripts` is left unspoken and reported once.
+ *
+ * @param config - Speech model, voice, format and the other synthesis options.
+ * @throws Error when the `agentRunner` has no `generateSpeech` support.
+ */
 export const voiceOutput = (config) => pikkuAgentMiddleware({
     modifyOutputStream: async (services, { event, state, shared, emit, signal }) => {
         const { agentRunner, logger } = services;

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

@@ -1,4 +1,3 @@
-import { randomUUID } from '../agent/agent-utils.js';
 const JUDGE_OUTPUT_SCHEMA = {
     type: 'object',
     properties: {
@@ -117,7 +116,7 @@ export const runJudge = async (scorer, input, agentRunner) => {
     }
     const messages = [
         {
-            id: randomUUID(),
+            id: globalThis.crypto.randomUUID(),
             role: 'user',
             content: buildJudgePrompt(judge, input),
             createdAt: new Date(),

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

@@ -1,6 +1,16 @@
 import type { PikkuAgentScorer } from './agent-scorer.types.js';
+/**
+ * Registers a scorer's runtime config under its name. Called by generated code.
+ *
+ * Skipped with a warning when the inspector recorded no metadata (scorers must live in a `*.scorer.ts` file).
+ *
+ * @throws Error when a scorer with the same name is already registered.
+ * @internal
+ */
 export declare const addAgentScorer: (scorerName: string, scorer: PikkuAgentScorer<any>, packageName?: string | null) => void;
+/** Every registered scorer, keyed by name. */
 export declare const getAgentScorers: () => Map<string, PikkuAgentScorer>;
+/** The inspector-generated metadata for every scorer, keyed by name. */
 export declare const getAgentScorersMeta: () => import("./agent-scorer.types.js").ScorerMeta;
 /**
  * Resolve a scorer by name across every registered package, the way an agent's

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

@@ -1,4 +1,12 @@
 import { pikkuState } from '../../pikku-state.js';
+/**
+ * Registers a scorer's runtime config under its name. Called by generated code.
+ *
+ * Skipped with a warning when the inspector recorded no metadata (scorers must live in a `*.scorer.ts` file).
+ *
+ * @throws Error when a scorer with the same name is already registered.
+ * @internal
+ */
 export const addAgentScorer = (scorerName, scorer, packageName = null) => {
     const scorersMeta = pikkuState(packageName, 'agent', 'scorersMeta');
     if (!scorersMeta[scorerName]) {
@@ -11,7 +19,9 @@ export const addAgentScorer = (scorerName, scorer, packageName = null) => {
     }
     scorers.set(scorerName, scorer);
 };
+/** Every registered scorer, keyed by name. */
 export const getAgentScorers = () => pikkuState(null, 'agent', 'scorers');
+/** The inspector-generated metadata for every scorer, keyed by name. */
 export const getAgentScorersMeta = () => pikkuState(null, 'agent', 'scorersMeta');
 /**
  * Resolve a scorer by name across every registered package, the way an agent's

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

@@ -6,5 +6,6 @@ import type { ScorerInput } from './agent-scorer.types.js';
  */
 export declare const enableScoreSnapshots: (maxRuns?: number) => void;
 export declare const recordScoreSnapshot: (run: ScorerInput) => void;
+/** The scorer input recorded for `runId`, if snapshots are enabled and it has not been evicted. */
 export declare const getScoreSnapshot: (runId: string) => ScorerInput | undefined;
 export declare const resetScoreSnapshots: () => void;

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

@@ -33,6 +33,7 @@ export const recordScoreSnapshot = (run) => {
         snapshots.delete(oldest);
     }
 };
+/** The scorer input recorded for `runId`, if snapshots are enabled and it has not been evicted. */
 export const getScoreSnapshot = (runId) => snapshots.get(runId);
 export const resetScoreSnapshots = () => {
     snapshots.clear();

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

@@ -30,6 +30,7 @@ export interface ScorerInput {
         model?: string;
     };
 }
+/** What a scorer returns: a 0..1 score, an optional reason and metadata. */
 export interface ScorerOutput {
     /** 0..1, so grades are comparable across scorers. */
     score: number;
@@ -73,6 +74,10 @@ export type ScorerJudgeConfig = {
     toolCalls: JudgeToolCallDisclosure;
     prompt?: (input: ScorerInput) => string;
 };
+/**
+ * A scorer: a heuristic `score` function (from `pikkuAgentScorer`) or an LLM `judge`
+ * (from `pikkuAgentJudge`), with its lane and live sample rate.
+ */
 export type PikkuAgentScorer<Services = any> = {
     name: string;
     description: string;
@@ -87,6 +92,7 @@ export type PikkuAgentScorer<Services = any> = {
     score?: (input: ScorerInput, services: Services) => ScorerOutput | Promise<ScorerOutput>;
     judge?: ScorerJudgeConfig;
 };
+/** Inspector-generated metadata for every scorer, keyed by name. */
 export type ScorerMeta = Record<string, {
     name: string;
     description: string;
@@ -100,6 +106,7 @@ export type ScorerMeta = Record<string, {
 export type ScoreJob = ScorerInput & {
     scorerName: string;
 };
+/** A stored grade of one run by one scorer. */
 export type AgentRunScore = {
     runId: string;
     scorerName: string;

package/dist/wirings/channel/channel-common.js

@@ -1,7 +1,7 @@
 import { combineMiddleware, runMiddleware } from '../../middleware-runner.js';
 import { runPikkuFunc } from '../../function/function-runner.js';
 import { createMiddlewareSessionWireProps, } from '../../services/user-session-service.js';
-import { combineChannelMiddleware, wrapChannelWithMiddleware, } from './channel-middleware-runner.js';
+import { combineChannelMiddleware, wrapChannelWithMiddleware, } from '../../channel-middleware-runner.js';
 export const runChannelLifecycleWithMiddleware = async ({ channelConfig, meta, lifecycleConfig, lifecycleType, services, channel, data, channelMiddlewareMeta, userSession, wireServices, }) => {
     const lifecycleMiddleware = typeof lifecycleConfig === 'object' && 'middleware' in lifecycleConfig
         ? lifecycleConfig.middleware || []

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

@@ -6,6 +6,7 @@
 export declare const CHANNEL_RPC_REQUEST = "pikku-rpc-request";
 export declare const CHANNEL_RPC_RESPONSE = "pikku-rpc-response";
 export declare const CHANNEL_RPC_PENDING = "pikku-rpc-pending";
+/** A request frame asking the peer on a channel to run one of its capabilities. */
 export interface ChannelRPCRequest {
     action: typeof CHANNEL_RPC_REQUEST;
     id: string;
@@ -13,6 +14,7 @@ export interface ChannelRPCRequest {
     data: unknown;
     traceId?: string;
 }
+/** The answer to a {@link ChannelRPCRequest} with the same `id`: a result when `ok`, an error name and message otherwise. */
 export interface ChannelRPCResponse {
     action: typeof CHANNEL_RPC_RESPONSE;
     id: string;
@@ -60,6 +62,7 @@ export interface ApprovalPolicy {
     needsApproval: boolean;
     approvalDescriptionFn?: (input: unknown) => Promise<string> | string;
 }
+/** A function one end of a channel offers for the peer to call through `channel.remote`. */
 export type CapabilityHandler = (data: any) => Promise<unknown> | unknown;
 /**
  * `needsApproval` is required here on purpose. On `AgentToolDef` the same
@@ -70,7 +73,9 @@ export type CapabilityHandler = (data: any) => Promise<unknown> | unknown;
 export interface CapabilityDef extends ApprovalPolicy {
     execute: CapabilityHandler;
 }
+/** A capability as registered: a bare handler, which is treated as needing approval, or a {@link CapabilityDef} that says whether it does. */
 export type Capability = CapabilityHandler | CapabilityDef;
+/** The capabilities one end of a channel answers to, by name. Only names listed here run; anything else the peer asks for is refused. */
 export type Capabilities = Record<string, Capability>;
 export declare const isCapabilityDef: (capability: Capability) => capability is CapabilityDef;
 /**

package/dist/wirings/channel/channel-runner.d.ts

@@ -1,6 +1,28 @@
 import type { SessionService } from '../../services/user-session-service.js';
 import type { ChannelMeta, CoreChannel, RunChannelOptions, RunChannelParams } from './channel.types.js';
+/**
+ * Wires a realtime channel (a WebSocket, or a serverless equivalent) to a route.
+ *
+ * `onConnect` runs once when a client connects, `onDisconnect` once when it
+ * leaves, and each message goes to the `onMessageWiring` handler its routing key
+ * selects, or to `onMessage` when none matches. A channel requires a session
+ * unless it sets `auth: false`. The session is established on connect, by the
+ * `middleware` on the channel and the HTTP middleware registered for `'*'`
+ * (which runs on the upgrade), and every handler then sees it.
+ *
+ * Registration needs the metadata `pikku` generates for the channel. When none is
+ * found the wiring is skipped with a warning rather than throwing.
+ *
+ * @param channel - The channel's name, route, lifecycle and message handlers, and middleware.
+ *
+ * @example snippet: wireChannel
+ */
 export declare const wireChannel: <In, Channel extends string, ChannelConnect, ChannelDisconnect, ChannelFunctionMessage>(channel: CoreChannel<In, Channel, ChannelConnect, ChannelDisconnect, ChannelFunctionMessage>) => void;
+/**
+ * Matches a route to a wired channel and validates its opening data against the channel's input schema.
+ * @throws {NotFoundError} When no channel is wired at `route`.
+ * @internal
+ */
 export declare const openChannel: ({ route, coerceDataFromSchema, request, }: Pick<CoreChannel<unknown, string>, 'route'> & RunChannelParams<unknown> & {
     userSession: SessionService<any>;
 } & RunChannelOptions) => Promise<{

package/dist/wirings/channel/channel-runner.js

@@ -15,6 +15,23 @@ const registeredHandler = (handler) => {
         ? handler
         : candidate.func;
 };
+/**
+ * Wires a realtime channel (a WebSocket, or a serverless equivalent) to a route.
+ *
+ * `onConnect` runs once when a client connects, `onDisconnect` once when it
+ * leaves, and each message goes to the `onMessageWiring` handler its routing key
+ * selects, or to `onMessage` when none matches. A channel requires a session
+ * unless it sets `auth: false`. The session is established on connect, by the
+ * `middleware` on the channel and the HTTP middleware registered for `'*'`
+ * (which runs on the upgrade), and every handler then sees it.
+ *
+ * Registration needs the metadata `pikku` generates for the channel. When none is
+ * found the wiring is skipped with a warning rather than throwing.
+ *
+ * @param channel - The channel's name, route, lifecycle and message handlers, and middleware.
+ *
+ * @example snippet: wireChannel
+ */
 export const wireChannel = (channel) => {
     const channelsMeta = pikkuState(null, 'channel', 'meta');
     const channelMeta = channelsMeta[channel.name];
@@ -69,6 +86,11 @@ const getMatchingChannelConfig = (path) => {
         meta: channelMeta,
     };
 };
+/**
+ * Matches a route to a wired channel and validates its opening data against the channel's input schema.
+ * @throws {NotFoundError} When no channel is wired at `route`.
+ * @internal
+ */
 export const openChannel = async ({ route, coerceDataFromSchema = true, request, }) => {
     const singletonServices = getSingletonServices();
     const matchingChannel = getMatchingChannelConfig(route);

package/dist/wirings/channel/channel-store.d.ts

@@ -1,9 +1,17 @@
+/** A channel as a {@link ChannelStore} persists it between serverless invocations. */
 export type Channel<ChannelType = unknown, OpeningData = unknown> = {
     channelId: string;
     channelName: string;
     channelObject?: ChannelType;
     openingData?: OpeningData;
 };
+/**
+ * Persists open channels for serverless runtimes, where each connect, message and disconnect runs in a separate invocation.
+ *
+ * It keeps the channel's opening data, its state, and the `pikkuUserId` of the
+ * session established on connect. The session itself is not stored: each
+ * message reloads it from the `sessionStore` by that id.
+ */
 export declare abstract class ChannelStore<ChannelType = unknown, OpeningData = unknown, TypedChannel = Channel<ChannelType, OpeningData>> {
     abstract addChannel(channel: Channel<ChannelType, OpeningData>): Promise<void> | void;
     abstract removeChannels(channelId: string[]): Promise<void> | void;

package/dist/wirings/channel/channel-store.js

@@ -1,2 +1,9 @@
+/**
+ * Persists open channels for serverless runtimes, where each connect, message and disconnect runs in a separate invocation.
+ *
+ * It keeps the channel's opening data, its state, and the `pikkuUserId` of the
+ * session established on connect. The session itself is not stored: each
+ * message reloads it from the `sessionStore` by that id.
+ */
 export class ChannelStore {
 }