@cubicecho/agent-core 2.24.0 → 2.25.0

package/dist/events.d.ts

@@ -1,5 +1,6 @@
-import type { TokenLedger } from "./ledger.ts";
-import type { TurnUsage } from "./stream.ts";
+import type { TokenLedger } from './ledger.ts';
+import type { TurnUsage } from './stream.ts';
+import { CacheBreakReason } from './stream.ts';
 /**
  * What a run is doing, while it is doing it.
  *
@@ -18,6 +19,7 @@ export interface EventBusOptions {
     /**
      * How far past the cap the backlog is allowed to run before it is trimmed.
      *
+     * @remarks
      * Dropping the oldest event on every push means shifting a thousand-element array tens of
      * thousands of times over a reasoning run — the one thing in here that would ever show up in a
      * profile. Trimming in batches makes it a few dozen splices instead, at the cost of the backlog
@@ -31,6 +33,7 @@ export interface EventBusOptions {
     /**
      * The same for a run that has not said `done`, which is a far more dangerous thing to drop.
      *
+     * @remarks
      * A finished run has nothing more to say, so forgetting it a minute later costs a late watcher
      * a backlog and nothing else. An unfinished one is still writing: `touched` only moves on
      * `emit`, so a live run that spends a minute inside one slow tool call looked exactly like an
@@ -50,6 +53,11 @@ export interface EventBusOptions {
  * Changes what the bus keeps, for a process whose runs are not shaped like the ones these
  * defaults were chosen for.
  *
+ * @param [options] - The bounds to change. A field left out — or given anything that is not a
+ * number above zero — keeps what it has, so a partial or a half-built config narrows nothing.
+ * @returns Everything in force afterwards, including what this call did not change.
+ *
+ * @remarks
  * The bus is one thing per runtime rather than an object a caller holds, so this is too: it is
  * a deployment's setting, said once at startup, and not something to move around under a run.
  * Called at the top level that is the process's bus; a runtime made by `createRuntime` has its
@@ -61,38 +69,37 @@ export interface EventBusOptions {
  * Changes apply from the next event and the next sweep. Nothing already buffered is trimmed to
  * a cap that has just come down, because the trim happens on push; the backlog settles to the
  * new number as the run goes on.
- *
- * @param options The bounds to change. A field left out — or given anything that is not a
- * number above zero — keeps what it has, so a partial or a half-built config narrows nothing.
- * @returns Everything in force afterwards, including what this call did not change.
  */
 export declare function configureEvents(options?: EventBusOptions): Required<EventBusOptions>;
 /** Which kind of thing happened, and what `text`, `name`, `ok` and `usage` carry for it. */
-export type RunEventKind = 
-/** A step of a caller's own flow began. `name` is the step, `text` its kind. */
-"step"
-/** A decision step chose an arm. `text` is the arm it took. */
- | "decision"
-/** A new turn of the agent loop began, inside whichever step is running. */
- | "turn"
-/** Reasoning tokens, as they arrive. */
- | "thinking"
-/** Reply tokens, as they arrive. */
- | "output"
-/** The model asked for a tool, with the arguments it chose. `id` is the call's. */
- | "tool-call"
-/** A tool came back, with what it said. `id` is the id of the call it answers. */
- | "tool-result"
-/** Something the runner did that is not the model's doing — a preselection, a retry. */
- | "notice"
-/**
- * What the run has cost so far, at the end of every turn, and what that one turn did. Sent
- * whether or not the endpoint reported tokens, since the timings and the cache comparison are
- * measured either way.
- */
- | "usage"
-/** The run ended. Always last, and always sent. */
- | "done";
+export declare const RunEventKind: {
+    /** A step of a caller's own flow began. `name` is the step, `text` its kind. */
+    readonly Step: 'step';
+    /** A decision step chose an arm. `text` is the arm it took. */
+    readonly Decision: 'decision';
+    /** A new turn of the agent loop began, inside whichever step is running. */
+    readonly Turn: 'turn';
+    /** Reasoning tokens, as they arrive. */
+    readonly Thinking: 'thinking';
+    /** Reply tokens, as they arrive. */
+    readonly Output: 'output';
+    /** The model asked for a tool, with the arguments it chose. `id` is the call's. */
+    readonly ToolCall: 'tool-call';
+    /** A tool came back, with what it said. `id` is the id of the call it answers. */
+    readonly ToolResult: 'tool-result';
+    /** Something the runner did that is not the model's doing — a preselection, a retry. */
+    readonly Notice: 'notice';
+    /**
+     * What the run has cost so far, at the end of every turn, and what that one turn did. Sent
+     * whether or not the endpoint reported tokens, since the timings and the cache comparison are
+     * measured either way.
+     */
+    readonly Usage: 'usage';
+    /** The run ended. Always last, and always sent. */
+    readonly Done: 'done';
+};
+/** Any one of the kinds in `RunEventKind`. */
+export type RunEventKind = (typeof RunEventKind)[keyof typeof RunEventKind];
 /**
  * What a run has spent, counted from the start of the run rather than for the turn that
  * carried it: a client draws the latest one it has seen and needs no arithmetic of its own,
@@ -128,6 +135,7 @@ export interface TurnReport extends TurnUsage {
 /**
  * One thing that happened in a run, as a watcher receives it.
  *
+ * @remarks
  * Every field but `id` is always present — the empty ones are `""` or `null` rather than
  * missing — so a client reads it without guarding each key.
  */
