@noetic-tools/types 3.4.1 → 3.6.0

package/dist/schemas/workflow.d.ts

@@ -47,23 +47,32 @@ export type UntilPredicate = {
 export declare const UntilPredicateSchema: z.ZodType<UntilPredicate>;
 /** @public ESM literal enum for merge strategies. */
 export declare const MergeStrategy: {
-    readonly Last: 'last';
-    readonly First: 'first';
-    readonly Concat: 'concat';
+    readonly Last: "last";
+    readonly First: "first";
+    readonly Concat: "concat";
 };
 /** @public Named merge strategy for inParallel nodes. */
 export type MergeStrategy = (typeof MergeStrategy)[keyof typeof MergeStrategy];
 /** @public Zod schema for the named merge strategy used by `inParallel` nodes. */
 export declare const MergeStrategySchema: z.ZodEnum<{
     concat: "concat";
-    first: "first";
     last: "last";
+    first: "first";
 }>;
 declare const ModelParamsSchema: z.ZodObject<{
     temperature: z.ZodOptional<z.ZodNumber>;
     topP: z.ZodOptional<z.ZodNumber>;
     maxTokens: z.ZodOptional<z.ZodNumber>;
     stopSequences: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    serviceTier: z.ZodOptional<z.ZodEnum<{
+        readonly Auto: "auto";
+        readonly Default: "default";
+        readonly Fast: "fast";
+        readonly Flex: "flex";
+        readonly Priority: "priority";
+        readonly Scale: "scale";
+        readonly Ultrafast: "ultrafast";
+    }>>;
 }, z.core.$strip>;
 /**
  * A uniform tool entry on a `callModel` node. Every entry is an object keyed by
@@ -87,9 +96,9 @@ declare const CallModelToolEntrySchema: z.ZodObject<{
 declare const RetryPolicySchema: z.ZodObject<{
     maxAttempts: z.ZodNumber;
     backoff: z.ZodEnum<{
-        exponential: "exponential";
         fixed: "fixed";
         linear: "linear";
+        exponential: "exponential";
     }>;
     initialDelay: z.ZodNumber;
     maxDelay: z.ZodOptional<z.ZodNumber>;
@@ -97,36 +106,36 @@ declare const RetryPolicySchema: z.ZodObject<{
 declare const AcpPermissionPolicySchema: z.ZodObject<{
     default: z.ZodOptional<z.ZodEnum<{
         allow: "allow";
-        cancel: "cancel";
         deny: "deny";
+        cancel: "cancel";
     }>>;
     allow: z.ZodOptional<z.ZodArray<z.ZodObject<{
         kind: z.ZodOptional<z.ZodEnum<{
+            read: "read";
             delete: "delete";
-            edit: "edit";
+            search: "search";
             execute: "execute";
-            fetch: "fetch";
+            edit: "edit";
             move: "move";
-            other: "other";
-            read: "read";
-            search: "search";
-            switch_mode: "switch_mode";
             think: "think";
+            fetch: "fetch";
+            switch_mode: "switch_mode";
+            other: "other";
         }>>;
         title: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
     deny: z.ZodOptional<z.ZodArray<z.ZodObject<{
         kind: z.ZodOptional<z.ZodEnum<{
+            read: "read";
             delete: "delete";
-            edit: "edit";
+            search: "search";
             execute: "execute";
-            fetch: "fetch";
+            edit: "edit";
             move: "move";
-            other: "other";
-            read: "read";
-            search: "search";
-            switch_mode: "switch_mode";
             think: "think";
+            fetch: "fetch";
+            switch_mode: "switch_mode";
+            other: "other";
         }>>;
         title: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
@@ -166,14 +175,19 @@ declare const AcpMcpServerSchema: z.ZodUnion<readonly [z.ZodObject<{
 declare const AcpSessionPolicySchema: z.ZodObject<{
     reuse: z.ZodOptional<z.ZodString>;
     keepAlive: z.ZodOptional<z.ZodEnum<{
-        harness: "harness";
-        run: "run";
         step: "step";
+        run: "run";
+        harness: "harness";
     }>>;
     load: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 interface WorkflowNodeBase {
     id: string;
+    /**
+     * Whether a resumed run replays this node's recorded output. Defaults to `true`;
+     * `false` makes the node run again on every resume. See spec 23a § Identity.
+     */
+    durable?: boolean;
 }
 /**
  * A reference to a streaming `OutputCodec` for a `callModel` node's structured

package/dist/schemas/workflow.js

@@ -9,6 +9,7 @@
  * document back into live `Step` objects via the existing builders.
  */
 import { z } from 'zod';
