@pikku/core 0.12.142 → 0.12.144

package/dist/wirings/trigger/webhook-source.types.d.ts

@@ -1,7 +1,7 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { CorePikkuFunctionConfig } from '../../function/functions.types.js';
 import type { HmacAlgorithm, SecretEncoding } from '../../utils/hmac.js';
-export declare const PIKKU_INCOMING_WEBHOOK_QUEUE_NAME = "pikku-incoming-webhooks";
+export { PIKKU_INCOMING_WEBHOOK_QUEUE_NAME } from '../../services/incoming-webhook-queue.js';
 /** `github` → `githubWebhookSecret`, `microsoft-outlook` → `microsoftOutlookWebhookSecret`. */
 export declare const webhookSecretCredentialName: (source: string) => string;
 /** What every trigger source produces, whichever way it arrives. */
@@ -27,9 +27,11 @@ export type WebhookRequest = {
 export type WebhookReceiveResult = {
     events: TriggerEvent[];
 };
+/** The HTTP methods a webhook source can be mounted on. */
 export type WebhookSourceMethod = 'post' | 'put' | 'get' | 'head';
 /** Whatever `setup` wants back on the next deploy, for providers whose endpoints cannot be found by label. */
 export type WebhookSourceState = Record<string, unknown>;
+/** What a webhook source's `check` and `setup` steps are given. */
 export type WebhookLifecycleInput = {
     /** Always this deployment's own route: nothing can point it elsewhere. */
     url: string;
@@ -39,6 +41,7 @@ export type WebhookLifecycleInput = {
     events: string[];
     previous?: WebhookSourceState;
 };
+/** Whether the provider-side registration matches what this deployment needs. */
 export type WebhookCheckResult = {
     status: 'ok';
 } | {
@@ -47,6 +50,7 @@ export type WebhookCheckResult = {
     status: 'drifted';
     reason: string;
 };
+/** What `setup` did at the provider. */
 export type WebhookSetupResult = {
     status: 'created' | 'updated' | 'unchanged';
     state?: WebhookSourceState;
@@ -56,10 +60,12 @@ export type WebhookSetupResult = {
     status: 'manual';
     instructions: string;
 };
+/** What a webhook source's `teardown` step is given. */
 export type WebhookTeardownInput = {
     label: string;
     previous?: WebhookSourceState;
 };
+/** Whether `teardown` removed a registration or found none. */
 export type WebhookTeardownResult = {
     status: 'deleted' | 'absent';
 };
@@ -98,6 +104,7 @@ export type WebhookVerify<Services = any> = {
 type SourceFunction<In, Out> = CorePikkuFunctionConfig<any, any> & {
     func: (services: any, data: In, wire: any) => Promise<Out>;
 };
+/** What `wireTriggerWebhookSource` takes. */
 export type CoreTriggerWebhookSource<Events extends Record<string, StandardSchemaV1> = Record<string, StandardSchemaV1>> = {
     /** Triggers subscribe to `<name>:<event>`. Unique across every kind of trigger source. */
     name: string;
@@ -129,6 +136,9 @@ export type CoreTriggerWebhookSource<Events extends Record<string, StandardSchem
     setup?: SourceFunction<WebhookLifecycleInput, WebhookSetupResult>;
     teardown?: SourceFunction<WebhookTeardownInput, WebhookTeardownResult>;
 };
+/**
+ * Generated metadata for one webhook source: its route and the function ids of its lifecycle steps.
+ */
 export type WebhookSourceMeta = {
     name: string;
     method: WebhookSourceMethod | WebhookSourceMethod[];
@@ -139,6 +149,7 @@ export type WebhookSourceMeta = {
     setup?: string;
     teardown?: string;
 };
+/** Generated metadata for every webhook source, keyed by name. */
 export type WebhookSourcesMeta = Record<string, WebhookSourceMeta>;
 /** One queued event on its way to its trigger. */
 export type WebhookSourceJob = {
@@ -147,4 +158,3 @@ export type WebhookSourceJob = {
     /** Present when a store-backed service recorded the receipt. */
     receiptId?: string;
 };
-export {};

package/dist/wirings/trigger/webhook-source.types.js

@@ -1,3 +1,3 @@
-export const PIKKU_INCOMING_WEBHOOK_QUEUE_NAME = 'pikku-incoming-webhooks';
+export { PIKKU_INCOMING_WEBHOOK_QUEUE_NAME } from '../../services/incoming-webhook-queue.js';
 /** `github` → `githubWebhookSecret`, `microsoft-outlook` → `microsoftOutlookWebhookSecret`. */
 export const webhookSecretCredentialName = (source) => `${source.replace(/[-_]+([a-z0-9])/gi, (_, c) => c.toUpperCase())}WebhookSecret`;

package/dist/wirings/variable/validate-variable-definitions.d.ts

@@ -1,4 +1,11 @@
 import type { VariableDefinitions, VariableDefinitionsMeta } from './variable.types.js';
 import type { SchemaRefLike } from '../../types/core.types.js';
 export type { SchemaRefLike };
+/**
+ * Merges the variable declarations the inspector found into meta keyed by name.
+ * Declarations that share a `variableId` must use the same schema.
+ *
+ * @throws Error when two declarations of one `variableId` disagree on schema.
+ * @internal Called by the CLI when generating meta.
+ */
 export declare function validateAndBuildVariableDefinitionsMeta(definitions: VariableDefinitions, schemaLookup: Map<string, SchemaRefLike>): VariableDefinitionsMeta;

package/dist/wirings/variable/validate-variable-definitions.js

@@ -1,3 +1,10 @@
+/**
+ * Merges the variable declarations the inspector found into meta keyed by name.
+ * Declarations that share a `variableId` must use the same schema.
+ *
+ * @throws Error when two declarations of one `variableId` disagree on schema.
+ * @internal Called by the CLI when generating meta.
+ */
 export function validateAndBuildVariableDefinitionsMeta(definitions, schemaLookup) {
     const meta = {};
     const variableIdToDefinition = new Map();

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

@@ -1,3 +1,7 @@
+/**
+ * The declaration {@link defineVariable} takes: a non-secret setting read from the
+ * environment. Anything sensitive belongs in {@link defineSecret} instead.
+ */
 export type CoreVariable<T = unknown> = {
     /** How the variable is asked for in code. Generated into `VariablesMap`, so it is what `variables.get` autocompletes. */
     name: string;
@@ -14,6 +18,7 @@ export type CoreVariable<T = unknown> = {
     /** Where to go to work out what to set this to. */
     docsUrl?: string;
 };
+/** A variable declaration as recorded in generated meta, with the schema replaced by its name. */
 export type VariableDefinitionMeta = {
     name: string;
     displayName: string;
@@ -24,7 +29,9 @@ export type VariableDefinitionMeta = {
     docsUrl?: string;
     sourceFile?: string;
 };
+/** Variable declarations collected by the CLI, keyed by name. */
 export type VariableDefinitionsMeta = Record<string, VariableDefinitionMeta>;
+/** Variable declarations as the inspector found them, before de-duplication. */
 export type VariableDefinitions = VariableDefinitionMeta[];
 /**
  * Declares an environment variable this project needs, with the shape of its

package/dist/wirings/virtual-user/conversation/conversation.types.d.ts

@@ -1,4 +1,7 @@
 export type ConversationApprovalPolicy = 'in-virtual-user' | 'always' | 'never';
+/**
+ * What a scenario asks for when a virtual user holds a conversation with one of the app's agents.
+ */
 export interface ConverseOptions<TAgentName extends string = string> {
     agent: TAgentName;
     /** What the virtual user is trying to get the agent to accomplish. */
@@ -9,6 +12,7 @@ export interface ConverseOptions<TAgentName extends string = string> {
     model?: string;
     maxTurns?: number;
 }
+/** The virtual user's judgement of a conversation, with the transcript it judged. */
 export interface ConversationVerdict {
     passed: boolean;
     reasoning: string;
@@ -26,6 +30,7 @@ export interface TargetAgentReply {
     status?: 'completed' | 'suspended';
     pendingApprovals?: TargetPendingApproval[];
 }
+/** Transport to the agent under test: sends a message, and answers its tool-approval requests. */
 export interface TargetAgentDriver {
     run(message: string): Promise<TargetAgentReply>;
     approve(runId: string, decisions: {

package/dist/wirings/virtual-user/conversation/run-conversation.d.ts

@@ -3,6 +3,7 @@ import type { ResolvedVirtualUser } from '../../../services/virtual-users-servic
 import type { AgentRunnerParams, AgentStepResult } from '../../../services/agent-runner-service.js';
 /** The LLM call the virtual user uses for its own turns/decisions/evaluation. */
 export type VirtualUserLLM = (params: AgentRunnerParams) => Promise<AgentStepResult>;
+/** What `runConversation` needs to play one virtual user against one agent. */
 export interface RunConversationParams {
     /** The person being played — name, job title, personality. */
     virtualUser: ResolvedVirtualUser;
@@ -27,6 +28,11 @@ export interface RunConversationParams {
     /** Display name of the target agent (transcript labelling). */
     agentName: string;
 }
+/** Read a structured `run` result, falling back to parsing JSON from text. */
+export declare function readObject<T>(result: {
+    object?: unknown;
+    text?: string;
+}): T | null;
 /**
  * Run a conversation: an LLM-driven virtual user holds a real multi-turn exchange
  * with a target agent (driven via the injected transport), answers the target's

package/dist/wirings/virtual-user/conversation/run-conversation.js

@@ -46,7 +46,7 @@ function msg(role, content) {
     };
 }
 /** Read a structured `run` result, falling back to parsing JSON from text. */
-function readObject(result) {
+export function readObject(result) {
     if (result.object && typeof result.object === 'object') {
         return result.object;
     }

package/dist/{services → wirings/virtual-user}/http-virtual-users.d.ts

@@ -1,6 +1,7 @@
-import type { ScenarioVirtualUser, ResolvedVirtualUser, ScenarioVirtualUsers, ScenarioInvokeOptions, ScenarioHttpResponse } from './virtual-users-service.js';
-import type { ConverseOptions, ConversationVerdict } from '../wirings/virtual-user/conversation/conversation.types.js';
-import { type VirtualUserSignIn } from './virtual-user-sign-in.js';
+import type { ScenarioVirtualUser, ResolvedVirtualUser, ScenarioVirtualUsers, ScenarioInvokeOptions, ScenarioHttpResponse } from '../../services/virtual-users-service.js';
+import type { ConverseOptions, ConversationVerdict } from './conversation/conversation.types.js';
+import { type VirtualUserSignIn } from '../../services/virtual-user-sign-in.js';
+/** How `createHttpVirtualUsers` reaches the target app and signs each virtual user in. */
 export interface HttpVirtualUsersConfig {
     /**
      * Base API URL of the target app, INCLUDING the HTTP prefix — e.g.

package/dist/{services → wirings/virtual-user}/http-virtual-users.js

@@ -1,9 +1,9 @@
-import { readScenarioHttpResponse } from './virtual-users-service.js';
-import { runConversation } from '../wirings/virtual-user/conversation/run-conversation.js';
-import { createCookieJar, } from './scenario-cookie-jar.js';
-import { authMount } from './virtual-user-sign-in.js';
-import { getSingletonServices } from '../pikku-state.js';
-import { AIProviderNotConfiguredError } from '../errors/errors.js';
+import { readScenarioHttpResponse } from '../../services/virtual-users-service.js';
+import { runConversation } from './conversation/run-conversation.js';
+import { createCookieJar, } from '../../services/scenario-cookie-jar.js';
+import { authMount, } from '../../services/virtual-user-sign-in.js';
+import { getSingletonServices } from '../../pikku-state.js';
+import { AIProviderNotConfiguredError } from '../../errors/errors.js';
 /**
  * Default HTTP-backed virtual user. Signs in lazily on first invoke, holds the
  * session cookies for its lifetime, and re-logs-in once on a 401 mid-run (long

package/dist/wirings/virtual-user/index.d.ts

@@ -49,7 +49,7 @@ export type { CoreVirtualUser, CoreVirtualUsers, VirtualUserAccountMeta, Virtual
  * imports services, which only a bundler could remove and an unbundled Node or
  * Lambda deploy would load outright.
  */
-export { HttpVirtualUser, createHttpVirtualUsers, type HttpVirtualUsersConfig, } from '../../services/http-virtual-users.js';
+export { HttpVirtualUser, createHttpVirtualUsers, type HttpVirtualUsersConfig, } from './http-virtual-users.js';
 export { statementSignIn, inProcessSignIn, authMount, type VirtualUserSignIn, type VirtualUserStatementMint, type StatementSignInOptions, type InProcessAuth, } from '../../services/virtual-user-sign-in.js';
 export { createCookieJar, type ScenarioCookieJar, } from '../../services/scenario-cookie-jar.js';
 export { postScenarioJson, readScenarioHttpResponse, } from '../../services/virtual-users-service.js';

package/dist/wirings/virtual-user/index.js

@@ -23,7 +23,7 @@ export { APP_SCOPE_ROOT, appScopeId, buildAppScopeDefinition, } from './virtual-
  * imports services, which only a bundler could remove and an unbundled Node or
  * Lambda deploy would load outright.
  */
-export { HttpVirtualUser, createHttpVirtualUsers, } from '../../services/http-virtual-users.js';
+export { HttpVirtualUser, createHttpVirtualUsers, } from './http-virtual-users.js';
 export { statementSignIn, inProcessSignIn, authMount, } from '../../services/virtual-user-sign-in.js';
 export { createCookieJar, } from '../../services/scenario-cookie-jar.js';
 export { postScenarioJson, readScenarioHttpResponse, } from '../../services/virtual-users-service.js';

package/dist/wirings/virtual-user/run-virtual-user.d.ts

@@ -1,5 +1,5 @@
 import type { ResolvedVirtualUser } from '../../services/virtual-users-service.js';
-import type { VirtualUserLLM } from './conversation/run-conversation.js';
+import { type VirtualUserLLM } from './conversation/run-conversation.js';
 import { type VirtualUserTuning } from './virtual-user-dispositions.js';
 import type { ApiCatalogueEntry, IntentSource, VirtualUserBudget, VirtualUserDisposition, VirtualUserFinding, VirtualUserRunResult, VirtualUserTally, VirtualUserTarget } from './virtual-user.types.js';
 /** What an app-specific oracle is shown about one call. */
@@ -13,6 +13,7 @@ export interface VirtualUserCallContext {
     step: number;
     disposition: VirtualUserDisposition;
 }
+/** Everything one autonomous virtual-user run is given. */
 export interface RunVirtualUserParams {
     /** The person being run — name, job title, personality, goals. */
     virtualUser: ResolvedVirtualUser;

package/dist/wirings/virtual-user/run-virtual-user.js

@@ -1,3 +1,4 @@
+import { readObject, } from './conversation/run-conversation.js';
 import { getDurationInMilliseconds } from '../../time-utils.js';
 import { catalogueIndex, catalogueLookup, describeEntry, isReadOnly, reachableCatalogue, renderCatalogue, } from './virtual-user-catalogue.js';
 import { dispositionProfile, } from './virtual-user-dispositions.js';
@@ -39,20 +40,6 @@ const msg = (role, content) => ({
     content,
     createdAt: new Date(),
 });
-/** Read a structured result, falling back to parsing JSON out of the text. */
-const readObject = (result) => {
-    if (result.object && typeof result.object === 'object')
-        return result.object;
-    if (result.text) {
-        try {
-            return JSON.parse(result.text);
-        }
-        catch {
-            return null;
-        }
-    }
-    return null;
-};
 /**
  * The arguments for a call, however the model chose to spell them.
  *

package/dist/wirings/virtual-user/virtual-user-declaration.types.d.ts

@@ -120,9 +120,11 @@ export type CoreVirtualUser = {
 };
 /** Virtual users to declare, keyed by id. */
 export type CoreVirtualUsers = Record<string, CoreVirtualUser>;
+/** Generated metadata for the account a virtual user signs in with. */
 export type VirtualUserAccountMeta = {
     provider?: string;
 };
+/** Generated metadata for one declared virtual user. */
 export type VirtualUserMeta = {
     /** The key it was declared under. */
     id: string;
@@ -146,5 +148,7 @@ export type VirtualUserMeta = {
     app?: string;
     sourceFile?: string;
 };
+/** Every declared virtual user, in declaration order. */
 export type VirtualUserDefinitions = VirtualUserMeta[];
+/** Generated metadata for every declared virtual user, keyed by id. */
 export type VirtualUsersMeta = Record<string, VirtualUserMeta>;

package/dist/wirings/virtual-user/virtual-user-scaffold.d.ts

@@ -3,7 +3,7 @@ import type { Logger } from '../../services/logger.js';
 import type { MetaService } from '../../services/meta-service.js';
 import type { VariablesService } from '../../services/variables-service.js';
 import type { AgentRunnerService } from '../../services/agent-runner-service.js';
-import type { HttpVirtualUsersConfig } from '../../services/http-virtual-users.js';
+import type { HttpVirtualUsersConfig } from './http-virtual-users.js';
 import type { ResolvedVirtualUser, ScenarioVirtualUsers } from '../../services/virtual-users-service.js';
 import type { VirtualUserEnvironment } from '../virtual-user/virtual-user-environments.js';
 import type { StepRecord, VirtualUserDisposition } from './virtual-user.types.js';
@@ -56,6 +56,11 @@ export declare const VIRTUAL_USER_VARIABLES: {
 export declare const runnableVirtualUser: (virtualUsers: ScaffoldVirtualUsers, virtualUserId: string) => ResolvedVirtualUser;
 /** The store, or the error naming the one to wire. */
 export declare const requireVirtualUserRunStore: (store: VirtualUserRunStore | undefined, reading?: boolean) => VirtualUserRunStore;
+/**
+ * The schedule store, or an error naming the one to wire.
+ *
+ * @throws Error when no `virtualUserScheduleStore` is wired.
+ */
 export declare const requireVirtualUserScheduleStore: (store: VirtualUserScheduleStore | undefined) => VirtualUserScheduleStore;
 /** What a caller asked for, before the declaration fills in what it left out. */
 export interface StartVirtualUserRunParams {
@@ -175,6 +180,9 @@ export declare const serializeVirtualUserSchedule: (schedule: VirtualUserSchedul
         goals: string[];
     };
 };
+/**
+ * What a request to create or change a virtual user's schedule carries. Omitted fields keep their current value.
+ */
 export interface WriteVirtualUserScheduleParams {
     store: VirtualUserScheduleStore | undefined;
     virtualUsers: ScaffoldVirtualUsers;
@@ -228,6 +236,7 @@ export declare const virtualUserScheduleRunInput: (schedule: VirtualUserSchedule
  * otherwise the only trace that a virtual user is still out there working.
  */
 export declare const logVirtualUserTick: (logger: Logger, result: VirtualUserTickResult) => void;
+/** What the scaffolded run worker needs to execute one recorded virtual-user run. */
 export interface ExecuteVirtualUserRunParams {
     runStore: VirtualUserRunStore | undefined;
     metaService: MetaService | undefined;

package/dist/wirings/virtual-user/virtual-user-scaffold.js

@@ -53,6 +53,11 @@ export const requireVirtualUserRunStore = (store, reading = false) => {
     }
     return store;
 };
+/**
+ * The schedule store, or an error naming the one to wire.
+ *
+ * @throws Error when no `virtualUserScheduleStore` is wired.
+ */
 export const requireVirtualUserScheduleStore = (store) => {
     if (!store) {
         throw new Error(MISSING_SCHEDULE_STORE);

package/dist/wirings/virtual-user/virtual-user-schedule.d.ts

@@ -21,6 +21,7 @@ export declare const STALE_RUN_AFTER_MS: number;
  * not the one that finds the most.
  */
 export declare const DEFAULT_MIN_INTERVAL_MS: number;
+/** The upper bound of the default cadence; see {@link DEFAULT_MIN_INTERVAL_MS}. */
 export declare const DEFAULT_MAX_INTERVAL_MS: number;
 /** Whether a row is the tick's business, for stores that cannot ask in a query. */
 export declare const isDue: (schedule: VirtualUserScheduleRecord, now: Date) => boolean;
@@ -33,6 +34,9 @@ export declare const isDue: (schedule: VirtualUserScheduleRecord, now: Date) =>
  */
 export declare const nextRunAt: (schedule: Pick<VirtualUserScheduleRecord, 'minIntervalMs' | 'maxIntervalMs'>, now: Date, random: () => number) => Date;
 export type VirtualUserSkipReason = 'in-flight' | 'dispatch-failed' | 'claimed-elsewhere';
+/**
+ * What one scheduling tick did: runs started, virtual users skipped and why, and stranded runs reaped.
+ */
 export interface VirtualUserTickResult {
     dispatched: {
         virtualUserId: string;
@@ -45,6 +49,7 @@ export interface VirtualUserTickResult {
     /** Runs found stranded at `running` and marked failed. */
     reaped: string[];
 }
+/** The stores a scheduling tick reads and the callback that starts a run. */
 export interface VirtualUserTickParams {
     schedules: VirtualUserScheduleStore;
     runs: VirtualUserRunStore;

package/dist/wirings/virtual-user/virtual-user-schedule.js

@@ -19,6 +19,7 @@ export const STALE_RUN_AFTER_MS = 2 * 60 * 60 * 1000;
  * not the one that finds the most.
  */
 export const DEFAULT_MIN_INTERVAL_MS = 6 * 60 * 60 * 1000;
+/** The upper bound of the default cadence; see {@link DEFAULT_MIN_INTERVAL_MS}. */
 export const DEFAULT_MAX_INTERVAL_MS = 24 * 60 * 60 * 1000;
 /** Whether a row is the tick's business, for stores that cannot ask in a query. */
 export const isDue = (schedule, now) => schedule.enabled && schedule.nextRunAt.getTime() <= now.getTime();

package/dist/wirings/virtual-user/virtual-user-target.d.ts

@@ -1,5 +1,6 @@
 import type { ScenarioVirtualUser } from '../../services/virtual-users-service.js';
 import type { VirtualUserTarget } from './virtual-user.types.js';
+/** Options for `virtualUserTarget`. */
 export interface VirtualUserTargetOptions {
     /** Model the virtual user uses for its side of a conversation with an agent. */
     model?: string;

package/dist/wirings/webhook/define-outgoing-webhook.d.ts

@@ -1,12 +1,14 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { Safe } from '../../classification/secret-value.js';
 import type { SendWebhookInput, SendWebhookResult, WebhookService } from '../../services/webhook-service.js';
+/** An outgoing webhook event your app sends: its event name, a title and description for docs, and the schema its payload must satisfy. */
 export type CoreOutgoingWebhook<Event extends string = string, Payload extends StandardSchemaV1 = StandardSchemaV1> = {
     event: Event;
     title: string;
     description?: string;
     payload: Payload;
 };
+/** Generated metadata for one outgoing webhook event. */
 export type OutgoingWebhookMeta = {
     event: string;
     title: string;
@@ -15,14 +17,32 @@ export type OutgoingWebhookMeta = {
     exportedName?: string;
     sourceFile?: string;
 };
+/** Generated metadata for every outgoing webhook event, keyed by event name. */
 export type OutgoingWebhooksMeta = Record<string, OutgoingWebhookMeta>;
+/** The payload type of an outgoing webhook, inferred from its schema's input type. */
 export type OutgoingWebhookPayloadOf<W> = W extends CoreOutgoingWebhook<string, infer S> ? StandardSchemaV1.InferInput<S> : never;
+/** Resolves the `data` a {@link TypedWebhookService.send} call must carry for its `event`: the event's payload when it is a known event, unconstrained otherwise. */
 export type OutgoingWebhookDataFor<TMap, Input> = Input extends {
     event: infer Event;
 } ? Event extends keyof TMap ? {
     data: Safe<TMap[Event]>;
 } : unknown : unknown;
+/**
+ * A `WebhookService` whose `send` checks `data` against the payload of the named event. An app's generated types supply the event-to-payload map.
+ *
+ * `data` must be {@link Safe}: a payload with a `SecretValue` anywhere in it
+ * fails to compile rather than being sent to a third party.
+ */
 export interface TypedWebhookService<TMap = Record<string, unknown>> extends Omit<WebhookService, 'send'> {
     send<const T extends SendWebhookInput>(input: Safe<T> & OutgoingWebhookDataFor<TMap, T>): Promise<SendWebhookResult>;
 }
+/**
+ * Declares an outgoing webhook event and its payload schema. Returns the definition unchanged.
+ *
+ * `pikku` collects these into the generated event-to-payload map, which is what
+ * makes `webhookService.send({ event, data })` type-check `data` against the
+ * schema. Defining an event does not send anything or register a URL.
+ *
+ * @param webhook - The event name, title, optional description, and payload schema.
+ */
 export declare const defineOutgoingWebhook: <const Event extends string, Payload extends StandardSchemaV1>(webhook: CoreOutgoingWebhook<Event, Payload>) => CoreOutgoingWebhook<Event, Payload>;

package/dist/wirings/webhook/define-outgoing-webhook.js

@@ -1 +1,10 @@
+/**
+ * Declares an outgoing webhook event and its payload schema. Returns the definition unchanged.
+ *
+ * `pikku` collects these into the generated event-to-payload map, which is what
+ * makes `webhookService.send({ event, data })` type-check `data` against the
+ * schema. Defining an event does not send anything or register a URL.
+ *
+ * @param webhook - The event name, title, optional description, and payload schema.
+ */
 export const defineOutgoingWebhook = (webhook) => webhook;

package/dist/wirings/workflow/dsl/workflow-dsl.types.d.ts

@@ -528,10 +528,7 @@ export interface WorkflowStepWire {
      */
     fromInvocationId?: string;
 }
-/**
- * Workflow wire object for DSL workflows
- * Provides workflow-specific capabilities to function execution
- */
+/** The outcome of the forward call a `compensate` function is undoing. */
 export type CompensatingFor<Out = unknown> = {
     ok: true;
     output: Out;
@@ -542,6 +539,10 @@ export type CompensatingFor<Out = unknown> = {
     error: SerializedError;
     stepName?: string;
 };
+/**
+ * Workflow wire object for DSL workflows
+ * Provides workflow-specific capabilities to function execution
+ */
 export interface PikkuWorkflowWire {
     /**
      * Set only while a function's `compensate` is running: the outcome of the
@@ -583,6 +584,9 @@ export interface PikkuWorkflowWire {
  * context would reject every wire whose scenario output differs from it.
  */
 export type ScenarioContext<Out = unknown> = 0 extends 1 & Out ? any : Out extends object ? Partial<Out> : Record<string, unknown>;
+/**
+ * The workflow wire a scenario body receives: every workflow step, plus the expectation steps and the shared `context`.
+ */
 export interface PikkuScenarioWire<Out = unknown> extends PikkuWorkflowWire {
     /**
      * Scratch the body writes and the `before`/`after` hooks read. A hook is a

package/dist/wirings/workflow/dsl/workflow-runner.d.ts

@@ -1 +1,8 @@
+/**
+ * Registers a workflow under its generated name. Called by generated code; an
+ * app declares workflows with `pikkuWorkflowFunc` and its relatives instead.
+ * Skipped with a warning when no metadata was generated for the name.
+ *
+ * @internal
+ */
 export declare const addWorkflow: (workflowName: string, workflowFunc: any, packageName?: string | null) => void;

package/dist/wirings/workflow/dsl/workflow-runner.js

@@ -1,5 +1,12 @@
 import { pikkuState } from '../../../pikku-state.js';
 import { addFunction } from '../../../function/function-runner.js';
+/**
+ * Registers a workflow under its generated name. Called by generated code; an
+ * app declares workflows with `pikkuWorkflowFunc` and its relatives instead.
+ * Skipped with a warning when no metadata was generated for the name.
+ *
+ * @internal
+ */
 export const addWorkflow = (workflowName, workflowFunc, packageName = null) => {
     const meta = pikkuState(packageName, 'workflows', 'meta');
     const workflowMeta = meta[workflowName];

package/dist/wirings/workflow/feature.d.ts

@@ -1,6 +1,18 @@
 import type { CoreWorkflow } from './workflow.types.js';
 import type { CoreFeature, FeaturePlanEntry } from './scenario.types.js';
+/**
+ * Registers a scenario feature. Called by generated code for each `pikkuFeature`.
+ *
+ * @internal
+ */
 export declare const addFeature: (featureId: string, feature: CoreFeature, packageName?: string | null) => void;
+/**
+ * Matches each feature's scenarios to the workflow names they are registered
+ * under, merging feature and scenario tags. Entries that name a scenario no
+ * workflow registration holds come back in `unresolved`.
+ *
+ * @internal
+ */
 export declare const resolveFeatureScenarios: (features: Map<string, CoreFeature>, registrations: Map<string, CoreWorkflow>) => {
     entries: FeaturePlanEntry[];
     unresolved: Array<{

package/dist/wirings/workflow/feature.js

@@ -1,7 +1,19 @@
 import { pikkuState } from '../../pikku-state.js';
+/**
+ * Registers a scenario feature. Called by generated code for each `pikkuFeature`.
+ *
+ * @internal
+ */
 export const addFeature = (featureId, feature, packageName = null) => {
     pikkuState(packageName, 'workflows', 'features').set(featureId, feature);
 };
+/**
+ * Matches each feature's scenarios to the workflow names they are registered
+ * under, merging feature and scenario tags. Entries that name a scenario no
+ * workflow registration holds come back in `unresolved`.
+ *
+ * @internal
+ */
 export const resolveFeatureScenarios = (features, registrations) => {
     const nameByConfig = new Map();
     for (const [name, registration] of registrations) {

package/dist/wirings/workflow/graph/graph-node.d.ts

@@ -15,6 +15,11 @@ export type TypedRef<T> = RefValue & {
 type InputWithRefs<T> = {
     [K in keyof T]: T[K] | TypedRef<T[K]>;
 };
+/**
+ * Builds a typed graph-node map for a set of RPCs: given a node-id → RPC-name
+ * map and per-node settings, returns the {@link GraphNodeConfig} for every node,
+ * with refs typed against each RPC's input and output.
+ */
 export declare function createGraph<RPCMap extends Record<string, RPCHandler>>(): <const FuncMap extends Record<string, keyof RPCMap & string>>(funcMap: FuncMap, nodesOrBuilder?: GraphNodeConfigMap<FuncMap, RPCMap> | ((nodes: FuncMap) => GraphNodeConfigMap<FuncMap, RPCMap>)) => Record<Extract<keyof FuncMap, string>, GraphNodeConfig<Extract<keyof FuncMap, string>>>;
 type GraphNodeConfigMap<FuncMap extends Record<string, string>, RPCMap extends Record<string, RPCHandler>> = {
     [K in Extract<keyof FuncMap, string>]?: {

package/dist/wirings/workflow/graph/graph-node.js

@@ -1,3 +1,8 @@
+/**
+ * Builds a typed graph-node map for a set of RPCs: given a node-id → RPC-name
+ * map and per-node settings, returns the {@link GraphNodeConfig} for every node,
+ * with refs typed against each RPC's input and output.
+ */
 export function createGraph() {
     return (funcMap, nodesOrBuilder) => {
         if (!nodesOrBuilder) {

package/dist/wirings/workflow/graph/template.d.ts

@@ -1,3 +1,4 @@
+/** A string interpolated at run time from other nodes' outputs, as `template` builds it. */
 export type TemplateString = {
     $template: {
         parts: string[];
@@ -9,6 +10,11 @@ export type TemplateString = {
 } & {
     __brand: 'TemplateString';
 };
+/**
+ * Builds a {@link TemplateString} for a graph node's input: each `$0`, `$1`, …
+ * in `templateStr` is replaced at run time by the value of the ref at that
+ * index. An index with no ref resolves to an unknown ref.
+ */
 export declare function template(templateStr: string, refs: Array<{
     $ref: string;
     path?: string;

package/dist/wirings/workflow/graph/template.js

@@ -1,3 +1,8 @@
+/**
+ * Builds a {@link TemplateString} for a graph node's input: each `$0`, `$1`, …
+ * in `templateStr` is replaced at run time by the value of the ref at that
+ * index. An index with no ref resolves to an unknown ref.
+ */
 export function template(templateStr, refs) {
     const parts = [];
     const expressions = [];

package/dist/wirings/workflow/graph/wire-workflow-graph.d.ts

@@ -1,3 +1,4 @@
+/** What `pikkuWorkflowGraph` takes. */
 export interface PikkuWorkflowGraphConfig<FuncMap extends Record<string, string>, T> {
     /** Keeps the graph in the codebase but out of the build. */
     disabled?: true;
@@ -14,6 +15,7 @@ export interface PikkuWorkflowGraphConfig<FuncMap extends Record<string, string>
     /** Free text carried onto the rendered graph, for a reader who needs the reasoning the shape cannot show. */
     notes?: string[];
 }
+/** The marker `pikkuWorkflowGraph` returns; the graph itself is read from source by `pikku all`. */
 export interface PikkuWorkflowGraphResult {
     __type: 'pikkuWorkflowGraph';
     name?: string;
@@ -21,4 +23,14 @@ export interface PikkuWorkflowGraphResult {
     tags?: string[];
     notes?: string[];
 }
+/**
+ * Declares a workflow as a graph: each node names an RPC, and `config` says what
+ * feeds it and which nodes run next. The shape is data, so the console can draw
+ * it and a run records which branch it took.
+ *
+ * The inspector reads the graph from source at build time; at runtime this only
+ * returns a marker carrying the descriptive fields.
+ *
+ * @example snippet: workflowGraph
+ */
 export declare function pikkuWorkflowGraph<const FuncMap extends Record<string, string>>(config: PikkuWorkflowGraphConfig<FuncMap, any>): PikkuWorkflowGraphResult;