@noetic-tools/core 5.6.0 → 5.8.0

package/dist/builders/channel-builder.d.ts

@@ -34,3 +34,21 @@ export declare function channel<T>(name: string, opts: {
     capacity?: number;
     external?: false;
 }): Channel<T>;
+/**
+ * Creates a typed communication channel whose externality is decided at run
+ * time. Pass a literal `true`/`false` to get the narrowed return type instead.
+ *
+ * @public
+ * @param name - Channel name for identification and debugging.
+ * @param opts.schema - Zod schema used to validate every message sent through the channel.
+ * @param opts.mode - Delivery semantics: `'value'` (last-write-wins), `'queue'` (FIFO), `'topic'` (pub/sub).
+ * @param opts.capacity - Buffer size for queue mode (default: 1000). Ignored for value/topic modes.
+ * @param opts.external - `true` for an externally writable channel; omit or `false` otherwise.
+ * @returns An `ExternalChannel` when `external` is `true`, otherwise a `Channel`.
+ */
+export declare function channel<T>(name: string, opts: {
+    schema: ZodType<T>;
+    mode: 'value' | 'queue' | 'topic';
+    capacity?: number;
+    external?: boolean;
+}): Channel<T> | ExternalChannel<T>;

package/dist/builders/control-flow-builders.d.ts

@@ -1,5 +1,16 @@
 import type { ContextData } from '@noetic-tools/context';
-import type { Context, ExecuteStepFn, SettleResult, Step, StepConditional, StepInParallelAll, StepInParallelRace, StepInParallelSettle } from '@noetic-tools/types';
+import type { StepConditional, StepInParallelAll, StepInParallelRace, StepInParallelSettle } from '@noetic-tools/types';
+/**
+ * Options for `inParallel()`, one shape per mode. `merge` is required for `all`
+ * and `settle` and absent for `race`.
+ * @public
+ */
+export type InParallelOpts<TContext = ContextData, I = unknown, O = unknown> = InParallelRaceOpts<TContext, I, O> | InParallelAllOpts<TContext, I, O> | InParallelSettleOpts<TContext, I, O>;
+type InParallelRaceOpts<TContext, I, O> = Omit<StepInParallelRace<TContext, I, O>, 'kind'>;
+type InParallelAllOpts<TContext, I, O> = Omit<StepInParallelAll<TContext, I, O>, 'kind'>;
+type InParallelSettleOpts<TContext, I, O> = Omit<StepInParallelSettle<TContext, I, O>, 'kind'>;
+/** @public Options for `conditional()`. */
+export type ConditionalOpts<TContext = ContextData, I = unknown, O = unknown> = Omit<StepConditional<TContext, I, O>, 'kind'>;
 /**
  * Creates a parallel execution step that races paths and returns the first result.
  *
@@ -11,13 +22,7 @@ import type { Context, ExecuteStepFn, SettleResult, Step, StepConditional, StepI
  * @returns A `StepInParallelRace` step.
  * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
  */
-export declare function inParallel<TContext = ContextData, I = unknown, O = unknown>(opts: {
-    id: string;
-    mode: 'race';
-    paths: (input: I, ctx: Context<TContext>) => Step<TContext, I, O>[];
-    concurrency?: number;
-    _optimizable?: Step<TContext>[];
-}): StepInParallelRace<TContext, I, O>;
+export declare function inParallel<TContext = ContextData, I = unknown, O = unknown>(opts: InParallelRaceOpts<TContext, I, O>): StepInParallelRace<TContext, I, O>;
 /**
  * Creates a parallel execution step that waits for all paths and merges results.
  *
@@ -31,14 +36,7 @@ export declare function inParallel<TContext = ContextData, I = unknown, O = unkn
  * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
  * @throws `NoeticConfigError` with code `MISSING_MERGE_FUNCTION` if `merge` is not provided.
  */
-export declare function inParallel<TContext = ContextData, I = unknown, O = unknown>(opts: {
-    id: string;
-    mode: 'all';
-    paths: (input: I, ctx: Context<TContext>) => Step<TContext, I, O>[];
-    merge: (results: O[], ctx: Context<TContext>) => O;
-    concurrency?: number;
-    _optimizable?: Step<TContext>[];
-}): StepInParallelAll<TContext, I, O>;
+export declare function inParallel<TContext = ContextData, I = unknown, O = unknown>(opts: InParallelAllOpts<TContext, I, O>): StepInParallelAll<TContext, I, O>;
 /**
  * Creates a parallel execution step that waits for all paths, collecting errors as results.
  *
@@ -52,14 +50,7 @@ export declare function inParallel<TContext = ContextData, I = unknown, O = unkn
  * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
  * @throws `NoeticConfigError` with code `MISSING_MERGE_FUNCTION` if `merge` is not provided.
  */