+import { ServiceTier } from '../types/common.js';
 import { DecideQuestionsSchema, routeOutcomes } from '../types/decide.js';
 //#endregion
 //#region Until Predicate Schemas
@@ -90,6 +91,7 @@ const ModelParamsSchema = z.object({
     topP: z.number().min(0).max(1).optional(),
     maxTokens: z.number().int().positive().optional(),
     stopSequences: z.array(z.string()).optional(),
+    serviceTier: z.enum(ServiceTier).optional(),
 });
 //#endregion
 //#region Tool Entries
@@ -209,6 +211,7 @@ const AcpSessionPolicySchema = z.object({
 const WorkflowNodeRef = z.lazy(() => WorkflowNodeSchema);
 const SHARED_FIELDS = {
     id: z.string().min(1),
+    durable: z.boolean().optional(),
 };
 const OutputCodecRefSchema = z.object({
     codec: z.literal('openui'),

package/dist/types/acp.d.ts

@@ -66,9 +66,9 @@ export interface AcpTransportOptions {
 export type AcpTransportFactory = (opts: AcpTransportOptions) => Promise<AcpTransport>;
 /** @public How a permission request was resolved. */
 export declare const AcpPermissionDecision: {
-    readonly Allow: 'allow';
-    readonly Deny: 'deny';
-    readonly Cancel: 'cancel';
+    readonly Allow: "allow";
+    readonly Deny: "deny";
+    readonly Cancel: "cancel";
 };
 /** @public Union of permission decisions. */
 export type AcpPermissionDecision = (typeof AcpPermissionDecision)[keyof typeof AcpPermissionDecision];
@@ -416,11 +416,11 @@ export interface AcpAgent {
  */
 export declare const AcpKeepAlive: {
     /** Closed when the step finishes. The default. */
-    readonly Step: 'step';
+    readonly Step: "step";
     /** Kept for the rest of the root run, then closed by the harness. */
-    readonly Run: 'run';
+    readonly Run: "run";
     /** Kept until {@link AcpSessionDisposer.closeAcpSessions} is called. Nothing closes it for you. */
-    readonly Harness: 'harness';
+    readonly Harness: "harness";
 };
 /** @public Union of connection keep-alive scopes. */
 export type AcpKeepAlive = (typeof AcpKeepAlive)[keyof typeof AcpKeepAlive];

package/dist/types/common.d.ts

@@ -36,6 +36,22 @@ export interface ServerToolSpec {
  * @public
  */
 export declare function isServerToolSpec(value: unknown): value is ServerToolSpec;
+/**
+ * @public OpenRouter service tiers. `fast` is an alias for `priority`;
+ * `ultrafast` prefers ultrafast endpoints and falls back to `priority`, then
+ * default endpoints.
+ */
+export declare const ServiceTier: {
+    readonly Auto: "auto";
+    readonly Default: "default";
+    readonly Fast: "fast";
+    readonly Flex: "flex";
+    readonly Priority: "priority";
+    readonly Scale: "scale";
+    readonly Ultrafast: "ultrafast";
+};
+/** @public Union of OpenRouter service tiers. */
+export type ServiceTier = (typeof ServiceTier)[keyof typeof ServiceTier];
 /**
  * Optional parameters forwarded to the model provider during an LLM step.
  * @public
@@ -49,6 +65,8 @@ export interface ModelParams {
     maxTokens?: number;
     /** Sequences that cause the model to stop generating. */
     stopSequences?: string[];
+    /** OpenRouter service tier to request. Omit to use the provider default. */
+    serviceTier?: ServiceTier;
 }
 /** @public Aggregate token counts for an execution (input, output, total, cached). */
 export interface TokenUsage {
@@ -84,6 +102,8 @@ export interface StepMeta {
     toolCalls?: FunctionCallItem[];
     usage?: RoundUsage;
     cost?: number;
+    /** Tier the provider served an `llm` step on; see `LLMResponse.serviceTier`. */
+    serviceTier?: string;
     responseItems?: ReadonlyArray<Item>;
     /**
      * Why an ACP agent stopped its turn. Set only by `acp-agent` steps, and the
@@ -107,6 +127,12 @@ export interface LLMResponse {
      */
     rounds?: ReadonlyArray<RoundUsage>;
     cost?: number;
+    /**
+     * The tier the provider reports it served, from the last round. Absent when
+     * the provider reports none — it is never an echo of the requested tier, so
+     * a difference from `params.serviceTier` means a fallback happened.
+     */
+    serviceTier?: string;
 }
 /** @public Configuration for the LLM provider used by the agent harness. */
 export interface LlmProviderConfig {

package/dist/types/common.js

@@ -17,3 +17,17 @@ export function isServerToolSpec(value) {
     const { type } = value;
     return type === 'openrouter:web_search' || type === 'openrouter:web_fetch';
 }
+/**
+ * @public OpenRouter service tiers. `fast` is an alias for `priority`;
+ * `ultrafast` prefers ultrafast endpoints and falls back to `priority`, then
+ * default endpoints.
+ */
+export const ServiceTier = {
+    Auto: 'auto',
+    Default: 'default',
+    Fast: 'fast',
+    Flex: 'flex',
+    Priority: 'priority',
+    Scale: 'scale',
+    Ultrafast: 'ultrafast',
+};

package/dist/types/context-harness.d.ts

@@ -120,6 +120,8 @@ export interface ContextHarness {
     detachedSpawn<I, O>(step: unknown, input: I, parentCtx: Context, overrides?: ContextDetachedSpawnOverrides): DetachedHandle<O>;
     createContext(opts?: {
         parent?: Context;
+        /** Charge this context's usage to `parent` as it is spent. Default `true`. */
+        rollUpUsage?: boolean;
         items?: Item[];
         state?: unknown;
         threadId?: string;
@@ -147,7 +149,7 @@ export interface ContextHarness {
      * consumer frees a slot (back-pressure; default 30s timeout →
      * `channel_timeout`, abort → `cancelled`).
      */
-    send<T>(channel: Channel<T>, value: T, ctx: Context): Promise<void>;
+    send<T>(channel: Channel<T>, value: NoInfer<T>, ctx: Context): Promise<void>;
     recv<T>(channel: Channel<T>, ctx: Context, opts?: {
         timeout?: number;
     }): Promise<T>;

package/dist/types/context.d.ts

@@ -42,6 +42,8 @@ export interface CwdState {
 export interface RestoreContextOptions {
     /** Live parent context, when the restored execution hangs under one. */
     parent?: Context;
+    /** Charge the restored context's usage to `parent`, same as `createContext({ rollUpUsage })`. Default `true`. */
+    rollUpUsage?: boolean;
     /** Opaque per-execution state, same as `createContext({ state })`. */
     state?: unknown;
     /** Context layers for the restored context. Defaults to the harness's configured layers. */
@@ -56,6 +58,17 @@ export interface Context<TContext = ContextData, TState = unknown> {
     readonly cost: number;
     state: TState;
     readonly parent: Context<ContextData> | null;
+    /**
+     * Where this context's token/cost usage is also charged. Every charge
+     * recorded here is added to this context and then to each ancestor along
+     * this chain, so `tokens` / `cost` cover this context plus every descendant,
+     * live — whether the descendant succeeds, fails, or is abandoned.
+     *
+     * Equals `parent` unless the context was created with `rollUpUsage: false`,
+     * in which case it is `null` and the context keeps its spend to itself. When
+     * absent (a hand-rolled `Context` implementation), `parent` is used.
+     */
+    readonly usageParent?: Context<ContextData> | null;
     readonly depth: number;
     readonly span: Span;
     readonly threadId: string;
@@ -84,6 +97,15 @@ export interface Context<TContext = ContextData, TState = unknown> {
     readonly unifiedTools?: ReadonlyArray<Tool>;
     /** Runtime item schema registry active for this context. */
     readonly itemSchemas?: ItemSchemaRegistry;
+    /**
+     * Receive a value from a channel. Waits up to `opts.timeout` ms (default
+     * 30s) before rejecting with `channel_timeout`; `timeout: 0` waits with no
+     * timeout in every mode and records an `unbounded_wait` channel warning.
+     * Aborting the context rejects the wait with `cancelled`.
+     *
+     * @throws `NoeticConfigError` with code `INVALID_CHANNEL_TIMEOUT` (as a
+     * rejection) when `opts.timeout` is negative.
+     */
     recv<T>(channel: Channel<T>, opts?: {
         timeout?: number;
     }): Promise<T>;
@@ -94,7 +116,7 @@ export interface Context<TContext = ContextData, TState = unknown> {
      * (back-pressure): after the default 30s timeout it rejects with
      * `channel_timeout`, and aborting the context rejects it with `cancelled`.
      */
-    send<T>(channel: Channel<T>, value: T): Promise<void>;
+    send<T>(channel: Channel<T>, value: NoInfer<T>): Promise<void>;
     tryRecv<T>(channel: Channel<T>): T | null;
     checkpoint(): Promise<void>;
     complete<T>(value: T): void;

package/dist/types/detached.d.ts

@@ -1,8 +1,8 @@
 /** @public Lifecycle states for a detached (background) execution. */
 declare const DetachedStatus: {
-    readonly Running: 'running';
-    readonly Completed: 'completed';
-    readonly Failed: 'failed';
+    readonly Running: "running";
+    readonly Completed: "completed";
+    readonly Failed: "failed";
 };
 type DetachedStatus = (typeof DetachedStatus)[keyof typeof DetachedStatus];
 /** @public Handle returned by `detachedSpawn`, used to poll or await a background execution. */

package/dist/types/runtime.d.ts

@@ -253,6 +253,12 @@ export interface AgentHarnessContract<TParams extends Record<string, unknown> =
     }): DetachedHandle<O>;
     createContext(opts?: {
         parent?: Context;
+        /**
+         * Charge this context's token/cost usage to `parent` as it is spent, so
+         * the parent's `tokens` / `cost` include it. Default `true`; pass `false`
+         * to keep the child's spend off the parent.
+         */
+        rollUpUsage?: boolean;
         items?: Item[];
         state?: unknown;
         threadId?: string;
@@ -273,7 +279,7 @@ export interface AgentHarnessContract<TParams extends Record<string, unknown> =
      * consumer frees a slot (30s default timeout → `channel_timeout`; context
      * abort → `cancelled`).
      */
-    send<T>(channel: Channel<T>, value: T, ctx: Context): Promise<void>;
+    send<T>(channel: Channel<T>, value: NoInfer<T>, ctx: Context): Promise<void>;
     recv<T>(channel: Channel<T>, ctx: Context, opts?: {
         timeout?: number;
     }): Promise<T>;

package/dist/types/step.d.ts

@@ -30,7 +30,7 @@ export interface Snapshot {
     lastOutput: unknown;
     /** Stringified text of the most recent iteration output. */
     lastText: string;
-    /** Array of all prior iteration outputs (bounded by `maxHistorySize`). */
+    /** Prior iteration outputs, oldest first; bounded by `maxHistorySize` (default 100, oldest dropped first). */
     history: unknown[];
     /** Nesting depth of the current execution context. */
     depth: number;
@@ -44,7 +44,7 @@ export interface Snapshot {
 export interface Verdict {
     /** When true, the loop terminates after this iteration. */
     stop: boolean;
-    /** Human-readable explanation of why the loop stopped (logged in traces). */
+    /** Why the loop stopped or continued; recorded on the `loop.verdict` span event. */
     reason?: string;
     /** Feedback string injected into the next iteration's context (ignored when `stop` is true). */
     feedback?: string;
@@ -73,10 +73,43 @@ export interface SettleResult<O> {
     /** The error that caused rejection (present when `status` is `'rejected'`). */
     error?: NoeticError;
 }
+/**
+ * Combines inParallel path results into one output. `R` is the element type of
+ * `results`: `O` in `all` mode, `SettleResult<O>` in `settle` mode.
+ * @public
+ */
+export type MergeFn<TContext = ContextData, O = unknown, R = O> = (results: R[], ctx: Context<TContext>) => O;
+/**
+ * Replay controls shared by every step kind (spec 23a § Identity).
+ *
+ * A resumed execution replays a recorded step's output in place of running it.
+ * By default the ledger keys that record by the step's execution path, so replay
+ * identity is positional. These fields change that per step.
+ * @public
+ */
+export interface StepReplay<TContext = ContextData, I = unknown> {
+    /**
+     * Whether the ledger records and replays this step. Defaults to `true`. With
+     * `false` the step always runs again on resume, so its side effects and state
+     * changes happen again too. Use it for cheap orchestration steps whose work is
+     * timing-dependent (which batch a worker picked) or lives in state rather than
+     * output. Applies to this step only: its children keep their own setting.
+     * `schedule` steps are never recorded, whatever this says.
+     */
+    durable?: boolean;
+    /**
+     * Content key that replaces the positional path as this step's ledger key, so a
+     * step that may run at a different position on resume (a concurrent worker's
+     * call) still finds its own output. Two dispatches with the same key in one
+     * execution share one entry. A key that throws skips the ledger for that
+     * dispatch with a warning; it never fails the step.
+     */
+    replayKey?(input: I, ctx: Context<TContext>): string;
+}
 /** @public Discriminated union of all step kinds that can be composed into an execution tree. */
 export type Step<TContext = ContextData, I = unknown, O = unknown> = StepRunCode<TContext, I, O> | StepCallModel<TContext, I, O> | StepAcpAgent<TContext, I, O> | StepInvokeTool<TContext, I, O> | StepDecide<TContext, I, O> | StepConditional<TContext, I, O> | StepInParallel<TContext, I, O> | StepSpawn<TContext, I, O> | StepWithContext<TContext, I, O> | StepLoop<TContext, I, O> | StepSchedule<TContext, I, O>;
 /** @public A step that executes arbitrary async logic via a user-supplied function. */
-export interface StepRunCode<TContext = ContextData, I = unknown, O = unknown> {
+export interface StepRunCode<TContext = ContextData, I = unknown, O = unknown> extends StepReplay<TContext, I> {
     kind: 'runCode';
     id: string;
     execute: (input: I, ctx: Context<TContext>) => Promise<O>;
@@ -90,7 +123,7 @@ export interface StepRunCode<TContext = ContextData, I = unknown, O = unknown> {
     subprocess?: SubprocessAdapter;
 }
 /** @public A step that sends a prompt to a language model and returns its response. */
-export interface StepCallModel<TContext = ContextData, _I = unknown, O = unknown> {
+export interface StepCallModel<TContext = ContextData, I = unknown, O = unknown> extends StepReplay<TContext, I> {
     kind: 'callModel';
     id: string;
     /** Model id. Accepts either an eager string or a `(ctx) => string` getter. */
@@ -129,7 +162,7 @@ export interface StepCallModel<TContext = ContextData, _I = unknown, O = unknown
  * itself is supplied as an adapter, so the set of supported agents is open.
  * @public
  */
-export interface StepAcpAgent<TContext = ContextData, _I = unknown, O = unknown> {
+export interface StepAcpAgent<TContext = ContextData, I = unknown, O = unknown> extends StepReplay<TContext, I> {
     kind: 'acp-agent';
     id: string;
     /**
@@ -168,7 +201,7 @@ export interface StepAcpAgent<TContext = ContextData, _I = unknown, O = unknown>
     emit?: boolean | ((eventType: string, data: Record<string, unknown>) => boolean);
 }
 /** @public A step that invokes a single tool directly, bypassing the model. */
-export interface StepInvokeTool<_TContext = ContextData, I = unknown, O = unknown> {
+export interface StepInvokeTool<TContext = ContextData, I = unknown, O = unknown> extends StepReplay<TContext, I> {
     kind: 'invokeTool';
     id: string;
     tool: Tool<StandardSchemaV1<unknown, I>, StandardSchemaV1<unknown, O>>;
@@ -180,7 +213,7 @@ export interface StepInvokeTool<_TContext = ContextData, I = unknown, O = unknow
  * to it, and runs no steering hooks. See spec 32.
  * @public
  */
-export interface StepDecide<TContext = ContextData, _I = unknown, O = unknown> {
+export interface StepDecide<TContext = ContextData, I = unknown, O = unknown> extends StepReplay<TContext, I> {
     kind: 'decide';
     /** Phantom field carrying the answers type for inference. Never set at runtime. */
     readonly _answers?: O;
@@ -216,7 +249,7 @@ export type DecideStep<TContext, I, Q extends DecideQuestions> = StepDecide<TCon
  */
 export type DecideView = 'full' | 'layers' | 'none';
 /** @public A step that dynamically selects and executes one of several possible sub-steps. */
-export interface StepConditional<TContext = ContextData, I = unknown, O = unknown> {
+export interface StepConditional<TContext = ContextData, I = unknown, O = unknown> extends StepReplay<TContext, I> {
     kind: 'conditional';
     id: string;
     /**
@@ -235,7 +268,7 @@ export interface StepConditional<TContext = ContextData, I = unknown, O = unknow
 /** @public Union of inParallel step variants (`race`, `all`, `settle`) for concurrent path execution. */
 export type StepInParallel<TContext = ContextData, I = unknown, O = unknown> = StepInParallelRace<TContext, I, O> | StepInParallelAll<TContext, I, O> | StepInParallelSettle<TContext, I, O>;
 /** @public An inParallel step that returns the result of the first path to complete. */
-export interface StepInParallelRace<TContext = ContextData, I = unknown, O = unknown> {
+export interface StepInParallelRace<TContext = ContextData, I = unknown, O = unknown> extends StepReplay<TContext, I> {
     kind: 'inParallel';
     id: string;
     mode: 'race';
@@ -244,22 +277,22 @@ export interface StepInParallelRace<TContext = ContextData, I = unknown, O = unk
     _optimizable?: Step<TContext>[];
 }
 /** @public An inParallel step that runs all paths and merges their results. */
-export interface StepInParallelAll<TContext = ContextData, I = unknown, O = unknown> {
+export interface StepInParallelAll<TContext = ContextData, I = unknown, O = unknown> extends StepReplay<TContext, I> {
     kind: 'inParallel';
     id: string;
     mode: 'all';
     paths: (input: I, ctx: Context<TContext>) => Step<TContext, I, O>[];
-    merge: (results: O[], ctx: Context<TContext>) => O;
+    merge: MergeFn<TContext, O>;
     concurrency?: number;
     _optimizable?: Step<TContext>[];
 }
 /** @public An inParallel step that runs all paths and collects fulfilled/rejected outcomes. */
-export interface StepInParallelSettle<TContext = ContextData, I = unknown, O = unknown> {
+export interface StepInParallelSettle<TContext = ContextData, I = unknown, O = unknown> extends StepReplay<TContext, I> {
     kind: 'inParallel';
     id: string;
     mode: 'settle';
     paths: (input: I, ctx: Context<TContext>) => Step<TContext, I, O>[];
-    merge: (results: SettleResult<O>[], ctx: Context<TContext>) => O;
+    merge: MergeFn<TContext, O, SettleResult<O>>;
     concurrency?: number;
     _optimizable?: Step<TContext>[];
 }
@@ -269,14 +302,14 @@ export interface StepInParallelSettle<TContext = ContextData, I = unknown, O = u
  * Spawn and detachedSpawn break the inheritance chain.
  * @public
  */
-export interface StepWithContext<TContext = ContextData, I = unknown, O = unknown> {
+export interface StepWithContext<TContext = ContextData, I = unknown, O = unknown> extends StepReplay<TContext, I> {
     kind: 'withContext';
     id: string;
     child: Step<TContext, I, O>;
     context: ContextConfig | ContextLayer[];
 }
 /** @public A step that launches a child execution with its own context scope. */
-export interface StepSpawn<TContext = ContextData, I = unknown, O = unknown> {
+export interface StepSpawn<TContext = ContextData, I = unknown, O = unknown> extends StepReplay<TContext, I> {
     kind: 'spawn';
     id: string;
     child: Step<TContext, I, O>;
@@ -293,7 +326,7 @@ export interface StepSpawn<TContext = ContextData, I = unknown, O = unknown> {
  * A loop step that iterates a body step until a termination predicate is satisfied.
  * @public
  */
-export interface StepLoop<TContext = ContextData, I = unknown, O = unknown> {
+export interface StepLoop<TContext = ContextData, I = unknown, O = unknown> extends StepReplay<TContext, I> {
     kind: 'loop';
     /** Unique step identifier used in traces and error messages. */
     id: string;
@@ -303,7 +336,7 @@ export interface StepLoop<TContext = ContextData, I = unknown, O = unknown> {
     until: Until;
     /** Hard safety cap on iterations (default: 1000). */
     maxIterations?: number;
-    /** Maximum number of entries kept in the snapshot history array. */
+    /** Maximum entries kept in the snapshot history array (default: 100); oldest drop first. */
     maxHistorySize?: number;
     /** Optional channel for injecting messages into the loop mid-execution. */
     inbox?: Channel<string>;
@@ -330,7 +363,7 @@ export type ScheduleErrorPolicy = 'continue' | 'fail';
  *
  * @public
  */
-export interface StepSchedule<TContext = ContextData, I = unknown, O = unknown> {
+export interface StepSchedule<TContext = ContextData, I = unknown, O = unknown> extends StepReplay<TContext, I> {
     kind: 'schedule';
     /** Unique step identifier used in traces and error messages. */
     id: string;

package/dist/util/message-helpers.d.ts

@@ -33,5 +33,23 @@ export declare function createMessage(text: string, role: 'user' | 'developer'):
 export declare function extractAssistantText(items: ReadonlyArray<Item>): string;
 /** Naive token estimate: ~4 chars per token */
 export declare function estimateTokens(text: string): number;
-/** Accumulate token usage and cost from an LLM response onto a mutable context. */
+/** @public One unit of spend to charge to a context: a model call, or any other billed work. */
+export interface UsageCharge {
+    inputTokens: number;
+    outputTokens: number;
+    cachedTokens?: number;
+    /** USD. */
+    cost?: number;
+}
+/**
+ * @public Charge `charge` to `ctx` and to every ancestor on its `usageParent`
+ * chain. Charging at the moment of spend — rather than merging a child's
+ * totals into its parent when the child settles — is what keeps spend from a
+ * failed spawn, a fork path, or an abandoned `race` loser from being lost, and
+ * lets `until.maxCost` / `checkBudget` on an ancestor see siblings' spend live.
+ * Use this, not direct writes to `ctx.cost`, for any billed work outside a
+ * model call; a direct write stays on that one context.
+ */
+export declare function recordUsage(ctx: Context, charge: UsageCharge): void;
+/** Accumulate token usage and cost from an LLM response onto a context and its usage ancestors. */
 export declare function trackUsage(ctx: Context, response: LLMResponse): void;

package/dist/util/message-helpers.js

@@ -90,23 +90,50 @@ export function extractAssistantText(items) {
 export function estimateTokens(text) {
     return Math.ceil(text.length / 4);
 }
-/** Accumulate token usage and cost from an LLM response onto a mutable context. */
-export function trackUsage(ctx, response) {
-    if (!canTrackUsage(ctx)) {
-        return;
-    }
-    ctx.tokens.input += response.usage.inputTokens;
-    ctx.tokens.output += response.usage.outputTokens;
-    ctx.tokens.total += response.usage.inputTokens + response.usage.outputTokens;
-    // Only write `cached` when the response actually carried a figure. Defaulting
+function addCharge(ctx, charge) {
+    ctx.tokens.input += charge.inputTokens;
+    ctx.tokens.output += charge.outputTokens;
+    ctx.tokens.total += charge.inputTokens + charge.outputTokens;
+    // Only write `cached` when the charge actually carried a figure. Defaulting
     // a missing report to 0 would erase the `RoundUsage` invariant that
     // `undefined` means "this provider says nothing about caching" — callers that
     // steer on cache behaviour could no longer tell that from "nothing was
-    // cached". Mirrors the child→parent merge in execute-action.
-    if (response.usage.cachedTokens !== undefined) {
-        ctx.tokens.cached = (ctx.tokens.cached ?? 0) + response.usage.cachedTokens;
+    // cached".
+    if (charge.cachedTokens !== undefined) {
+        ctx.tokens.cached = (ctx.tokens.cached ?? 0) + charge.cachedTokens;
+    }
+    if (charge.cost) {
+        ctx.cost = ctx.cost + charge.cost;
     }
-    if (response.cost) {
-        ctx.cost = ctx.cost + response.cost;
+}
+function usageParentOf(ctx) {
+    return ctx.usageParent !== undefined ? ctx.usageParent : ctx.parent;
+}
+/**
+ * @public Charge `charge` to `ctx` and to every ancestor on its `usageParent`
+ * chain. Charging at the moment of spend — rather than merging a child's
+ * totals into its parent when the child settles — is what keeps spend from a
+ * failed spawn, a fork path, or an abandoned `race` loser from being lost, and
+ * lets `until.maxCost` / `checkBudget` on an ancestor see siblings' spend live.
+ * Use this, not direct writes to `ctx.cost`, for any billed work outside a
+ * model call; a direct write stays on that one context.
+ */
+export function recordUsage(ctx, charge) {
+    // The chain is acyclic for every ContextImpl (parents are fixed at
+    // construction); the guard only protects against a hand-rolled Context.
+    const seen = new Set();
+    for (let current = ctx; current && !seen.has(current);) {
+        seen.add(current);
+        if (canTrackUsage(current)) {
+            addCharge(current, charge);
+        }
+        current = usageParentOf(current);
     }
 }
+/** Accumulate token usage and cost from an LLM response onto a context and its usage ancestors. */
+export function trackUsage(ctx, response) {
+    recordUsage(ctx, {
+        ...response.usage,
+        cost: response.cost,
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noetic-tools/types",
-  "version": "3.4.1",
+  "version": "3.6.0",
   "type": "module",
   "description": "Foundational type contracts and primitives shared across the Noetic framework (items, LLM config, adapters, steering, errors).",
   "license": "Apache-2.0",