@pikku/core 0.12.91 → 0.12.93

package/src/wirings/agent/agent-authorization.test.ts

@@ -8,7 +8,11 @@ import {
 } from '../../pikku-state.js'
 import { assertAgentAuthorized } from './agent-prepare.js'
 import { clearPermissionsCache } from '../../permissions.js'
-import { ForbiddenError, MissingScopeError } from '../../errors/errors.js'
+import {
+  ForbiddenError,
+  MissingScopeError,
+  MissingSessionError,
+} from '../../errors/errors.js'
 import type { CoreAgent } from './agent.types.js'
 import type { CoreUserSession } from '../../types/core.types.js'
 
@@ -73,7 +77,7 @@ describe('assertAgentAuthorized', () => {
     await assertAgentAuthorized(agent, {}, null)
   })
 
-  test('throws ForbiddenError when auth is explicitly true and no session exists', async () => {
+  test('throws MissingSessionError when auth is explicitly true and no session exists', async () => {
     const agent = addAgent('needs-session', { auth: true })
     await assert.rejects(
       () =>
@@ -82,7 +86,7 @@ describe('assertAgentAuthorized', () => {
           { sessionService: sessionService(undefined) },
           null
         ),
-      ForbiddenError
+      MissingSessionError
     )
   })
 

package/src/wirings/agent/agent-prepare.ts

@@ -22,7 +22,7 @@ import {
   type PermissionWire,
 } 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'
@@ -315,7 +315,7 @@ export async function assertAgentAuthorized(
     : undefined
 
   if (agent.auth === true && !session) {
-    throw new ForbiddenError('Authentication required')
+    throw new MissingSessionError('Authentication required')
   }
 
   verifyScopes(agent.scopes, session)

package/src/wirings/agent/agent.types.ts

@@ -183,6 +183,7 @@ 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: {
@@ -210,6 +211,7 @@ export interface PikkuAgentMiddlewareHooks<
     | Promise<{ messages: AgentMessage[]; instructions: string }>
     | { 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: {
@@ -262,6 +264,7 @@ export interface PikkuAgentMiddlewareHooks<
    * 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: {
@@ -282,6 +285,7 @@ export interface PikkuAgentMiddlewareHooks<
         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: {
@@ -294,6 +298,7 @@ export interface PikkuAgentMiddlewareHooks<
     | { 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: {
@@ -305,6 +310,7 @@ export interface PikkuAgentMiddlewareHooks<
     }
   ) => Promise<{ result: unknown } | void> | { result: unknown } | void
 
+  /** Runs at the end of each model turn. For observation — it cannot change what happened. */
   afterStep?: (
     services: SingletonServices,
     ctx: {
@@ -323,6 +329,7 @@ export interface PikkuAgentMiddlewareHooks<
     }
   ) => 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: {
@@ -347,58 +354,51 @@ export type CoreAgent<
   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[]
@@ -407,8 +407,11 @@ export type CoreAgent<
     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
@@ -427,6 +430,7 @@ export type CoreAgent<
    * `#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>
 }
 

package/src/wirings/agent-scorer/agent-scorer.ts

@@ -18,6 +18,8 @@ const assertSampleRate = (name: string, sampleRate: number | undefined) => {
 /**
  * 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 = <Services = any>(config: {
   name: string
@@ -49,6 +51,8 @@ export 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 const pikkuAgentJudge = <Services = any>(config: {
   name: string

package/src/wirings/channel/channel.types.ts

@@ -98,8 +98,11 @@ export type CoreChannel<
   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
     | {
@@ -112,7 +115,9 @@ export type CoreChannel<
         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<
@@ -125,17 +130,23 @@ export type CoreChannel<
         }
     >
   >
+  /** 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/src/wirings/cli/cli.types.ts

@@ -174,6 +174,12 @@ type SplitBySpace<S extends string> = S extends `${infer First} ${infer Rest}`
     ? []
     : [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
  */
@@ -182,7 +188,7 @@ type BuildParamsTuple<Parts extends readonly string[]> =
     infer First extends string,
     ...infer Rest extends string[],
   ]
-    ? [StripBrackets<First>, ...BuildParamsTuple<Rest>]
+    ? [StripVariadic<StripBrackets<First>>, ...BuildParamsTuple<Rest>]
     : []
 
 /**
@@ -227,16 +233,39 @@ export type CoreCLICommandConfig<
   >,
   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
@@ -246,13 +275,18 @@ export type CoreCLICommandConfig<
       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
 }
 
@@ -308,14 +342,23 @@ export interface CoreCLI<
   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/src/wirings/cli/define-cli-commands.ts

@@ -1,6 +1,11 @@
 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 function defineCLICommands<
   T extends Record<string, CoreCLICommandConfig<any, any, any, any>>,
 >(commands: T): T {

package/src/wirings/credential/credential.types.ts

@@ -1,12 +1,19 @@
 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/src/wirings/gateway/gateway-authorization.test.ts

@@ -280,7 +280,7 @@ describe('gateway handler authorization', () => {
 
       const response = await postMessage('/webhooks/declared-session')
 
-      assert.equal(response.status, 403)
+      assert.equal(response.status, 401)
       assert.deepEqual(
         calls,
         [],
@@ -339,7 +339,7 @@ describe('gateway handler authorization', () => {
 
       const response = await postMessage('/webhooks/gw-auth')
 
-      assert.equal(response.status, 403)
+      assert.equal(response.status, 401)
       assert.deepEqual(calls, [], 'auth: true must require a session')
     })
 
@@ -365,7 +365,7 @@ describe('gateway handler authorization', () => {
 
       const response = await postMessage('/webhooks/handler-auth')
 
-      assert.equal(response.status, 403)
+      assert.equal(response.status, 401)
       assert.deepEqual(calls, [], 'auth: true must require a session')
     })
 

package/src/wirings/gateway/gateway.types.ts

@@ -17,6 +17,10 @@ export interface GatewayAttachment {
   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
@@ -26,15 +30,27 @@ export interface GatewayInboundMessage {
   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. */
@@ -70,14 +86,21 @@ export type CoreGateway<
 > = Partial<
   Pick<CommonWireMeta, 'title' | 'summary' | 'description' | 'errors'>
 > & {
+  /** Unique across the project. It is how the gateway is addressed in `pikku meta` and in logs. */
   name: string
+  /** How the platform reaches us: a `webhook` it posts to, a `websocket` it holds open, or a `listener` we open outward. */
   type: GatewayTransportType
   /** Required for 'webhook' and 'websocket'; unused for 'listener'. */
   route?: string
+  /** Which service this speaks to — slack, whatsapp, discord. It selects the adapter's dialect, not the transport. */
   platform?: string
+  /** Translates between the platform's message format and pikku's. A factory is called with services, for an adapter that needs a token or a client. */
   adapter: GatewayAdapter | GatewayAdapterFactory
+  /** The function to run per inbound message. It receives the normalised message, not the platform's raw payload. */
   func: PikkuFunctionConfig
+  /** Wraps every inbound message: signature verification, tracing, rate limiting. */
   middleware?: CorePikkuMiddlewareGroup<any, any>
+  /** Filters this gateway in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
   tags?: string[]
   /** Unset lets the handler's own `auth` govern; gateway handlers are sessionless by default. */
   auth?: boolean

package/src/wirings/http/http-runner-addon-ref.test.ts

@@ -233,6 +233,6 @@ describe('http routes wired with ref() to an addon function', () => {
 
     const response = await fetch(new ParamsRequest('/addon/greet', 'get'))
 
-    assert.strictEqual(response.status, 403)
+    assert.strictEqual(response.status, 401)
   })
 })