-export declare function inParallel<TContext = ContextData, I = unknown, O = unknown>(opts: {
-    id: string;
-    mode: 'settle';
-    paths: (input: I, ctx: Context<TContext>) => Step<TContext, I, O>[];
-    merge: (results: SettleResult<O>[], ctx: Context<TContext>) => O;
-    concurrency?: number;
-    _optimizable?: Step<TContext>[];
-}): StepInParallelSettle<TContext, I, O>;
+export declare function inParallel<TContext = ContextData, I = unknown, O = unknown>(opts: InParallelSettleOpts<TContext, I, O>): StepInParallelSettle<TContext, I, O>;
 /**
  * Creates a conditional routing step that selects the next step at runtime.
  *
@@ -72,9 +63,5 @@ export declare function inParallel<TContext = ContextData, I = unknown, O = unkn
  * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
  * @throws `NoeticConfigError` with code `MISSING_ROUTE_FUNCTION` if `route` is not provided.
  */
-export declare function conditional<TContext = ContextData, I = unknown, O = unknown>(opts: {
-    id: string;
-    route: (input: I, ctx: Context<TContext>, run: ExecuteStepFn) => Step<TContext, I, O> | null | Promise<Step<TContext, I, O> | null>;
-    _optimizable?: Step<TContext>[];
-    _rebuild?: (children: Step<TContext>[]) => StepConditional<TContext, I, O>;
-}): StepConditional<TContext, I, O>;
+export declare function conditional<TContext = ContextData, I = unknown, O = unknown>(opts: ConditionalOpts<TContext, I, O>): StepConditional<TContext, I, O>;
+export {};

package/dist/builders/decide-builders.d.ts

@@ -1,6 +1,6 @@
-import type { AnsweredAll, CaseKeyOf, Context, ContextData, DecideQuestions, DecideStep, DecideView, Lazy, ProjectionPolicy, Step, StepConditional } from '@noetic-tools/types';
+import type { AnsweredAll, CaseKeyOf, Context, ContextData, DecideQuestions, DecideStep, DecideView, Lazy, ProjectionPolicy, Step, StepConditional, StepReplay } from '@noetic-tools/types';
 /** @public Options for `decide()`. */
