nexus-ai-pro 2.0.0 → 2.2.0

package/dist/types/graph.d.ts

@@ -30,11 +30,20 @@ export declare class Send {
     readonly node: string;
     /** What the task receives as `context.input`. */
     readonly input?: unknown | undefined;
+    /** Options for this task alone. `timeout` replaces the node's own for it. */
+    readonly options?: SendOptions | undefined;
     constructor(
     /** The node to run. */
     node: string, 
     /** What the task receives as `context.input`. */
-    input?: unknown | undefined);
+    input?: unknown | undefined, 
+    /** Options for this task alone. `timeout` replaces the node's own for it. */
+    options?: SendOptions | undefined);
+}
+/** Options for one task a `Send` creates. */
+export interface SendOptions {
+    /** Replaces the node's timeout for this task, such as a longer limit for one large document. */
+    timeout?: NodeTimeout;
 }
 /** Where a `Command` sends control. */
 export type CommandTarget = string | Send | Array<string | Send>;
@@ -79,6 +88,118 @@ export interface GraphTask {
     node: string;
     /** The task's `Send` input. */
     input?: unknown;
+    /** The timeout its `Send` set, replacing the node's own. */
+    timeout?: NodeTimeout;
+}
+/**
+ * How long a node may run, in two senses.
+ *
+ * `runMs` caps the whole attempt: "this may never take longer than ten minutes". `idleMs` caps the
+ * time between signs of progress: "this may take ten minutes, but must show progress every thirty
+ * seconds". A node shows progress by calling `context.heartbeat()`, `context.emit()`, or
+ * `context.report()`. Either limit fails the attempt with `GraphNodeTimeoutError`, which the retry
+ * policy may retry.
+ */
+export interface NodeTimeout {
+    /** The longest an attempt may run, in milliseconds. */
+    runMs?: number;
+    /** The longest an attempt may go without showing progress, in milliseconds. */
+    idleMs?: number;
+}
+/**
+ * When a graph writes its checkpoints.
+ *
+ * - `sync` (the default) writes each checkpoint before the next superstep starts. Use it when a
+ *   node's side effects must line up with the state that records them, such as payments.
+ * - `async` writes checkpoints in the background while the graph runs on. Every write still
+ *   happens, in order, and the run waits for them before it returns, pauses, fails, or drains. A
+ *   crash can lose the last few supersteps, which then run again.
+ * - `exit` writes only when the run stops: at an interrupt, a breakpoint, completion, a failure, an
+ *   abort, or a drain. A crash loses the whole run. For short, high-throughput graphs.
+ */
+export type DurabilityMode = 'sync' | 'async' | 'exit';
+/**
+ * Why a node's last attempt failed, handed to its `onError` once retries are exhausted.
+ *
+ * Everything here is what the runtime knows at the moment of failure. The decision `onError`
+ * returns is checkpointed before the graph moves on, so a crash after it resumes into the same path.
+ */
+export interface NodeFailure {
+    /** The node that failed. */
+    node: string;
+    /** The task that failed. Equal to `node` unless the task came from a `Send`. */
+    taskId: string;
+    /** The superstep it failed in. */
+    step: number;
+    /** Attempts made, including the last. */
+    attempts: number;
+    /** ISO-8601 time of the first attempt. */
+    firstAttemptAt: string;
+    /** ISO-8601 time the last attempt failed. */
+    failedAt: string;
+    /** What the last attempt threw. */
+    error: unknown;
+    /** True when the retry policy ran out; false when the error was not retryable. */
+    retryExhausted: boolean;
+    /** The limit that ended the last attempt, when a timeout did. */
+    timeout?: {
+        type: 'run' | 'idle';
+        limitMs: number;
+    };
+    /** The task's `Send` input. */
+    input?: unknown;
+    /** The thread the run belongs to. */
+    threadId: string;
+}
+/**
+ * Decides what happens after a node's retries are exhausted: a state update, a `Command` that
+ * routes to a compensation node, or nothing, to carry on along the node's own edges. Throwing fails
+ * the graph with that error.
+ *
+ * It decides; it should not act. Compensation with side effects belongs in the node it routes to,
+ * which runs only after the decision is checkpointed.
+ */
+export type NodeErrorHandler<S extends ChannelSchema = ChannelSchema> = (failure: NodeFailure, context: {
+    state: Readonly<StateOf<S>>;
+}) => NodeResult<S> | Promise<NodeResult<S>>;
+/** A failure a node's `onError` recovered from, as its checkpoint records it. */
+export interface RecoveredFailure {
+    /** The node that failed. */
+    node: string;
+    /** The task that failed. */
+    taskId: string;
+    /** The superstep it failed in. */
+    step: number;
+    /** Attempts made. */
+    attempts: number;
+    /** What the last attempt threw, as a name and a message. */
+    error: {
+        name: string;
+        message: string;
+    };
+    /** ISO-8601 time the last attempt failed. */
+    failedAt: string;
+    /** True when the retry policy ran out. */
+    retryExhausted: boolean;
+    /** The limit that ended the last attempt, when a timeout did. */
+    timeout?: {
+        type: 'run' | 'idle';
+        limitMs: number;
+    };
+    /** Where `onError` sent the run, when it returned a `Command` with a target. */
+    goto?: string[];
+}
+/**
+ * Asks a running graph to stop at the end of its current superstep.
+ *
+ * `RunControl` from `nexus-ai-pro/graph` implements it. Any object with these members works, so a
+ * server can pass its own.
+ */
+export interface RunControlLike {
+    /** True once a drain was requested. */
+    readonly draining: boolean;
+    /** Why the drain was requested. */
+    readonly reason?: string;
 }
 /**
  * How a node retries. Applied per node, or as the graph default through `compile({ retry })`.
@@ -100,12 +221,28 @@ export interface RetryPolicy {
     /** Decides whether this error is worth retrying. Defaults to retrying anything else. */
     retryOn?(error: unknown, attempt: number): boolean;
 }