@@ -139,6 +147,7 @@ export interface RunEvent {
     /**
      * When it happened, as epoch milliseconds.
      *
+     * @remarks
      * A number rather than a `Date`: these events are read over a wire, where a `Date` is an ISO
      * string by the time anyone sees it, and `emit` runs once per streamed token — so the object
      * it does not allocate is one per token. It also spares the `getTime()` the sweep used to do
@@ -170,22 +179,25 @@ export interface RunEvent {
 /**
  * What `emit` is given: the run and the sequence are the bus's to assign.
  *
+ * @remarks
  * Named exclusions rather than a blanket `Partial`, which permitted both and let the spread in
  * `emit` overwrite them — a caller could file an event under another run and hand every watcher
  * a duplicate `seq`, which is the one thing the sequence is for.
  */
-export type RunEventInput = Pick<RunEvent, "kind"> & Partial<Omit<RunEvent, "kind" | "runId" | "seq">>;
+export type RunEventInput = Pick<RunEvent, 'kind'> & Partial<Omit<RunEvent, 'kind' | 'runId' | 'seq'>>;
 /**
  * A whole event from what a caller said of it: the empty defaults under it, the run and sequence over it.
  *
+ * @param input - What happened. An `at` it carries wins over the one given here.
+ * @param runId - The run it belongs to. Written after `input`, which gets no say in it.
+ * @param seq - Its place in that run, the same.
+ * @param at - When, for an input that does not say.
+ * @returns A new event; `input` is not written to.
+ *
+ * @remarks
  * The one place the defaults are written, so an event the bus stamps, one the loop keeps for its
  * own metrics and the notice a slow watcher is sent cannot come to disagree about what an unset
  * field reads as.
- *
- * @param input What happened. An `at` it carries wins over the one given here.
- * @param runId The run it belongs to. Written after `input`, which gets no say in it.
- * @param seq Its place in that run, the same.
- * @param at When, for an input that does not say.
  */
 export declare const stamp: (input: RunEventInput, runId: string, seq: number, at: number) => RunEvent;
 /**
@@ -193,45 +205,54 @@ export declare const stamp: (input: RunEventInput, runId: string, seq: number, a
  * loop threw where it could not be caught. The sweep gets there on its own; this is for a
  * caller that already knows.
  *
- * @param runId The run to forget. An id nothing was emitted under is ignored.
+ * @param runId - The run to forget. An id nothing was emitted under is ignored.
  */
 export declare function endRun(runId: string): void;
 /**
  * Records one event and hands it to everyone watching that run. Never throws at the caller.
  *
- * @param runId The run this belongs to. Created on first use.
- * @param input The event. `kind` is required; `runId` and `seq` are not a caller's to set.
+ * @param runId - The run this belongs to. Created on first use.
+ * @param input - The event. `kind` is required; `runId` and `seq` are not a caller's to set.
+ * @returns The event as it was recorded: its `seq` in the run, its time, and every unset field
+ * filled in.
  */
 export declare function emit(runId: string, input: RunEventInput): RunEvent;
 /**
  * Everything that has happened on a run, then everything that happens next, until it ends.
  *
- * The backlog comes first so a watcher that joins halfway through — or after the run finished,
- * inside the retention window — reads the same story as one that was there from the start.
- *
- * @param runId The run to follow. One that has not started yet is waited on, not refused.
- * @param signal Stops following. The only other way out is the run's own `done`, and a watcher
+ * @param runId - The run to follow. One that has not started yet is waited on, not refused.
+ * @param [signal] - Stops following. The only other way out is the run's own `done`, and a watcher
  * with no way out is a leak rather than a lost backlog: the sweep below skips any stream a
  * listener is on, so a run that dies without `done` pins its backlog for the life of the process.
  * Returning the generator is not that way out — parked on the promise at the foot of this
  * function it is suspended at an `await` rather than at a `yield`, and a `return()` there is
  * queued behind a promise only the next event can settle. An abort resolves that promise itself.
+ * @returns The run's events in order, ending after its `done` or at the abort. A watcher that fell
+ * too far behind is given one notice in place of the events it missed. Nothing is subscribed until
+ * the first event is asked for.
+ *
+ * @remarks
+ * The backlog comes first so a watcher that joins halfway through — or after the run finished,
+ * inside the retention window — reads the same story as one that was there from the start.
  */
 export declare function watch(runId: string, signal?: AbortSignal): AsyncGenerator<RunEvent>;
 /**
  * The backlog alone, for a caller that wants a snapshot rather than a subscription.
  *
+ * @param runId - The run to read. An unknown or already-swept run gives an empty array.
+ * @returns The events still held, oldest first, in an array of the caller's own.
+ *
+ * @remarks
  * The array is a copy; the events in it are not. They are the same objects the bus holds and
  * every watcher was handed, so writing to one rewrites the run for everybody — which is what
  * `fold` copies to avoid, and this is the other half of the same warning. Read them, or copy
  * what you mean to change.
- *
- * @param runId The run to read. An unknown or already-swept run gives an empty array.
  */
 export declare const history: (runId: string) => RunEvent[];
 /**
  * Test seam: forget every run, so one test's events cannot be read by the next.
  *
+ * @remarks
  * Named for what it forgets rather than bare `reset`, which sat in a consumer's imports beside
  * `resetAll`, `resetClients`, `resetCapabilities` and `resetHints` saying nothing about which
  * of the five it was — `reset.ts` had to alias it on the way in to stay readable.
@@ -243,21 +264,25 @@ export declare const history: (runId: string) => RunEvent[];
  */
 export declare const resetEvents: () => void;
 /**
- * Consecutive tokens of one kind are one thing being said, not hundreds of things.
+ * A run's events with each stretch of `thinking` or of `output` joined into one block, for a
+ * reader that takes a run in snapshots.
+ *
+ * @param events - Events in `seq` order, from `history` or collected from `watch`. Not written to.
+ * @returns One event per block, every one a copy. A run of `thinking` or of `output` within one
+ * step is a single block with the texts joined; anything else is a block to itself.
  *
- * A client that reads a run in snapshots rather than token by token wants it that way: a
+ * @remarks
+ * Consecutive tokens of one kind are one thing being said, not hundreds of things. A client that
+ * reads a run in snapshots rather than token by token wants it that way: a
  * reasoning model spends ten thousand deltas on a paragraph, and a paragraph is what it meant.
  * Each block carries the `seq` of its last event, so asking for what came after one block
  * picks up exactly where it left off.
- *
- * @param events Events in `seq` order, from `history` or collected from `watch`.
  */
 export declare function fold(events: RunEvent[]): RunEvent[];
-/** Why a turn's cache broke, as `TurnUsage.cacheBreakReason` names it. */
-type CacheBreakReason = NonNullable<TurnUsage["cacheBreakReason"]>;
 /**
  * A run summed and derived from its events: what it cost, where the time went, and why.
  *
+ * @remarks
  * The counts are always there, zero when nothing happened. Every other field is absent where no
  * turn reported what it is made of, and summed over the turns that did where only some did —
  * a mean of a number a server never sent would be a number nobody measured.
@@ -321,13 +346,23 @@ export interface RunMetrics {
     largestPrompt?: number;
     /** `largestPrompt` over the window `runMetrics` was told, for how close the run came. */
     largestPromptShare?: number;
+    /** How it ended, read off `done` and the last turn. */
+    outcome?: RunOutcome;
+}
+/** How a run ended, as `runMetrics` reads it. */
+export declare const RunOutcome: {
+    /** The run did not fail, and its last turn was not cut off. */
+    readonly Answered: 'answered';
+    /** The run did not fail, and its last turn is an answer the reply ceiling cut off. */
+    readonly Truncated: 'truncated';
     /**
-     * How it ended, read off `done` and the last turn: `truncated` is an answer the ceiling cut off.
-     * A failure does not say whether it was an error, a stop or the tool budget — that is in the
-     * host's own `done` text.
+     * `done` said the run was not ok. Whether that was an error, a stop or the tool budget is in
+     * the host's own `done` text and not here.
      */
-    outcome?: "answered" | "truncated" | "failed";
-}
+    readonly Failed: 'failed';
+};
+/** Any one of the outcomes in `RunOutcome`. */
+export type RunOutcome = (typeof RunOutcome)[keyof typeof RunOutcome];
 /** What `runMetrics` takes besides the events. */
 export interface RunMetricsOptions {
     /** The window the run was served, for `largestPromptShare`. Absent or zero leaves it out. */
@@ -336,15 +371,17 @@ export interface RunMetricsOptions {
 /**
  * A run's totals, timings and cache findings, derived from the events it emitted.
  *
+ * @param events - A run's events in `seq` order, from `history` or collected from `watch`. A backlog
+ * that has lost its oldest events to the cap sums what it still has.
+ * @param [options] - The served window, for how full the run came to it.
+ * @returns A summary of the caller's own. The counts are zero for an empty list, and `outcome` is
+ * absent for a run that has not reported `done`.
+ *
+ * @remarks
  * A sibling of `fold` rather than part of it. `fold` hands back events, and a client renders
  * what it returns as blocks; a summary is another shape, and folding one in would give every
  * consumer of `fold` a block it does not know how to draw. Derived from the `usage` reports' own
  * `turn` rather than the running totals, so a run with several loops in it — a question per loop —
  * adds up the same as one with a single loop.
- *
- * @param events A run's events in `seq` order, from `history` or collected from `watch`. A backlog
- * that has lost its oldest events to the cap sums what it still has.
- * @param options The served window, for how full the run came to it.
  */
 export declare function runMetrics(events: RunEvent[], { contextLength }?: RunMetricsOptions): RunMetrics;
-export {};