@pikku/core 0.12.143 → 0.12.144

package/dist/time-utils.js

@@ -6,18 +6,32 @@ const multipliers = {
     week: 60 * 60 * 24 * 7,
     year: Math.round(365.25 * 60 * 60 * 24),
 };
+/** Converts a {@link RelativeTimeInput} to milliseconds, rounded to the whole second. */
 export const getRelativeTimeOffset = ({ value, unit, }) => {
     return Math.round(value * multipliers[unit]) * 1000;
 };
+/** The `Date` that is `relativeTime` away from now. */
 export const getRelativeTimeOffsetFromNow = (relativeTime) => {
     return new Date(Date.now() + getRelativeTimeOffset(relativeTime));
 };
+/**
+ * Normalises a duration to milliseconds: a number is taken as milliseconds already,
+ * a string is parsed by {@link parseDurationString}.
+ *
+ * @throws Error when the string is not a recognised duration.
+ */
 export const getDurationInMilliseconds = (duration) => {
     if (typeof duration === 'number') {
         return duration;
     }
     return parseDurationString(duration);
 };
+/**
+ * Parses a duration such as `'500ms'`, `'5s'`, `'10min'`, `'1hour'`, `'2days'`,
+ * `'1week'` or `'1y'` into milliseconds. Whole numbers only, no spaces.
+ *
+ * @throws Error when the string does not match the format.
+ */
 export const parseDurationString = (duration) => {
     const match = duration.match(/^(\d+)(ms|milliseconds?|s|sec|seconds?|m|min|minutes?|h|hour|hours?|d|day|days?|w|week|weeks?|y|year|years?)$/);
     if (!match) {

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

@@ -45,6 +45,10 @@ import type { ScopeService } from '../services/scope-service.js';
 import type { FeatureFlagSource } from '../services/feature-flag-service.js';
 import type { AuditDurability, AuditLog, AuditService } from '../services/audit-service.js';
 import type { AnalyticsLog, AnalyticsIdentityResolver, AnalyticsService } from '../analytics/analytics.types.js';
+/**
+ * Every transport a function can be wired to; read off `wire.wireType` to see
+ * how the current invocation arrived.
+ */
 export type PikkuWiringTypes = 'http' | 'scheduler' | 'trigger' | 'channel' | 'rpc' | 'queue' | 'mcp' | 'cli' | 'workflow' | 'agent' | 'gateway';
 /**
  * Runtime pool tuning for the Postgres adapter. The connection string stays
@@ -74,6 +78,10 @@ export interface PostgresConfig {
      */
     prepare?: boolean;
 }
+/**
+ * The config every Pikku app's `Config` extends. `createConfig` returns it and
+ * it is handed to `createSingletonServices`.
+ */
 export type CoreConfig<Config extends Record<string, unknown> = {}> = {
     logLevel?: LogLevel;
     secrets?: {
@@ -84,6 +92,11 @@ export type CoreConfig<Config extends Record<string, unknown> = {}> = {
     webhook?: WebhookServiceConfig;
     postgres?: PostgresConfig;
 } & Config;
+/**
+ * The fields Pikku itself reads from a session. Extend it with your own
+ * `UserSession`; the runner only enforces `readonly` and `scopes`, the rest is
+ * carried for you.
+ */
 export interface CoreUserSession {
     /** Who the session belongs to, as your own system identifies them. Pikku only carries it. */
     userId?: string;
@@ -111,6 +124,12 @@ export interface AuthInstance {
     api: Record<string, any>;
     $context?: Promise<any>;
 }
+/**
+ * The services created once at startup and shared by every invocation. Your
+ * `SingletonServices` extends it; only `config`, `logger`, `variables` and
+ * `secrets` are required, every other service is opt-in and the features that
+ * need it fail with `MissingServiceError` or stay inert without it.
+ */
 export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
     schema?: SchemaService;
     jwt?: JWTService;
@@ -214,6 +233,13 @@ export type GetCredential<TCredentials = Record<string, unknown>> = string exten
     <K extends keyof TCredentials & string>(name: K): TCredentials[K] | null | Promise<TCredentials[K] | null>;
     <T = unknown>(name: string): T | null | Promise<T | null>;
 };
+/**
+ * The second argument of every Pikku function: what this invocation knows
+ * about how it was called. `rpc` and the credential readers are always
+ * present; each transport fills in its own key (`http`, `channel`, `queue`,
+ * `workflow`, …) and leaves the rest undefined, and `session` is typed as
+ * present only for functions that require one.
+ */
 export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boolean = false, UserSession extends CoreUserSession = CoreUserSession, TypedRPC extends PikkuRPC = PikkuRPC, IsChannel extends true | null = null, MCPTools extends string | never = never, TypedWorkflow extends PikkuWorkflowWire | never = PikkuWorkflowWire, TriggerOutput = unknown, TypedScenario extends PikkuScenarioWire<any> | never = PikkuScenarioWire<any>, TScenarioVirtualUsers extends ScenarioVirtualUsers = ScenarioVirtualUsers, TypedCredentials = Record<string, unknown>> = {
     /** Always present — lazily initialised on first access for every function invocation */
     rpc: TypedRPC;
@@ -261,7 +287,20 @@ export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boo
     trigger: PikkuTrigger<TriggerOutput>;
     gateway: PikkuGateway;
     session: HasInitialSession extends true ? UserSession : UserSession | undefined;
+    /**
+     * Sign the caller in as `session`: marks the session changed, so `authCookie`
+     * re-issues the cookie, and writes the session store under the session's
+     * `userId`. Means the same in middleware and in a function body. Await it.
+     */
     setSession: (session: UserSession) => Promise<void> | void;
+    /**
+     * Establish who the caller is for this invocation only — what auth
+     * middleware does with a credential it was handed. Does not mark the session
+     * changed and writes nothing, so no cookie is re-issued. The function body
+     * sees it as `session`; set it before the body starts.
+     */
+    setInitialSession: (session: UserSession) => void;
+    /** Sign the caller out: marks the session changed and clears the session store entry. */
     clearSession: () => Promise<void> | void;
     /** Fetch the latest session (may read from backing store) */
     getSession: () => Promise<UserSession> | UserSession | undefined;
@@ -297,21 +336,51 @@ export type PikkuRawWire = Omit<PikkuWire, 'rpc' | 'getCredential' | 'getCredent
      */
     abortScope?: AbortScope;
 };
+/**
+ * The services a function receives. Today the same as the singleton services;
+ * kept as its own name so function signatures do not depend on that.
+ */
 export type CoreServices<SingletonServices = CoreSingletonServices> = SingletonServices;
 /** Strips `secrets` from a services type. */
 export type SecretlessServices<Services> = Omit<Services, 'secrets'>;
 /** The constraint every function-, permission- and auth-facing type is bounded by. */
 export type CoreSecretlessSingletonServices<Config extends CoreConfig = CoreConfig> = SecretlessServices<CoreSingletonServices<Config>>;
+/**
+ * The per-invocation services: whatever `Services` adds on top of the singleton
+ * services, minus the session.
+ */
 export type WireServices<SingletonServices extends CoreSingletonServices = CoreSingletonServices, Services = CoreServices<SingletonServices>> = Omit<Services, keyof SingletonServices | 'session'>;
+/**
+ * Your `createSingletonServices` factory: builds the shared services once from
+ * the config. `existingServices` carries services a host has already created,
+ * which the factory should reuse rather than recreate.
+ */
 export type CreateSingletonServices<Config extends CoreConfig, SingletonServices extends CoreSingletonServices> = (config: Config, existingServices?: Partial<SingletonServices>) => Promise<SingletonServices>;
+/**
+ * Your `createWireServices` factory: builds the services scoped to one
+ * invocation. A returned service with a `close()` is closed by the runner when
+ * the invocation ends.
+ */
 export type CreateWireServices<SingletonServices extends CoreSingletonServices = CoreSingletonServices, Services extends CoreServices<SingletonServices> = CoreServices<SingletonServices>, UserSession extends CoreUserSession = CoreUserSession> = (services: SingletonServices, wire: PikkuRawWire) => Promise<WireServices<Services, SingletonServices>>;
+/**
+ * Your `createConfig` factory: builds the app config, typically reading from
+ * the `VariablesService`.
+ */
 export type CreateConfig<Config extends CoreConfig, RemainingArgs extends any[] = unknown[]> = (variables?: VariablesService, ...args: RemainingArgs) => Promise<Config>;
+/**
+ * Hooks a server runtime calls around starting and stopping, with the
+ * singleton services.
+ */
 export type ServerLifecycle<SingletonServices extends CoreSingletonServices = CoreSingletonServices> = {
     beforeStart?: (services: SingletonServices) => void | Promise<void>;
     afterStart?: (services: SingletonServices) => void | Promise<void>;
     beforeStop?: (services: SingletonServices) => void | Promise<void>;
     afterStop?: (services: SingletonServices) => void | Promise<void>;
 };
+/**
+ * The metadata fields shared by every wiring's generated meta entry.
+ * @internal
+ */
 export type CommonWireMeta = {
     pikkuFuncId: string;
     packageName?: string;
@@ -333,9 +402,14 @@ export type CommonWireMeta = {
  * addon (reader) and the console UI (renderer).
  */
 export type SecuritySeverity = 'critical' | 'high' | 'moderate' | 'low' | 'info';
+/** How far behind the latest release an outdated dependency is. */
 export type SecurityUpdateLevel = 'major' | 'minor' | 'patch' | 'unknown';
 /** `dev` = only reachable through devDependencies or build tooling, so never shipped. */
 export type SecurityDependencyType = 'prod' | 'dev';
+/**
+ * One advisory affecting an installed package, as written to
+ * `.pikku/audit.json`.
+ */
 export interface SecurityAuditIssue {
     package: string;
     severity: SecuritySeverity;
@@ -348,6 +422,7 @@ export interface SecurityAuditIssue {
     recommendedVersion: string | null;
     dependencyType?: SecurityDependencyType;
 }
+/** One dependency with a newer release available. */
 export interface SecurityAuditUpdate {
     package: string;
     current: string;
@@ -355,6 +430,7 @@ export interface SecurityAuditUpdate {
     level: SecurityUpdateLevel;
     dependencyType?: SecurityDependencyType;
 }
+/** Counts of the issues by severity and the updates by level. */
 export interface SecurityAuditSummary {
     totalIssues: number;
     critical: number;
@@ -366,6 +442,10 @@ export interface SecurityAuditSummary {
     minor: number;
     patch: number;
 }
+/**
+ * The whole of `.pikku/audit.json`, written by `pikku audit` and read by the
+ * console.
+ */
 export interface SecurityAuditReport {
     schemaVersion: number;
     tool: string;

package/dist/types/state.types.d.ts

@@ -19,6 +19,10 @@ import type { CreateConfig, CreateSingletonServices, CreateWireServices, CoreCon
 import type { FunctionsMeta } from '../function/function-meta.types.js';
 import type { CorePikkuMiddleware, CorePikkuMiddlewareGroup } from '../middleware/middleware.types.js';
 import type { CorePikkuChannelMiddleware } from '../wirings/channel/channel.types.js';
+/**
+ * The shape of one package's registry, as read and written by `pikkuState`.
+ * @internal
+ */
 export interface PikkuPackageState {
     function: {
         meta: FunctionsMeta;

package/dist/utils/hmac.d.ts

@@ -9,8 +9,11 @@
  * (the lengths of the two values are not secret).
  */
 export declare function timingSafeStringEqual(a: string, b: string): boolean;
+/** The bytes an HMAC is computed over: a string is UTF-8 encoded, so pass the raw request body, not re-serialised JSON. */
 export type WebhookPayload = string | Uint8Array;
+/** The hash an HMAC helper signs with. `sha1` exists only for providers that still sign with it. */
 export type HmacAlgorithm = 'sha1' | 'sha256' | 'sha512';
+/** How the signing secret string is turned into key bytes: as UTF-8 text, or decoded from hex or base64. */
 export type SecretEncoding = 'utf8' | 'hex' | 'base64';
 /**
  * HMAC-SHA256 of a payload, hex-encoded. Senders wrap this in their own scheme

package/dist/utils/safe-fetch.d.ts

@@ -16,6 +16,7 @@ export type HostResolver = (hostname: string) => Promise<string[]>;
  * `nodeHostResolver` from `@pikku/core/node-host-resolver` at startup.
  */
 export declare function setDefaultHostResolver(resolver: HostResolver | undefined): void;
+/** Restrictions {@link safeFetch} and {@link assertFetchableUrl} apply to each URL they visit. */
 export interface SafeFetchOptions {
     /**
      * When set, the host of every hop must appear in this allowlist. When omitted,
@@ -31,6 +32,19 @@ export interface SafeFetchOptions {
      */
     resolveHost?: HostResolver | null;
 }
+/**
+ * Synchronous SSRF guard for a single URL: only `http:`/`https:` is accepted, and
+ * the host must be in `allowedHosts` when given, or else must not be a private,
+ * loopback or link-local literal ({@link isPrivateHost}).
+ *
+ * It does not resolve DNS, so a public name pointing at an internal address
+ * passes; {@link safeFetch} adds that check per hop.
+ *
+ * @param url - The URL to check.
+ * @param options - Only `allowedHosts` is read here.
+ * @returns The parsed URL.
+ * @throws TypeError for an unparseable URL; Error for a refused scheme or host.
+ */
 export declare function assertFetchableUrl(url: string, options?: SafeFetchOptions): URL;
 /**
  * `fetch` with SSRF protection on the initial URL and every redirect hop.

package/dist/utils/safe-fetch.js

@@ -212,6 +212,19 @@ async function assertResolvedHostAllowed(hostname, options) {
         }
     }
 }
+/**
+ * Synchronous SSRF guard for a single URL: only `http:`/`https:` is accepted, and
+ * the host must be in `allowedHosts` when given, or else must not be a private,
+ * loopback or link-local literal ({@link isPrivateHost}).
+ *
+ * It does not resolve DNS, so a public name pointing at an internal address
+ * passes; {@link safeFetch} adds that check per hop.
+ *
+ * @param url - The URL to check.
+ * @param options - Only `allowedHosts` is read here.
+ * @returns The parsed URL.
+ * @throws TypeError for an unparseable URL; Error for a refused scheme or host.
+ */
 export function assertFetchableUrl(url, options = {}) {
     const parsed = new URL(url);
     if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {

package/dist/utils/stable-stringify.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `JSON.stringify` with object keys sorted, so property order cannot change
+ * the output. Follows `JSON.stringify` for everything else: `toJSON` is
+ * honoured, object properties whose value JSON cannot represent (`undefined`,
+ * functions, symbols) are omitted, the same values become `null` inside
+ * arrays, and such a value at the top level returns `undefined`.
+ *
+ * Keys are emitted in plain string order, including integer-like keys that a
+ * JavaScript object would otherwise move to the front.
+ */
+export declare const stableStringify: (value: unknown) => string | undefined;

package/dist/utils/stable-stringify.js

@@ -0,0 +1,33 @@
+/**
+ * `JSON.stringify` with object keys sorted, so property order cannot change
+ * the output. Follows `JSON.stringify` for everything else: `toJSON` is
+ * honoured, object properties whose value JSON cannot represent (`undefined`,
+ * functions, symbols) are omitted, the same values become `null` inside
+ * arrays, and such a value at the top level returns `undefined`.
+ *
+ * Keys are emitted in plain string order, including integer-like keys that a
+ * JavaScript object would otherwise move to the front.
+ */
+export const stableStringify = (value) => serialize(value, '');
+const serialize = (value, key) => {
+    if (value !== null &&
+        typeof value === 'object' &&
+        typeof value.toJSON === 'function') {
+        value = value.toJSON(key);
+    }
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((item, i) => serialize(item, String(i)) ?? 'null').join(',')}]`;
+    }
+    const record = value;
+    const entries = [];
+    for (const k of Object.keys(record).sort()) {
+        const serialized = serialize(record[k], k);
+        if (serialized !== undefined) {
+            entries.push(`${JSON.stringify(k)}:${serialized}`);
+        }
+    }
+    return `{${entries.join(',')}}`;
+};

package/dist/utils.d.ts

@@ -1,8 +1,25 @@
 import type { Logger } from './services/logger.js';
 import type { WireServices } from './types/core.types.js';
+/**
+ * Calls `close()` on every wire service that has one, in parallel, at the end of a
+ * wiring. A failing `close` is logged and does not stop the others.
+ */
 export declare const closeWireServices: (logger: Logger, wireServices: WireServices) => Promise<void>;
+/**
+ * A process-unique id (random 8-character prefix plus a counter). Not
+ * unpredictable, so never use it as a token or secret.
+ */
 export declare const createWeakUID: () => string;
+/**
+ * Whether a response body needs `JSON.stringify`: false for strings and binary
+ * (`ArrayBuffer` and typed arrays), which are sent as they are.
+ */
 export declare const isSerializable: (data: any) => boolean;
+/**
+ * Looks up the groups for a hierarchical tag and each of its `:`-separated
+ * ancestors, most specific first: `'admin:users'` yields the groups for
+ * `'admin:users'` then `'admin'`.
+ */
 export declare const getTagGroups: <T>(tagGroups: Record<string, T>, tag: string) => T[];
 /**
  * `JSON.parse` of text or UTF-8 bytes, refusing anything that is not JSON with
@@ -11,15 +28,26 @@ export declare const getTagGroups: <T>(tagGroups: Record<string, T>, tag: string
  * @example snippet: pikkuWebhookReceive
  */
 export declare const parseJson: <T = any>(input: string | Uint8Array) => T;
+/**
+ * Returns a frozen copy of the array with duplicates removed, keeping first-seen
+ * order. Used for middleware and permission lists, so the same function is never
+ * run twice.
+ */
 export declare const freezeDedupe: <T>(arr?: readonly T[] | T[] | undefined) => readonly T[];
 export { stopSingletonServices, pikkuServerLifecycle } from './lifecycle.js';
+/** `T` with the keys `K` made required. */
 export type MakeRequired<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
+/** A JSON scalar; `undefined` is included because it is dropped on serialisation rather than rejected. */
 export type JSONPrimitive = string | number | boolean | null | undefined;
+/** Any value that round-trips through JSON. */
 export type JSONValue = JSONPrimitive | JSONValue[] | {
     [key: string]: JSONValue;
 };
+/** `T` with the keys `K` made required and every other key unchanged. */
 export type PickRequired<T, K extends keyof T> = T & Required<Pick<T, K>>;
+/** `T` with every key optional except `K`. */
 export type PickOptional<T, K extends keyof T> = Partial<T> & Pick<T, K>;
+/** `T` with every key optional, but at least one of them present. */
 export type RequireAtLeastOne<T> = {
     [K in keyof T]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<keyof T, K>>>;
 }[keyof T];

package/dist/utils.js

@@ -1,4 +1,8 @@
 import { BadRequestError } from './errors/errors.js';
+/**
+ * Calls `close()` on every wire service that has one, in parallel, at the end of a
+ * wiring. A failing `close` is logged and does not stop the others.
+ */
 export const closeWireServices = async (logger, wireServices) => {
     await Promise.all(Object.values(wireServices).map(async (service) => {
         if (service?.close) {
@@ -13,10 +17,18 @@ export const closeWireServices = async (logger, wireServices) => {
 };
 let _uidPrefix;
 let _uidCounter = 0;
+/**
+ * A process-unique id (random 8-character prefix plus a counter). Not
+ * unpredictable, so never use it as a token or secret.
+ */
 export const createWeakUID = () => {
     _uidPrefix ??= globalThis.crypto.randomUUID().slice(0, 8);
     return `${_uidPrefix}-${++_uidCounter}`;
 };
+/**
+ * Whether a response body needs `JSON.stringify`: false for strings and binary
+ * (`ArrayBuffer` and typed arrays), which are sent as they are.
+ */
 export const isSerializable = (data) => {
     return !(typeof data === 'string' ||
         data instanceof ArrayBuffer ||
@@ -29,6 +41,11 @@ export const isSerializable = (data) => {
         data instanceof Float32Array ||
         data instanceof Float64Array);
 };
+/**
+ * Looks up the groups for a hierarchical tag and each of its `:`-separated
+ * ancestors, most specific first: `'admin:users'` yields the groups for
+ * `'admin:users'` then `'admin'`.
+ */
 export const getTagGroups = (tagGroups, tag) => {
     const results = [];
     const exact = tagGroups[tag];
@@ -60,6 +77,11 @@ export const parseJson = (input) => {
     }
 };
 const EMPTY_ARRAY = Object.freeze([]);
+/**
+ * Returns a frozen copy of the array with duplicates removed, keeping first-seen
+ * order. Used for middleware and permission lists, so the same function is never
+ * run twice.
+ */
 export const freezeDedupe = (arr) => {
     if (!arr || arr.length === 0)
         return EMPTY_ARRAY;

package/dist/version.d.ts

@@ -1,6 +1,13 @@
+/** The id of one version of a function: `name@v2`. */
 export declare function formatVersionedId(baseName: string, version: number): string;
+/**
+ * Splits `name@vN` into its base name and version. An id with no `@v` suffix,
+ * or whose suffix is not a positive integer, is returned whole with `version:
+ * null`.
+ */
 export declare function parseVersionedId(id: string): {
     baseName: string;
     version: number | null;
 };
+/** Whether `id` carries a valid `@vN` version suffix. */
 export declare function isVersionedId(id: string): boolean;

package/dist/version.js

@@ -1,7 +1,13 @@
 const VERSION_SEPARATOR = '@v';
+/** The id of one version of a function: `name@v2`. */
 export function formatVersionedId(baseName, version) {
     return `${baseName}${VERSION_SEPARATOR}${version}`;
 }
+/**
+ * Splits `name@vN` into its base name and version. An id with no `@v` suffix,
+ * or whose suffix is not a positive integer, is returned whole with `version:
+ * null`.
+ */
 export function parseVersionedId(id) {
     const idx = id.lastIndexOf(VERSION_SEPARATOR);
     if (idx === -1) {
@@ -14,6 +20,7 @@ export function parseVersionedId(id) {
     }
     return { baseName: id.slice(0, idx), version };
 }
+/** Whether `id` carries a valid `@vN` version suffix. */
 export function isVersionedId(id) {
     return parseVersionedId(id).version !== null;
 }

package/dist/wirings/addon/define-screens.d.ts

@@ -18,7 +18,9 @@ export type AddonAppScreen = AddonScreenBase & {
     /** Directory of the built program, relative to the addon package. */
     app: string;
 };
+/** One screen an addon ships: either a component the host renders or a static app it serves in a sandboxed iframe. */
 export type AddonScreen = AddonComponentScreen | AddonAppScreen;
+/** The manifest passed to `defineScreens`: the addon's title, optional icon and its screens. */
 export type ScreensManifest = {
     title: string;
     icon?: string;

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

@@ -1,6 +1,10 @@
 import type { CoreServices, PikkuRawWire } from '../../types/core.types.js';
 import { PikkuError } from '../../errors/error-handler.js';
 import { type SecretValue } from '../../classification/secret-value.js';
+/**
+ * Where the bearer token for a remote addon call comes from: a per-user credential, a deployment
+ * secret, or a resolver function. `credentialId` needs a wire with credential access.
+ */
 export type RemoteAddonAuthBinding = {
     credentialId: string;
 } | {
@@ -8,6 +12,11 @@ export type RemoteAddonAuthBinding = {
 } | {
     resolve: (services: CoreServices, wire: PikkuRawWire) => string | SecretValue<string> | Promise<string | SecretValue<string>>;
 };
+/**
+ * Thrown (401) when a remote addon's token cannot be resolved: the binding needs credential
+ * access the wire lacks, or it resolved to an empty value. The call is refused rather than sent
+ * unauthenticated.
+ */
 export declare class RemoteAddonAuthError extends PikkuError {
     readonly namespace: string;
     constructor(namespace: string, detail: string);

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

@@ -1,5 +1,10 @@
 import { PikkuError, addError } from '../../errors/error-handler.js';
 import { isSecretValue, } from '../../classification/secret-value.js';
+/**
+ * Thrown (401) when a remote addon's token cannot be resolved: the binding needs credential
+ * access the wire lacks, or it resolved to an empty value. The call is refused rather than sent
+ * unauthenticated.
+ */
 export class RemoteAddonAuthError extends PikkuError {
     namespace;
     constructor(namespace, detail) {

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

@@ -1,6 +1,10 @@
 import type { CredentialOverrides } from '../credential/credential-overrides.js';
 import type { CorePikkuMiddleware } from '../../middleware/middleware.types.js';
 import type { AddonInstance } from './addon-runner.js';
+/**
+ * Options for `wireAddon`: the instance name, its package, and what the consuming app grants it
+ * (auth, scopes, exposed functions, secret/credential/content access and overrides).
+ */
 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;

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

@@ -7,6 +7,7 @@ export type RemoteAddonAuth = {
 } | {
     resolve: (services: CoreServices, wire: PikkuWire) => string | Promise<string>;
 };
+/** Options for `wireRemoteAddon`: the namespace, the contract package, where the addon is deployed and how calls authenticate. */
 export type WireRemoteAddonConfig = {
     /** Consumer-facing namespace, e.g. `registry` → `rpc('registry:getOpenApi')` */
     name: string;

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

@@ -49,12 +49,12 @@ type AGUIEvent = {
     type: 'RUN_FINISHED';
     threadId: string;
     runId: string;
-    model?: string;
-    usage?: {
-        promptTokens: number;
-        completionTokens: number;
+    usage?: Array<{
+        model?: string;
+        inputTokens: number;
+        outputTokens: number;
         totalTokens: number;
-    };
+    }>;
 } | {
     type: 'RUN_ERROR';
     message: string;
@@ -76,4 +76,13 @@ export type AGUIChannelOptions = {
     runId?: string;
     getRunId?: () => string | undefined;
 };
+/**
+ * Wraps an agent stream channel so the events written to it go out as AG-UI protocol events
+ * (`RUN_STARTED`, `TEXT_MESSAGE_CONTENT`, `TOOL_CALL_START`, ...) instead of Pikku's own
+ * `AgentStreamEvent`s. `rpc.agent.stream` and `rpc.agent.resume` apply it for you.
+ *
+ * @param inner - The channel the AG-UI events are sent on.
+ * @param options - Thread and run ids to stamp on the events; generated when absent.
+ * @returns A channel that accepts `AgentStreamEvent`s.
+ */
 export declare function wrapChannelWithAGUI(inner: AgentStreamChannel, options?: AGUIChannelOptions): AgentStreamChannel;

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

@@ -9,6 +9,15 @@ function resultToString(result) {
         return String(result);
     }
 }
+/**
+ * Wraps an agent stream channel so the events written to it go out as AG-UI protocol events
+ * (`RUN_STARTED`, `TEXT_MESSAGE_CONTENT`, `TOOL_CALL_START`, ...) instead of Pikku's own
+ * `AgentStreamEvent`s. `rpc.agent.stream` and `rpc.agent.resume` apply it for you.
+ *
+ * @param inner - The channel the AG-UI events are sent on.
+ * @param options - Thread and run ids to stamp on the events; generated when absent.
+ * @returns A channel that accepts `AgentStreamEvent`s.
+ */
 export function wrapChannelWithAGUI(inner, options) {
     const threadId = options?.threadId ?? randomUUID();
     let runId = options?.runId ?? null;
@@ -86,14 +95,16 @@ export function wrapChannelWithAGUI(inner, options) {
             type: 'RUN_FINISHED',
             threadId,
             runId: resolveRunId(),
-            ...(usageModel ? { model: usageModel } : {}),
             ...(sawUsage
                 ? {
-                    usage: {
-                        promptTokens: usageTotals.input,
-                        completionTokens: usageTotals.output,
-                        totalTokens: usageTotals.input + usageTotals.output,
-                    },
+                    usage: [
+                        {
+                            ...(usageModel ? { model: usageModel } : {}),
+                            inputTokens: usageTotals.input,
+                            outputTokens: usageTotals.output,
+                            totalTokens: usageTotals.input + usageTotals.output,
+                        },
+                    ],
                 }
                 : {}),
         });