-/** How a node runs: retries, a timeout, where it may route, deferral, and caching. */
-export interface NodeOptions {
+/**
+ * How a node runs: retries, timeouts, recovery, where it may route, deferral, caching, and whether
+ * it is safe to run twice.
+ */
+export interface NodeOptions<S extends ChannelSchema = ChannelSchema> {
     /** Retries failed attempts, overriding the graph's default policy. */
     retry?: RetryPolicy;
-    /** Aborts the node's signal and fails the attempt when it runs longer than this. */
+    /** Aborts the node's signal and fails the attempt when it runs longer than this. Same as `timeout.runMs`. */
     timeoutMs?: number;
+    /** A run limit, an idle limit, or both. `timeout.runMs` wins over `timeoutMs`. */
+    timeout?: NodeTimeout;
+    /**
+     * Called once retries are exhausted, instead of failing the graph. See `NodeErrorHandler`. A
+     * `Command` it returns may route anywhere; declare those targets in `ends`.
+     */
+    onError?: NodeErrorHandler<S>;
+    /**
+     * Declares that running this node twice is safe: it has no side effects, or they carry an
+     * idempotency key. Nothing at run time depends on it; `lintGraph()` uses it to flag retried nodes
+     * that are not.
+     */
+    idempotent?: boolean;
     /**
      * Nodes this one may reach through `Send` or a `Command`. Declaring them keeps compile-time
      * reachability checks and diagrams exact, so a node reached only that way is not reported as
@@ -235,6 +372,8 @@ export interface NodeContext<S extends ChannelSchema> {
     readonly step: number;
     /** The thread this run belongs to. */
     readonly threadId: string;
+    /** The tenant the run is for, when it has one. */
+    readonly tenantId?: string;
     /** Identifies this task. Equal to `node` unless the task came from a `Send`. */
     readonly taskId: string;
     /** Input carried by a `Send`. Undefined for a node reached through an ordinary edge. */
@@ -258,16 +397,33 @@ export interface NodeContext<S extends ChannelSchema> {
      * Long-term memory, present when the graph was compiled with a store.
      *
      * State is this thread's; the store is everything else the application remembers — across threads,
-     * users, and runs.
+     * users, and runs. In a run with a `tenantId`, it is that tenant's view of the store, and nothing
+     * another tenant stored can be read through it.
      */
     readonly store?: Store;
-    /** Reports progress without writing to state. */
+    /** Reports progress without writing to state. Refreshes an idle timeout. */
     report(progress: Omit<GraphProgress, 'step' | 'node'>): void;
     /**
-     * Sends anything to the run's `onEvent` listener as a `custom` event: model tokens as they stream,
-     * intermediate results, a status line. Nothing is written to state or checkpointed.
+     * Shows the node is still making progress, which refreshes its idle timeout. For long work that
+     * neither emits nor reports, such as a large upload or a slow tool call.
+     */
+    heartbeat(): void;
+    /**
+     * Sends anything to the run's `onEvent` listener as a `custom` event: intermediate results, a
+     * status line. Nothing is written to state or checkpointed. Refreshes an idle timeout.
      */
     emit(data: unknown): void;
+    /**
+     * Streams a piece of model output as a `message` event, which `events()` delivers on its
+     * `messages` projection. `createAgent()` sends its model's output this way. Refreshes an idle
+     * timeout.
+     */
+    message(chunk: GraphMessageChunk): void;
+    /**
+     * Reports a tool call as a `tool` event, which `events()` delivers on its `tools` projection.
+     * `createAgent()` reports every tool it runs this way. Refreshes an idle timeout.
+     */
+    tool(event: GraphToolEvent): void;
 }
 /** A node: reads state from its context and returns an update, a `Command`, or nothing. */
 export type NodeFn<S extends ChannelSchema> = (context: NodeContext<S>) => Promise<NodeResult<S>> | NodeResult<S>;
@@ -335,6 +491,13 @@ export interface GraphCheckpoint<S extends ChannelSchema = ChannelSchema> {
     };
     /** Present when the run paused at a breakpoint rather than to ask a question. */
     breakpoint?: GraphBreakpoint;
+    /** Failures in the step this checkpoint follows that a node's `onError` recovered from. */
+    recovered?: RecoveredFailure[];
+    /** Present when the run stopped because a drain was requested. `continue()` resumes it. */
+    drained?: {
+        reason?: string;
+        at: string;
+    };
     /** ISO-8601 time the checkpoint was written. */
     createdAt: string;
     /** Application data, including `graph` when the graph was compiled with a name. */
@@ -407,6 +570,13 @@ export interface GraphRunOptions {
     signal?: AbortSignal;
     /** Application data recorded on every checkpoint of the run. */
     metadata?: Record<string, unknown>;
+    /**
+     * The tenant the run is for. It is recorded on every checkpoint as `metadata.tenantId`, nodes read
+     * it as `context.tenantId`, and `context.store` becomes the tenant's own view of the store. A thread
+     * another tenant owns is not found: resuming, continuing, forking, or editing it with a different
+     * `tenantId` is refused before anything runs. A run without one carries on the thread's tenant.
+     */
+    tenantId?: string;
     /** Overrides the compiled `maxConcurrency` for this run. */
     maxConcurrency?: number;
     /** Breakpoints for this run only, replacing the compiled ones. */
@@ -421,6 +591,19 @@ export interface GraphRunOptions {
     onEvent?: (event: GraphEvent) => void;
     /** Receives what nodes pass to `context.report()`. A throwing callback never fails the node. */
     onProgress?: (progress: GraphProgress) => void;
+    /** Overrides the compiled `durability` for this run. */
+    durability?: DurabilityMode;
+    /**
+     * Also delivers the events of subgraphs run through `asNode()` to `onEvent`, each with the
+     * `namespace` of nodes it came through. Defaults to false.
+     */
+    subgraphEvents?: boolean;
+    /**
+     * Lets the caller stop the run at the end of its current superstep: pass a `RunControl` and call
+     * `drain()`, on SIGTERM for example. The run writes its checkpoint and ends with
+     * `GraphDrainedError`, and `continue()` resumes it, on this worker or another.
+     */
+    control?: RunControlLike;
 }
 /** The outcome of a run. */
 export interface GraphResult<S extends ChannelSchema, O extends keyof S = keyof S> {
@@ -447,7 +630,7 @@ export interface GraphResult<S extends ChannelSchema, O extends keyof S = keyof
     };
 }
 /** Fine-grained events delivered to `GraphRunOptions.onEvent`. */
-export type GraphEvent = {
+export type GraphEvent = ({
     type: 'task_start';
     step: number;
     taskId: string;
@@ -460,6 +643,15 @@ export type GraphEvent = {
     node: string;
     attempt: number;
     error: string;
+} | {
+    type: 'task_failed';
+    step: number;
+    taskId: string;
+    node: string;
+    attempts: number;
+    error: string;
+    /** True when the node's `onError` recovered, so the graph carries on. */
+    recovered: boolean;
 } | {
     type: 'task_end';
     step: number;
@@ -480,7 +672,132 @@ export type GraphEvent = {
     taskId: string;
     node: string;
     data: unknown;
+} | {
+    type: 'message';
+    step: number;
+    taskId: string;
+    node: string;
+    chunk: GraphMessageChunk;
+} | {
+    type: 'tool';
+    step: number;
+    taskId: string;
+    node: string;
+    tool: GraphToolEvent;
+}) & {
+    /**
+     * The nodes a subgraph event came through, outermost first: `['review']` for an event of a graph
+     * that runs as the parent's `review` node. Absent for the graph's own events.
+     */
+    namespace?: string[];
+};
+/** A piece of a model's output, as a node streams it: text, or a reasoning summary. */
+export interface GraphMessageChunk {
+    /** `text` for visible output, `reasoning` for a reasoning summary. Defaults to `text`. */
+    kind?: 'text' | 'reasoning';
+    /** The text. */
+    content: string;
+    /** Identifies the message the chunk belongs to, when a node streams more than one. */
+    messageId?: string;
+}
+/** A tool call's progress, as a node reports it. */
+export interface GraphToolEvent {
+    /** `start` when it is called, `progress` while it runs, then `result` or `error`. */
+    phase: 'start' | 'progress' | 'result' | 'error';
+    /** The call's id, matching the model's. */
+    id: string;
+    /** The tool's name. */
+    name: string;
+    /** The arguments, on `start`. */
+    args?: unknown;
+    /** Anything the tool reported, on `progress`. */
+    progress?: unknown;
+    /** What it returned, on `result`. */
+    result?: unknown;
+    /** Why it failed, on `error`. */
+    error?: string;
+}
+/**
+ * What `events()` can include. `values` is the state after each superstep; `updates` each task's
+ * write; `messages` model output as nodes stream it; `tools` tool calls; `tasks` each task
+ * starting, retrying, failing, and ending; `checkpoints` each write; `custom` what nodes emit.
+ */
+export type GraphStreamProjection = 'values' | 'updates' | 'messages' | 'tools' | 'tasks' | 'checkpoints' | 'custom';
+/** One event of `events()`, tagged by its projection. */
+export type GraphStreamEvent<S extends ChannelSchema = ChannelSchema> = ({
+    type: 'values';
+    step: number;
+    status: GraphStatus;
+    state: StateOf<S>;
+} | {
+    type: 'updates';
+    step: number;
+    node: string;
+    taskId: string;
+    update: unknown;
+} | {
+    type: 'messages';
+    step: number;
+    node: string;
+    taskId: string;
+    chunk: GraphMessageChunk;
+} | {
+    type: 'tools';
+    step: number;
+    node: string;
+    taskId: string;
+    tool: GraphToolEvent;
+} | {
+    type: 'tasks';
+    event: Extract<GraphEvent, {
+        type: 'task_start' | 'task_retry' | 'task_failed' | 'task_end';
+    }>;
+} | {
+    type: 'checkpoints';
+    step: number;
+    status: GraphStatus;
+    next: string[];
+} | {
+    type: 'custom';
+    step: number;
+    node: string;
+    taskId: string;
+    data: unknown;
+}) & {
+    /** The subgraph nodes it came through, outermost first. Empty for the graph's own events. */
+    namespace: string[];
 };
+/**
+ * What an event stream does when a reader falls behind within a superstep. At the end of each
+ * superstep the run waits for its slowest reader, whatever the policy, so a slow reader slows the
+ * graph down rather than filling memory.
+ *
+ * - `coalesce` (the default) merges a model chunk into the one before it from the same task, and a
+ *   state snapshot into the one before it; when nothing can merge, the oldest event goes.
+ * - `drop-oldest` and `drop-newest` lose events, and count them.
+ * - `error` ends the stream with `GraphStreamOverflowError` and stops the run.
+ */
+export type GraphStreamOverflow = 'coalesce' | 'drop-oldest' | 'drop-newest' | 'error';
+/** Options for `events()`: the run's own options, what to include, and how much to buffer. */
+export interface GraphEventsOptions extends GraphRunOptions {
+    /** Projections to include. Defaults to `values`, `updates`, `messages`, `tools`, and `custom`. */
+    include?: GraphStreamProjection[];
+    /** Includes the events of subgraphs, with their `namespace`. Defaults to false. */
+    subgraphs?: boolean;
+    /** Events each reader holds before `overflow` applies. Defaults to 1,000. */
+    maxBuffered?: number;
+    /** What happens when a reader's buffer is full. Defaults to `coalesce`. */
+    overflow?: GraphStreamOverflow;
+}
+/** What an event stream did to keep up with its slowest reader. */
+export interface GraphStreamStats {
+    /** The most events any reader held at once. */
+    peak: number;
+    /** Events merged into another. */
+    coalesced: number;
+    /** Events lost. */
+    dropped: number;
+}
 /** One superstep, as seen by `stream()`. */
 export interface GraphStepEvent<S extends ChannelSchema> {
     /**
@@ -506,6 +823,8 @@ export interface GraphStepEvent<S extends ChannelSchema> {
     interrupts?: PendingInterrupt[];
     /** The breakpoint the step stopped at. */
     breakpoint?: GraphBreakpoint;
+    /** Failures in this step that a node's `onError` recovered from. */
+    recovered?: RecoveredFailure[];
     /** A `Command.PARENT` that ended this run, for the graph that contains it. In memory only. */
     parentCommand?: Command;
 }
@@ -523,7 +842,15 @@ export interface GraphDescription {
         ends?: string[];
         defer?: boolean;
         retry?: boolean;
+        /** Attempts its retry policy allows, when more than one. */
+        maxAttempts?: number;
         timeoutMs?: number;
+        /** Its run and idle limits, when it has either. */
+        timeout?: NodeTimeout;
+        /** True when the node recovers from failure through `onError`. */
+        onError?: boolean;
+        /** True when the node is declared safe to run twice. */
+        idempotent?: boolean;
         /** True when the node reuses results through `cache`. */
         cache?: boolean;
         /** The graph this node runs, when it is a compiled graph used through `asNode()`. */
@@ -543,6 +870,12 @@ export interface GraphDescription {
     input?: string[];
     /** Channels a caller gets back, when the graph restricts them. */
     output?: string[];
+    /** When checkpoints are written. */
+    durability?: DurabilityMode;
+    /** Where checkpoints go: the in-process default, a store the application passed, or nowhere. */
+    checkpointer?: 'memory' | 'custom' | 'none';
+    /** Tasks a superstep runs at once. */
+    maxConcurrency?: number;
 }
 /**
  * Options applied when a graph is compiled: stores, breakpoints, concurrency, retries, and failure
@@ -565,6 +898,18 @@ export interface CompileOptions {
     maxConcurrency?: number;
     /** Default retry policy for every node. A node's own policy wins. */
     retry?: RetryPolicy;
+    /**
+     * Defaults for every node: a retry policy, timeouts, and an `onError`. A node's own options win,
+     * field by field. `retry` here is the same as `compile({ retry })`, and wins over it.
+     */
+    nodeDefaults?: Pick<NodeOptions, 'retry' | 'timeout' | 'onError'>;
+    /** When checkpoints are written: `sync` (the default), `async`, or `exit`. See `DurabilityMode`. */
+    durability?: DurabilityMode;
+    /**
+     * Checkpoint writes `async` durability keeps in flight before the graph waits for the store to
+     * catch up. Defaults to 8. Bounds what a slow store can cost in memory.
+     */
+    maxPendingWrites?: number;
     /**
      * What happens to sibling tasks when one fails. `fail-fast` (the default) aborts their signals;
      * `settle` lets them finish, which is worth it when their work is expensive to repeat.

package/dist/types/graph.js

@@ -3,9 +3,11 @@ export const END = '__end__';
 export class Send {
     node;
     input;
-    constructor(node, input) {
+    options;
+    constructor(node, input, options) {
         this.node = node;
         this.input = input;
+        this.options = options;
     }
 }
 export class Command {

package/dist/types/messages.d.ts

@@ -257,6 +257,11 @@ export interface CompletionRequest {
     reasoning?: ReasoningConfig;
     /** Provider-side prompt caching controls. */
     cache?: PromptCacheConfig;
+    /**
+     * Skips this client's response cache for this request: `bypass` neither reads nor writes it, and
+     * `refresh` skips the read and stores the fresh answer. Either is recorded as a `bypass` outcome.
+     */
+    responseCache?: 'bypass' | 'refresh';
     /**
      * Overrides the configured capability policy for this request. `'strict'` fails on an option the
      * model cannot honor, `'warn'` drops it and records a warning, and `'off'` sends the request

package/dist/types/operations.d.ts

@@ -158,6 +158,11 @@ export interface OperationRecord<TResult = unknown> {
     lease?: OperationLease;
     /** The latest progress reported. */
     progress?: OperationProgress;
+    /**
+     * What the executor last passed to `context.heartbeat()`, such as the last row it processed. Kept
+     * across attempts, so a retry can resume from it. Must be serializable.
+     */
+    heartbeatDetails?: unknown;
     /** The result, once it succeeded. Must be serializable; bytes belong in an asset store. */
     result?: TResult;
     /** The failure, once it failed. */
@@ -168,6 +173,8 @@ export interface OperationRecord<TResult = unknown> {
     idempotencyKey?: string;
     /** Family and operation, such as `image.generate`, for filtering and metrics. */
     kind?: string;
+    /** The tenant it belongs to. A tenant-scoped store reads and lists only its own. */
+    tenantId?: string;
     /** Trace propagation headers, carried to the worker that runs it. */
     traceContext?: Record<string, string>;
     /** Application data. Must be serializable. */
@@ -212,6 +219,8 @@ export interface OperationStore<TResult = unknown> {
 export interface OperationStoreFilter {
     /** Only records whose `kind` starts with this, such as `assistant:` for the agent server's runs. */
     kindPrefix?: string;
+    /** Only records of this tenant. Postgres and SQLite read it through an index on queued work. */
+    tenantId?: string;
 }
 /** What an operation store holds, counted: the numbers a queue dashboard and an autoscaler read. */
 export interface OperationStoreStats {
@@ -300,6 +309,8 @@ export interface OperationSubmitOptions {
     id?: string;
     /** Family and operation, such as `image.generate`. */
     kind?: string;
+    /** The tenant it belongs to, recorded on the operation. */
+    tenantId?: string;
     /** Replays the operation already accepted under this key instead of starting another. */
     idempotencyKey?: string;
     /** Overrides the runner's attempt budget for this operation. */
@@ -327,8 +338,17 @@ export interface OperationContext {
     signal: AbortSignal;
     /** Publishes a progress event and persists it. */
     report(progress: OperationProgress): void;
-    /** Extends the lease immediately, for a step known to exceed the heartbeat interval. */
-    heartbeat(): Promise<void>;
+    /**
+     * Extends the lease immediately, for a step known to exceed the heartbeat interval. `details`, when
+     * given, is stored with the record and handed to the next attempt as `previousHeartbeat`, so work
+     * that fails halfway can resume where it was instead of starting over.
+     */
+    heartbeat(details?: unknown): Promise<void>;
+    /**
+     * The `details` an earlier attempt last passed to `heartbeat()`. Undefined on a first attempt,
+     * and when no attempt passed any.
+     */
+    previousHeartbeat?: unknown;
     /** Trace propagation headers from submission. */
     traceContext?: Record<string, string>;
     /** Application data from submission. */

package/dist/types/response.d.ts

@@ -72,6 +72,8 @@ export interface ResponseMeta {
     capabilityWarnings?: CapabilityWarning[];
     /** True when the response came from the response cache and no provider was called. */
     cacheHit: boolean;
+    /** What the response cache did for this request, and why. Present when the cache is enabled. */
+    cache?: CacheOutcome;
     /** Guardrails and techniques applied, such as redaction, trimming, or a retry. */
     guardrailsApplied: string[];
     /** Why the router chose the provider, and how many fallbacks were available. */
@@ -164,3 +166,21 @@ export interface NexusStream extends AsyncIterable<StreamChunk> {
     /** Stops the stream and the provider request behind it. */
     abort(): void;
 }
+/**
+ * What the response cache did for one request: `hit` (answered from it), `miss` (looked, found
+ * nothing), `stale` (found an entry that had expired), `bypass` (the request skipped the lookup), or
+ * `error` (the cache failed, and the request went to the provider as on a miss). Recorded on
+ * `response.meta.cache` and on the request's trace.
+ */
+export interface CacheOutcome {
+    /** What happened. */
+    outcome: 'hit' | 'miss' | 'stale' | 'bypass' | 'error';
+    /** Which layer answered or was asked last: the exact cache or the semantic one. */
+    layer?: 'exact' | 'semantic';
+    /** Why, in a few words, such as `no entry for this request` or the cache's error message. */
+    reason: string;
+    /** The namespace the lookup ran in, when one applies. */
+    namespace?: string;
+    /** Set when storing the response failed; the response was still returned. */
+    writeError?: string;
+}

package/dist/types/server.d.ts

@@ -334,6 +334,24 @@ export interface AssistantRunContext {
     attempt?: number;
     /** The revision serving the run, when the assistant has revisions. */
     revision?: string;
+    /**
+     * Set to draining when this replica drains and has a queue to hand work to. A graph served through
+     * `graphAssistant()` reads it as its `RunControl`: it finishes its superstep, writes its checkpoint,
+     * and stops, and another worker continues the run from there. A function assistant checks it between
+     * its own steps and throws `RunHandOffError` to hand the run off the same way.
+     */
+    control?: {
+        readonly draining: boolean;
+        readonly reason?: string;
+    };
+    /**
+     * Records how far the run got, such as the last item it finished, so the worker that continues it
+     * after a hand-off or a crash reads it as `progress` and carries on from there. Must be
+     * serializable. Extends the run's lease, as a heartbeat does.
+     */
+    saveProgress?(details: unknown): Promise<void>;
+    /** What the run saved with `saveProgress()` before this attempt, on a later attempt. */
+    progress?: unknown;
     /**
      * Records US dollars the run spent, such as a model call's cost. The amount is added to the run's
      * `cost` and to its tenant's budget; a budget that stops runs in flight cancels this one.

package/dist/types/tracing.d.ts

@@ -126,6 +126,17 @@ export interface TraceStore {
     /** Removes runs older than a cutoff, returning how many went. */
     prune?(before: string): Promise<number> | number;
 }
+/**
+ * Receives every finished run a tracer keeps, after redaction, to send somewhere else: an
+ * OpenTelemetry collector, a log pipeline, a metrics rollup. An exporter that throws or rejects is
+ * reported through the tracer's `onError` and never fails the run.
+ */
+export interface TraceExporter {
+    /** Takes one finished run. */
+    export(run: Run): Promise<void> | void;
+    /** Sends anything batched. `Tracer.flush()` calls it. */
+    flush?(): Promise<void> | void;
+}
 /**
  * What is removed from runs before they are stored, so a hidden field is never written anywhere.
  */