-export interface StepDecideOpts<TContext, Q extends DecideQuestions> {
+export interface StepDecideOpts<TContext, Q extends DecideQuestions, I = unknown> extends StepReplay<TContext, I> {
     id: string;
     /** Decision model id. Falls back to `harness.config.decisionModel`. */
     model?: Lazy<string, TContext>;
@@ -38,7 +38,7 @@ type OnlyKeys<Cases, Keys extends PropertyKey> = {
  * @public `routeSwitch` options that route by one question. `cases` needs exactly
  * one step per outcome; refusals and low-confidence answers take `uncertain`.
  */
-export interface RouteSwitchByKeyOpts<TContext, Q extends DecideQuestions, K extends keyof Q & string, Cases extends Record<CaseKeyOf<Q[K]>, CaseStep>, U extends CaseStep> {
+export interface RouteSwitchByKeyOpts<TContext, Q extends DecideQuestions, K extends keyof Q & string, Cases extends Record<CaseKeyOf<Q[K]>, CaseStep>, U extends CaseStep> extends StepReplay<TContext> {
     id: string;
     decide: DecideStep<TContext, unknown, Q>;
     on: K;
@@ -49,7 +49,7 @@ export interface RouteSwitchByKeyOpts<TContext, Q extends DecideQuestions, K ext
     uncertain: U;
 }
 /** @public `routeSwitch` options that combine answers in a function; `default` catches the rest. */
-export interface RouteSwitchByFunctionOpts<TContext, Q extends DecideQuestions, C extends string, Cases extends Partial<Record<C, CaseStep>>, D extends CaseStep, U extends CaseStep> {
+export interface RouteSwitchByFunctionOpts<TContext, Q extends DecideQuestions, C extends string, Cases extends Partial<Record<C, CaseStep>>, D extends CaseStep, U extends CaseStep> extends StepReplay<TContext> {
     id: string;
     decide: DecideStep<TContext, unknown, Q>;
     /** Receives answers with refusals already handled. */
@@ -71,7 +71,7 @@ export interface RouteSwitchByFunctionOpts<TContext, Q extends DecideQuestions,
  * @throws `NoeticConfigError` `EMPTY_STEP_ID`, `MISSING_MODEL` (empty eager model),
  *   `INVALID_DECIDE_QUESTIONS`, or `INVALID_DECIDE_SAMPLES`.
  */
-export declare function decide<const Q extends DecideQuestions, TContext = ContextData, I = unknown>(opts: StepDecideOpts<TContext, Q>): DecideStep<TContext, I, Q>;
+export declare function decide<const Q extends DecideQuestions, TContext = ContextData, I = unknown>(opts: StepDecideOpts<TContext, Q, I>): DecideStep<TContext, I, Q>;
 /**
  * Creates a conditional step that runs a decide step and routes the original input to
  * the case its answers pick. The output type is the union of every case's

package/dist/builders/decide-builders.js

@@ -59,6 +59,8 @@ export function routeSwitch(opts) {
         minConfidence: 'minConfidence' in opts ? opts.minConfidence : undefined,
         uncertain: opts.uncertain,
         default: 'default' in opts ? opts.default : undefined,
+        durable: opts.durable,
+        replayKey: opts.replayKey,
     });
 }
 /**
@@ -84,6 +86,8 @@ function buildSwitch(plan) {
     ];
     return conditional({
         id: plan.id,
+        durable: plan.durable,
+        replayKey: plan.replayKey,
         route: async (input, ctx, run) => {
             const answers = frameworkCast(await run(plan.decide, input, ctx));
             const picked = pick(answers);

package/dist/builders/every.d.ts

@@ -1,5 +1,5 @@
 import type { ContextData } from '@noetic-tools/context';
-import type { Channel, ScheduleErrorPolicy, Step, StepSchedule } from '@noetic-tools/types';
+import type { Channel, ScheduleErrorPolicy, Step, StepReplay, StepSchedule } from '@noetic-tools/types';
 /**
  * Configuration options accepted by the `schedule()` builder, excluding the `kind`
  * discriminant. `schedule()` schedules a body step on a fixed-interval, optionally
@@ -7,7 +7,7 @@ import type { Channel, ScheduleErrorPolicy, Step, StepSchedule } from '@noetic-t
  *
  * @public
  */
-export interface ScheduleOptions<TContext = ContextData, I = unknown, O = unknown> {
+export interface ScheduleOptions<TContext = ContextData, I = unknown, O = unknown> extends StepReplay<TContext, I> {
     /** Unique step identifier used in traces and error messages. */
     id: string;
     /** Body step executed on each iteration. */

package/dist/builders/every.js

@@ -57,6 +57,8 @@ export function schedule(opts) {
         inbox: opts.inbox,
         onError: opts.onError ?? 'continue',
         jitter: opts.jitter ?? 0,
+        durable: opts.durable,
+        replayKey: opts.replayKey,
     };
     getDefaultRegistrar().register(built);
     return built;

package/dist/builders/loop-builder.d.ts

@@ -10,7 +10,7 @@ export type LoopConfig<TContext = ContextData, I = unknown, O = unknown> = Omit<
  * @param opts.steps - Array of steps to execute sequentially on each iteration.
  * @param opts.until - Termination predicate `(snapshot) => Verdict | Promise<Verdict>` evaluated after each iteration.
  * @param opts.maxIterations - Hard safety cap on iterations (default: 1000).
- * @param opts.maxHistorySize - Maximum entries kept in the snapshot history array.
+ * @param opts.maxHistorySize - Maximum entries kept in the snapshot history array (default: 100); oldest drop first.
  * @param opts.inbox - Optional channel for injecting messages into the loop mid-execution.
  * @param opts.parkTimeout - Ms to wait on inbox before the loop parks itself (default: 0).
  * @param opts.prepareNext - Transforms `(output, verdict, ctx)` into the next iteration's input.

package/dist/builders/loop-builder.js

@@ -8,7 +8,7 @@ import { getDefaultRegistrar } from '../types/step-registrar.js';
  * @param opts.steps - Array of steps to execute sequentially on each iteration.
  * @param opts.until - Termination predicate `(snapshot) => Verdict | Promise<Verdict>` evaluated after each iteration.
  * @param opts.maxIterations - Hard safety cap on iterations (default: 1000).
- * @param opts.maxHistorySize - Maximum entries kept in the snapshot history array.
+ * @param opts.maxHistorySize - Maximum entries kept in the snapshot history array (default: 100); oldest drop first.
  * @param opts.inbox - Optional channel for injecting messages into the loop mid-execution.
  * @param opts.parkTimeout - Ms to wait on inbox before the loop parks itself (default: 0).
  * @param opts.prepareNext - Transforms `(output, verdict, ctx)` into the next iteration's input.

package/dist/builders/provide-builder.d.ts

@@ -1,5 +1,5 @@
 import type { ContextConfig, ContextData, ContextLayer } from '@noetic-tools/context';
-import type { Step, StepWithContext } from '@noetic-tools/types';
+import type { Step, StepReplay, StepWithContext } from '@noetic-tools/types';
 /**
  * Creates a provide step that attaches context layers to its child without creating an isolated context.
  * Like React's Context.Provider — layers are available to all descendant steps.
@@ -17,4 +17,4 @@ export declare function withContext<TContext = ContextData, I = unknown, O = unk
     id: string;
     child: Step<TContext, I, O>;
     context: ContextConfig | ContextLayer[];
-}): StepWithContext<TContext, I, O>;
+} & StepReplay<TContext, I>): StepWithContext<TContext, I, O>;

package/dist/builders/provide-builder.js

@@ -41,6 +41,8 @@ export function withContext(opts) {
         id: opts.id,
         child: opts.child,
         context: layers,
+        durable: opts.durable,
+        replayKey: opts.replayKey,
     };
     getDefaultRegistrar().register(built);
     return built;

package/dist/builders/spawn-builder.d.ts

@@ -1,6 +1,6 @@
 import type { ContextConfig, ContextData, ContextLayer } from '@noetic-tools/context';
-import type { Step, StepSpawn, SubprocessAdapter } from '@noetic-tools/types';
-interface SpawnOpts<TContext, I, O> {
+import type { Step, StepReplay, StepSpawn, SubprocessAdapter } from '@noetic-tools/types';
+interface SpawnOpts<TContext, I, O> extends StepReplay<TContext, I> {
     id: string;
     child: Step<TContext, I, O>;
     context?: ContextConfig | ContextLayer[];

package/dist/builders/spawn-builder.js

@@ -40,6 +40,8 @@ export function spawn(opts) {
         context: opts.context,
         timeout: opts.timeout,
         subprocess: opts.subprocess,
+        durable: opts.durable,
+        replayKey: opts.replayKey,
     };
     getDefaultRegistrar().register(built);
     // Ensure the child is addressable by id — builders for `runCode`/`callModel`/`invokeTool`

package/dist/builders/step-builders.d.ts

@@ -1,6 +1,6 @@
 import type { ContextData } from '@noetic-tools/context';
-import type { AcpAgent, AcpClientCapabilityConfig, AcpContentBlock, AcpMcpServer, AcpPermissionHandler, AcpPermissionPolicy, AcpSessionPolicy, Context, Lazy, ModelParams, OutputCodec, RetryPolicy, ServerToolSpec, StandardSchemaV1, StepAcpAgent, StepCallModel, StepInvokeTool, StepRunCode, SubprocessAdapter, Tool } from '@noetic-tools/types';
-export interface RunCodeOpts<TContext, I, O> {
+import type { AcpAgent, AcpClientCapabilityConfig, AcpContentBlock, AcpMcpServer, AcpPermissionHandler, AcpPermissionPolicy, AcpSessionPolicy, Context, Lazy, ModelParams, OutputCodec, RetryPolicy, ServerToolSpec, StandardSchemaV1, StepAcpAgent, StepCallModel, StepInvokeTool, StepReplay, StepRunCode, SubprocessAdapter, Tool } from '@noetic-tools/types';
+export interface RunCodeOpts<TContext, I, O> extends StepReplay<TContext, I> {
     id: string;
     execute: (input: I, ctx: Context<TContext>) => Promise<O>;
     retry?: RetryPolicy;
@@ -11,7 +11,7 @@ export interface RunCodeOpts<TContext, I, O> {
      */
     subprocess?: SubprocessAdapter;
 }
-export interface CallModelOpts<TContext, O> {
+export interface CallModelOpts<TContext, O, I = unknown> extends StepReplay<TContext, I> {
     id: string;
     /** Model id. Eager string or `(ctx) => string` getter (resolved at step execution). */
     model: Lazy<string, TContext>;
@@ -33,12 +33,12 @@ export interface CallModelOpts<TContext, O> {
     params?: ModelParams;
     emit?: boolean | ((eventType: string, data: Record<string, unknown>) => boolean);
 }
-export interface InvokeToolOpts<I, O> {
+export interface InvokeToolOpts<I, O, TContext = ContextData> extends StepReplay<TContext, I> {
     id: string;
     tool: Tool<StandardSchemaV1<unknown, I>, StandardSchemaV1<unknown, O>>;
     args?: Partial<I>;
 }
-export interface StepAcpAgentOpts<TContext, O> {
+export interface StepAcpAgentOpts<TContext, O, I = unknown> extends StepReplay<TContext, I> {
     id: string;
     /** An ACP agent adapter, e.g. `claudeCode()` from `@noetic-tools/acp`. Eager or `(ctx) => AcpAgent`. */
     agent: Lazy<AcpAgent, TContext>;
@@ -101,7 +101,7 @@ export declare function runCode<TContext = ContextData, I = unknown, O = unknown
  * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
  * @throws `NoeticConfigError` with code `MISSING_MODEL` if an eager `model` string is empty. Function-form models are validated at step execution.
  */
-export declare function callModel<TContext = ContextData, I = unknown, O = unknown>(opts: CallModelOpts<TContext, O>): StepCallModel<TContext, I, O>;
+export declare function callModel<TContext = ContextData, I = unknown, O = unknown>(opts: CallModelOpts<TContext, O, I>): StepCallModel<TContext, I, O>;
 /**
  * Creates a tool execution step that invokes a typed tool definition.
  *
@@ -114,7 +114,7 @@ export declare function callModel<TContext = ContextData, I = unknown, O = unkno
  * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
  * @throws `NoeticConfigError` with code `MISSING_TOOL` if `tool` is not provided.
  */
-export declare function invokeTool<TContext = ContextData, I = unknown, O = unknown>(opts: InvokeToolOpts<I, O>): StepInvokeTool<TContext, I, O>;
+export declare function invokeTool<TContext = ContextData, I = unknown, O = unknown>(opts: InvokeToolOpts<I, O, TContext>): StepInvokeTool<TContext, I, O>;
 /**
  * The ACP step builder namespace. Unlike the flattened base builders
  * (`runCode`, `callModel`, `invokeTool`), the coding-agent builder stays
@@ -140,5 +140,5 @@ export declare const step: {
      * @returns A `StepAcpAgent`, auto-registered in the step registry.
      * @throws `NoeticConfigError` `EMPTY_STEP_ID` / `MISSING_ACP_AGENT` / `MISSING_PROMPT`.
      */
-    acpAgent<TContext = ContextData, I = unknown, O = unknown>(opts: StepAcpAgentOpts<TContext, O>): StepAcpAgent<TContext, I, O>;
+    acpAgent<TContext = Readonly<Record<string, Record<string, unknown>>>, I = unknown, O = unknown>(opts: StepAcpAgentOpts<TContext, O, I>): StepAcpAgent<TContext, I, O>;
 };

package/dist/builders/workflow-hydrator.js

@@ -767,7 +767,12 @@ export function hydrateNode(node, ctx) {
             hint: `Supported kinds: ${Object.keys(NODE_HYDRATORS).join(', ')}.`,
         });
     }
-    return hydrator(node, ctx);
+    const hydrated = hydrator(node, ctx);
+    // Set in place rather than copied: builders register the step object itself.
+    if (node.durable !== undefined) {
+        hydrated.durable = node.durable;
+    }
+    return hydrated;
 }
 /**
  * Hydrates a complete `WorkflowDocument` into a live `Step` tree.

package/dist/harness/agent-harness.d.ts

@@ -3,6 +3,7 @@ import { AcpSessionStore } from '../runtime/acp-session-store.js';
 import type { LayerStateStore, RecallCache } from './deps/context.js';
 import type { DetachedSpawnOverrides } from './deps/interpreter.js';
 import type { CheckpointStore, EventBroadcaster, RestoreCheckpointOptions, StepLedgerRetention, StepLedgerStore } from './deps/runtime.js';
+import { ChannelStore } from './deps/runtime.js';
 import type { AcpLiveSession, AcpSessionInfo, AgentConfig, AgentHarnessContract, AgentHooks, CallModelRequest, Channel, ChannelHandle, Context, ContextCacheConfig, ContextCacheStore, ContextData, ContextLayer, CwdState, DecideRequest, DecideResponse, DecisionRecord, DeliveryMode, DetachedHandle, ExecuteInput, ExecuteOptions, ExternalChannel, FsAdapter, HarnessResponse, HarnessStatus, Item, ItemSchemaConfig, LLMResponse, LlmProviderConfig, ProjectionPolicy, RecallLayerOutput, RecallOptions, SessionScope, SessionUsage, ShellAdapter, Span, SteeringDecision, Step, StorageAdapter, StreamEvent, StreamingItem, SubprocessAdapter, Tool, TraceExporter, ZodType } from './deps/types.js';
 export { createStreamIdleWatchdog } from './model-call.js';
 /**
@@ -163,9 +164,13 @@ export declare class AgentHarness<TParams extends Record<string, unknown> = Reco
     private readonly decideOverride?;
     /** Model id → whether it answers natively as a decision model. */
     private readonly decisionModels;
-    private readonly channelStore;
-    /** Re-entrant `run()` depth per root context id — see `executeClosingChannels`. */
-    private readonly rootRunDepth;
+    /** @internal Channel state; read by the checkpoint functions. */
+    readonly channelStore: ChannelStore;
+    /**
+     * Root contexts with a `run()` in flight, keyed by id, with their
+     * re-entrant run depth — see `executeClosingChannels`.
+     */
+    private readonly liveRoots;
     private readonly callModelOverride?;
     private readonly defaultDeliveryMode;
     private readonly sessions;
@@ -279,6 +284,8 @@ export declare class AgentHarness<TParams extends Record<string, unknown> = Reco
     detachedSpawn<I, O>(s: Step<ContextData, I, O>, input: I, parentCtx: Context, overrides?: DetachedSpawnOverrides): 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;
@@ -294,11 +301,11 @@ export declare class AgentHarness<TParams extends Record<string, unknown> = Reco
         cwdInit?: string;
         _broadcaster?: EventBroadcaster;
     }): Context;
-    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>;
-    tryRecv<T>(channel: Channel<T>, _ctx: Context): T | null;
+    tryRecv<T>(channel: Channel<T>, ctx: Context): T | null;
     getChannelHandle<T>(channel: ExternalChannel<T>, executionId: string): ChannelHandle<T>;
     getChannelStream<T>(channel: ExternalChannel<T>, executionId: string): AsyncIterable<T>;
     /** Resolves layer-provided tools and merges with step tools into ctx.unifiedTools. */
@@ -405,6 +412,14 @@ export declare class AgentHarness<TParams extends Record<string, unknown> = Reco
      * under cancellation (spec 09, Cancellation item 5).
      */
     private teardownCancelledContext;
+    /**
+     * Channel state is shared by every root on this harness, so a channel
+     * warning is recorded as a `channel.warning` event on each live root's
+     * span (spec 10). A root span counts only if it will reach the trace
+     * exporter — a harness span (`SpanImpl`) with a real exporter configured.
+     * With no such span the warning goes to the console, so it is never lost.
+     */
+    private recordChannelWarning;
     createSpan(name: string, parent: Span | null): Span;
     getLayerState<T>(executionId: string, layerId: string): T | undefined;
     setLayerState<T>(executionId: string, layerId: string, state: T): void;

package/dist/harness/agent-harness.js

@@ -1,4 +1,5 @@
 import { frameworkCast, ItemSchemaRegistry, NoeticConfigError } from '@noetic-tools/types';
+import { NoeticEvent } from '../observability/genai-attributes.js';
 import { SpanImpl } from '../observability/span-impl.js';
 import { NoopExporter } from '../observability/trace-exporter.js';
 import { AcpSessionStore } from '../runtime/acp-session-store.js';
@@ -6,7 +7,7 @@ import { callDecide } from './decide-call.js';
 import { createInMemoryFsAdapter, createInMemoryShellAdapter, createInMemorySubprocessAdapter, OpenRouter, OpenRouterSdk, } from './deps/adapters.js';
 import { afterModelCallLayers, allocateBudgets, assembleView, beforeToolCallLayers, completeLayers, contextToExecCtx, createContextCacheStore, createLayerStateStore, createRecallCache, DEFAULT_PROJECTION, disposeLayers, executeRerender, initLayers, notifyDecision, projectHistoryLayers, recallLayers, recallLayersAtomic, recallLayersEventual, resolveLayerTools, runAppendPipeline, storeLayers, } from './deps/context.js';
 import { collectAllTools, deduplicateTools, dispatchStepThroughAdapter, execute, prepareBandedView, } from './deps/interpreter.js';
-import { buildItemStream, ChannelStore, ContextImpl, captureCheckpoint, clearCheckpoint, collectContextTree, createInMemoryStorage, createStepLedgerStore, filterReasoningStream, filterTextStream, resolveStepLedgerRetention, restoreFromCheckpoint, SessionRunner, StepLedger, snapshotCwdState, } from './deps/runtime.js';
+import { buildItemStream, ChannelStore, ContextImpl, captureCheckpoint, clearCheckpoint, collectContextTree, createInMemoryStorage, createStepLedgerStore, filterReasoningStream, filterTextStream, resolveStepLedgerRetention, restoreFromCheckpoint, rootIdOf, SessionRunner, StepLedger, snapshotCwdState, warnToConsole, } from './deps/runtime.js';
 import { SteeringAction } from './deps/types.js';
 import { AgentHarnessModelCaller } from './model-call.js';
 export { createStreamIdleWatchdog } from './model-call.js';
@@ -202,9 +203,13 @@ export class AgentHarness {
     decideOverride;
     /** Model id → whether it answers natively as a decision model. */
     decisionModels = new Map();
+    /** @internal Channel state; read by the checkpoint functions. */
     channelStore;
-    /** Re-entrant `run()` depth per root context id — see `executeClosingChannels`. */
-    rootRunDepth = new Map();
+    /**
+     * Root contexts with a `run()` in flight, keyed by id, with their
+     * re-entrant run depth — see `executeClosingChannels`.
+     */
+    liveRoots = new Map();
     callModelOverride;
     defaultDeliveryMode;
     sessions = new Map();
@@ -317,7 +322,9 @@ export class AgentHarness {
         this.decisionsClient = opts._testCallModel
             ? undefined
             : createDecisionsClient(opts.callModelDefaults);
-        this.channelStore = new ChannelStore();
+        this.channelStore = new ChannelStore({
+            onWarning: (warning) => this.recordChannelWarning(warning),
+        });
         this.traceExporter = opts.traceExporter ?? new NoopExporter();
         this.layerStateStore =
             storageEnv?.layerStateStore ??
@@ -589,23 +596,25 @@ export class AgentHarness {
         if (ctx.parent !== null) {
             return execute(s, input, ctx);
         }
-        const depth = this.rootRunDepth.get(ctx.id) ?? 0;
-        if (depth === 0) {
+        const live = this.liveRoots.get(ctx.id);
+        if (!live) {
             // A restored or sequentially re-run root context reuses its id — clear
             // any closure from a previous completion so its channels work again.
             this.channelStore.openExecution(ctx.id);
         }
-        this.rootRunDepth.set(ctx.id, depth + 1);
+        const entry = live ?? {
+            ctx,
+            depth: 0,
+        };
+        entry.depth += 1;
+        this.liveRoots.set(ctx.id, entry);
         try {
             return await execute(s, input, ctx);
         }
         finally {
-            const remaining = (this.rootRunDepth.get(ctx.id) ?? 1) - 1;
-            if (remaining > 0) {
-                this.rootRunDepth.set(ctx.id, remaining);
-            }
-            else {
-                this.rootRunDepth.delete(ctx.id);
+            entry.depth -= 1;
+            if (entry.depth <= 0) {
+                this.liveRoots.delete(ctx.id);
                 this.channelStore.closeExecution(ctx.id);
                 await this.acpSessions.closeOwnedBy(ctx.id);
             }
@@ -688,6 +697,7 @@ export class AgentHarness {
         // Internal sender: back-pressured on full queue channels. The calling
         // context's abort signal rejects a parked send with 'cancelled'.
         const signal = ctx instanceof ContextImpl ? ctx.abortSignal : undefined;
+        this.channelStore.claim(channel, rootIdOf(ctx));
         return this.channelStore.send(channel, value, {
             signal,
         });
@@ -696,9 +706,11 @@ export class AgentHarness {
         // Wire the calling context's abort signal so ctx.abort() rejects a
         // pending recv with { kind: 'cancelled' } instead of hanging.
         const signal = ctx instanceof ContextImpl ? ctx.abortSignal : undefined;
+        this.channelStore.claim(channel, rootIdOf(ctx));
         return this.channelStore.recv(channel, opts?.timeout, signal);
     }
-    tryRecv(channel, _ctx) {
+    tryRecv(channel, ctx) {
+        this.channelStore.claim(channel, rootIdOf(ctx));
         return this.channelStore.tryRecv(channel);
     }
     getChannelHandle(channel, executionId) {
@@ -1003,6 +1015,29 @@ export class AgentHarness {
             ...layers,
         ], ctx);
     }
+    /**
+     * Channel state is shared by every root on this harness, so a channel
+     * warning is recorded as a `channel.warning` event on each live root's
+     * span (spec 10). A root span counts only if it will reach the trace
+     * exporter — a harness span (`SpanImpl`) with a real exporter configured.
+     * With no such span the warning goes to the console, so it is never lost.
+     */
+    recordChannelWarning(warning) {
+        const traced = this.traceExporter instanceof NoopExporter
+            ? []
+            : [
+                ...this.liveRoots.values(),
+            ].filter(({ ctx }) => ctx.span instanceof SpanImpl);
+        if (traced.length === 0) {
+            warnToConsole(warning);
+            return;
+        }
+        for (const { ctx } of traced) {
+            ctx.span.addEvent(NoeticEvent.CHANNEL_WARNING, {
+                ...warning,
+            });
+        }
+    }
     createSpan(name, parent) {
         return new SpanImpl(name, parent);
     }

package/dist/harness/deps/runtime.d.ts

@@ -1,5 +1,6 @@
-export { ChannelStore } from '../../runtime/channel-store.js';
-export { ContextImpl, collectContextTree } from '../../runtime/context-impl.js';
+export type { ChannelWarning } from '../../runtime/channel-store.js';
+export { ChannelStore, warnToConsole } from '../../runtime/channel-store.js';
+export { ContextImpl, collectContextTree, rootIdOf } from '../../runtime/context-impl.js';
 export { snapshotCwdState } from '../../runtime/cwd-helpers.js';
 export type { CheckpointStore } from '../../runtime/durable/index.js';
 export type { RestoreCheckpointOptions } from '../../runtime/durable/harness-checkpoints.js';

package/dist/harness/deps/runtime.js

@@ -1,5 +1,5 @@
-export { ChannelStore } from '../../runtime/channel-store.js';
-export { ContextImpl, collectContextTree } from '../../runtime/context-impl.js';
+export { ChannelStore, warnToConsole } from '../../runtime/channel-store.js';
+export { ContextImpl, collectContextTree, rootIdOf } from '../../runtime/context-impl.js';
 export { snapshotCwdState } from '../../runtime/cwd-helpers.js';
 export { captureCheckpoint, clearCheckpoint, restoreFromCheckpoint, } from '../../runtime/durable/harness-checkpoints.js';
 export { createStepLedgerStore, resolveStepLedgerRetention, StepLedger, } from '../../runtime/durable/step-ledger.js';

package/dist/harness/model-call.js

@@ -386,6 +386,7 @@ export class AgentHarnessModelCaller {
         // the assembled view was cached (see `noteCacheOutcome`).
         const rounds = [];
         let totalCost = 0;
+        let servedTier;
         const conversationInput = itemsToInput(prepared.remaining);
         const textFormat = request.outputSchema
             ? buildTextFormat(request.outputSchema, request.outputJsonSchema)
@@ -434,6 +435,9 @@ export class AgentHarnessModelCaller {
                 temperature: request.params?.temperature,
                 maxOutputTokens: request.params?.maxTokens,
                 topP: request.params?.topP,
+                // The agent's bundled SDK types an older tier list (no `fast` or
+                // `ultrafast`); the field is an open enum, so newer tiers pass through.
+                serviceTier: frameworkCast(request.params?.serviceTier),
                 ...(textFormat
                     ? {
                         text: textFormat,
@@ -524,6 +528,7 @@ export class AgentHarnessModelCaller {
             totalUsage.outputTokens += roundUsage.outputTokens;
             totalUsage.cachedTokens += roundUsage.cachedTokens ?? 0;
             totalCost += roundCost;
+            servedTier = sdkResponse.serviceTier ?? undefined;
             allItems.push(...roundItems);
             const functionCalls = roundItems.filter(isFunctionCall);
             if (functionCalls.length === 0 || !request.tools) {
@@ -563,6 +568,11 @@ export class AgentHarnessModelCaller {
             },
             rounds,
             cost: totalCost > 0 ? totalCost : undefined,
+            ...(servedTier
+                ? {
+                    serviceTier: servedTier,
+                }
+                : {}),
         };
     }
     injectBetweenRoundMessages(ctx, conversationInput, round, emitIfAllowed) {

package/dist/index.d.ts

@@ -15,6 +15,8 @@ export { channel } from './builders/channel-builder.js';
 /** @public */
 export { context } from './builders/context-builder.js';
 /** @public */
+export type { ConditionalOpts, InParallelOpts } from './builders/control-flow-builders.js';
+/** @public */
 export { conditional, inParallel } from './builders/control-flow-builders.js';
 /** @public */
 export { decide, routeSwitch } from './builders/decide-builders.js';
@@ -82,9 +84,9 @@ export type { DecisionsHistoryConfig, DecisionsHistoryLayer, DecisionsHistorySta
 /** @public */
 export { DECISION_PROJECTION, decisionsHistoryLayer, filesystem, findFunctionCall, history, instructions, observations, PlanPhase, PlanStyle, plan, scratchpad, steering, storageGetMany, stripUnresolvedToolCalls, taskState, temporal, toolCalls, } from '@noetic-tools/context';
 /** @public */
-export { createMessage, estimateTokens } from '@noetic-tools/types';
+export { createMessage, estimateTokens, recordUsage } from '@noetic-tools/types';
 /** @public */
-export { GenAI, NoeticAttr, ToolAttr } from './observability/genai-attributes.js';
+export { GenAI, NoeticAttr, NoeticEvent, ToolAttr } from './observability/genai-attributes.js';
 /** @public */
 export { InMemoryExporter, NoopExporter } from './observability/trace-exporter.js';
 /** @public */
@@ -113,9 +115,9 @@ export { MergeStrategySchema, UntilPredicateSchema, validateWorkflow, WorkflowDo
 export type { Channel, ChannelHandle, ExternalChannel } from '@noetic-tools/types';
 /** @public */
 /** @public */
-export type { InferSchemaInput, InferSchemaOutput, InputSchemaConfig, LLMResponse, LlmProviderConfig, ModelParams, RetryPolicy, RoundUsage, SchemaValidationFailure, SchemaValidationResult, SchemaValidationSuccess, ServerToolSpec, StandardJSONSchemaV1, StandardSchemaV1, StepMeta, TokenUsage, Tool, ToolContextDeclaration, } from '@noetic-tools/types';
+export type { InferSchemaInput, InferSchemaOutput, InputSchemaConfig, LLMResponse, LlmProviderConfig, ModelParams, RetryPolicy, RoundUsage, SchemaValidationFailure, SchemaValidationResult, SchemaValidationSuccess, ServerToolSpec, StandardJSONSchemaV1, StandardSchemaV1, StepMeta, TokenUsage, Tool, ToolContextDeclaration, UsageCharge, } from '@noetic-tools/types';
 /** @public */
-export { isServerToolSpec, isStandardJsonSchema, isZodSchema, standardIssuesToZodError, validateSchema, } from '@noetic-tools/types';
+export { isServerToolSpec, isStandardJsonSchema, isZodSchema, ServiceTier, standardIssuesToZodError, validateSchema, } from '@noetic-tools/types';
 /** @public */
 /** @public */
 /** @public */
@@ -129,9 +131,9 @@ export { DetachedStatus } from '@noetic-tools/types';
 /** @public */
 export type { EmbedFn } from './types/embed.js';
 /** @public */
-export type { CheckpointSnapshot, CwdSnapshot, FrontierFrame, ItemLogSnapshot, PendingAskUserSnapshot, } from './types/checkpoint.js';
+export type { ChannelSnapshot, CheckpointSnapshot, CwdSnapshot, FrontierFrame, ItemLogSnapshot, PendingAskUserSnapshot, } from './types/checkpoint.js';
 /** @public */
-export { CheckpointSchemaVersion, CheckpointSnapshotSchema, CwdSnapshotSchema, FrontierFrameSchema, ItemLogSnapshotSchema, PendingAskUserSnapshotSchema, } from './types/checkpoint.js';
+export { ChannelSnapshotSchema, CheckpointSchemaVersion, CheckpointSnapshotSchema, CwdSnapshotSchema, FrontierFrameSchema, ItemLogSnapshotSchema, PendingAskUserSnapshotSchema, } from './types/checkpoint.js';
 /** @public */
 export type { NoeticError } from '@noetic-tools/types';
 /** @public */
@@ -153,7 +155,7 @@ export type { AfterModelCallParams, AfterModelCallResult, BeforeToolCallParams,
 /** @public */
 export { LedgerEntryKind, SteeringAction } from '@noetic-tools/types';
 /** @public */
-export type { ExecuteStepFn, SettleResult, Snapshot, Step, StepAcpAgent, StepCallModel, StepConditional, StepInParallel, StepInParallelAll, StepInParallelRace, StepInParallelSettle, StepInvokeTool, StepLoop, StepRunCode, StepSpawn, StepWithContext, Until, Verdict, } from '@noetic-tools/types';
+export type { ExecuteStepFn, MergeFn, SettleResult, Snapshot, Step, StepAcpAgent, StepCallModel, StepConditional, StepInParallel, StepInParallelAll, StepInParallelRace, StepInParallelSettle, StepInvokeTool, StepLoop, StepReplay, StepRunCode, StepSpawn, StepWithContext, Until, Verdict, } from '@noetic-tools/types';
 /** @public */
 export type { AnsweredAll, AnswerFor, BooleanAnswer, BooleanQuestion, CaseKeyOf, ChoiceAnswer, ChoiceQuestion, ChoiceValues, DecideAnswer, DecideAnswers, DecideQuestion, DecideQuestions, DecideRequest, DecideResponse, DecideStatePart, DecideStep, DecideView, DecisionMeta, DecisionRecord, DecisionSource, LevelLabels, OnDecisionParams, RecallOptions, ScoreAnswer, ScoreLevel, ScoreQuestion, StepDecide, } from '@noetic-tools/types';
 /** @public */