@noetic-tools/types 3.2.0 → 3.2.1

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

@@ -0,0 +1,172 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { Channel, ChannelHandle, ExternalChannel } from './channel.js';
+import type { LLMResponse, ModelParams } from './common.js';
+import type { Context, CwdState, RestoreContextOptions } from './context.js';
+import type { ContextCacheConfig, ContextCacheStore } from './context-cache.js';
+import type { ContextData, ContextLayer, ProjectionPolicy, StorageAdapter } from './context-layer.js';
+import type { DetachedHandle } from './detached.js';
+import type { FsAdapter } from './fs-adapter.js';
+import type { HarnessResponse, StreamEvent, StreamingItem } from './harness-result.js';
+import type { ExecuteInput, Item } from './items.js';
+import type { Span, TraceExporter } from './observability.js';
+import type { ShellAdapter } from './shell-adapter.js';
+import type { SteeringDecision } from './steering.js';
+import type { SubprocessAdapter } from './subprocess-adapter.js';
+import type { Tool } from './tool.js';
+export type ContextHarnessStatus = {
+    readonly kind: 'idle';
+} | {
+    readonly kind: 'generating';
+    readonly startedAt: number;
+    readonly turnId: string;
+} | {
+    readonly kind: 'aborting';
+    readonly turnId: string;
+};
+interface ContextCallModelRequestBase {
+    model: string;
+    items: ReadonlyArray<Item>;
+    instructions?: string;
+    params?: ModelParams;
+    outputSchema?: StandardSchemaV1;
+    /** Explicit non-Zod override/fallback after StandardJSONSchemaV1 conversion. */
+    outputJsonSchema?: Record<string, unknown>;
+    emit?: boolean | ((eventType: string, data: Record<string, unknown>) => boolean);
+    signal?: AbortSignal;
+}
+interface ContextCallModelRequestWithTools extends ContextCallModelRequestBase {
+    tools: Tool[];
+    ctx: Context;
+    layers?: ContextLayer[];
+    allowedToolNames?: string[];
+}
+interface ContextCallModelRequestWithoutTools extends ContextCallModelRequestBase {
+    tools?: undefined;
+    ctx?: undefined;
+    layers?: undefined;
+}
+export type ContextCallModelRequest = ContextCallModelRequestWithTools | ContextCallModelRequestWithoutTools;
+export interface ContextDetachedSpawnOverrides {
+    threadId?: string;
+    resourceId?: string;
+    cwdInit?: string;
+}
+export interface ContextRerenderRequest {
+    layerId: string;
+    slot: number;
+    timing: 'immediate' | 'batched';
+    scope: 'self' | 'slot-after' | 'all';
+}
+export interface ContextAppendPipelineResult {
+    readonly items: Item[];
+    readonly rerenderRequests: ContextRerenderRequest[];
+}
+export interface ContextRecallLayerOutput {
+    layerId: string;
+    items: Item[];
+    tokenCount: number;
+}
+export type ContextStep<TContext = ContextData, I = unknown, O = unknown> = {
+    readonly kind: 'runCode';
+    readonly id: string;
+    readonly execute: (input: I, ctx: Context<TContext>) => Promise<O>;
+} | {
+    readonly kind: 'callModel';
+    readonly id: string;
+    readonly output?: StandardSchemaV1<unknown, O>;
+} | {
+    readonly kind: 'loop';
+    readonly id: string;
+    readonly steps: ReadonlyArray<ContextStep<TContext, I, O>>;
+    readonly prepareNext?: (output: O, verdict: unknown, ctx: Context<TContext>) => I;
+} | {
+    readonly kind: string;
+    readonly id: string;
+};
+/** @public Runtime surface exposed on Context without coupling Context's definition to the runtime type module. */
+export interface ContextHarness {
+    readonly config: {
+        readonly name: string;
+        readonly params: Record<string, unknown>;
+        /** Harness-wide default projection policy; a step's `projection` overrides it. */
+        readonly projection?: ProjectionPolicy;
+        /** Tuning for prompt-cache anchoring. */
+        readonly contextCache?: ContextCacheConfig;
+    };
+    readonly fs: FsAdapter;
+    readonly shell: ShellAdapter;
+    readonly subprocess: SubprocessAdapter;
+    readonly rootCwdState: CwdState;
+    callModel(request: ContextCallModelRequest): Promise<LLMResponse>;
+    execute(input: ExecuteInput, options?: unknown): Promise<void>;
+    getAgentResponse(scope?: unknown): Promise<HarnessResponse>;
+    getItemStream(scope?: unknown): AsyncIterable<StreamingItem>;
+    getTextStream(scope?: unknown): AsyncIterable<string>;
+    getReasoningStream(scope?: unknown): AsyncIterable<string>;
+    getFullStream(scope?: unknown): AsyncIterable<StreamEvent>;
+    run<I, O>(step: ContextStep<ContextData, I, O>, input: I, ctx: Context): Promise<O>;
+    detachedSpawn<I, O>(step: unknown, input: I, parentCtx: Context, overrides?: ContextDetachedSpawnOverrides): DetachedHandle<O>;
+    createContext(opts?: {
+        parent?: Context;
+        items?: Item[];
+        state?: unknown;
+        threadId?: string;
+        resourceId?: string;
+        contextLayers?: ContextLayer[];
+        cwdInit?: string;
+    }): Context;
+    setRootCwd(nextCwd: string): void;
+    getLayerState<T>(executionId: string, layerId: string): T | undefined;
+    setLayerState<T>(executionId: string, layerId: string, state: T): void;
+    beforeToolCall(layers: ContextLayer[], toolName: string, toolArgs: unknown, ctx: Context): Promise<SteeringDecision>;
+    afterModelCall(layers: ContextLayer[], response: LLMResponse, ctx: Context): Promise<SteeringDecision>;
+    runAppendPipeline(layers: ContextLayer[], items: Item[], ctx: Context): Promise<ContextAppendPipelineResult>;
+    /** Pinned anchor output and epoch bookkeeping for prompt-cache anchoring. Absent on a harness that predates it. */
+    readonly contextCache?: ContextCacheStore;
+    recallLayers(layers: ContextLayer[], input: string, ctx: Context): Promise<ContextRecallLayerOutput[]>;
+    recallLayersAtomic(layers: ContextLayer[], input: string, ctx: Context, budgets: Map<string, number>): Promise<ContextRecallLayerOutput[]>;
+    recallLayersEventual(layers: ContextLayer[], input: string, ctx: Context, budgets: Map<string, number>): Promise<ContextRecallLayerOutput[]>;
+    projectHistory(layers: ContextLayer[], items: ReadonlyArray<Item>, ctx: Context): Promise<ReadonlyArray<Item>>;
+    storeLayers(layers: ContextLayer[], response: LLMResponse, ctx: Context): Promise<void>;
+    previewRequestItems(scope?: unknown): Promise<ReadonlyArray<Item>>;
+    /**
+     * Internal-sender channel write. Resolves immediately unless the target
+     * queue channel is at capacity, in which case the send parks until a
+     * consumer frees a slot (back-pressure; default 30s timeout →
+     * `channel_timeout`, abort → `cancelled`).
+     */
+    send<T>(channel: Channel<T>, value: 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;
+    getChannelHandle<T>(channel: ExternalChannel<T>, executionId: string): ChannelHandle<T>;
+    /** Read-side counterpart to `getChannelHandle` — see `AgentHarnessContract.getChannelStream`. */
+    getChannelStream<T>(channel: ExternalChannel<T>, executionId: string): AsyncIterable<T>;
+    initLayers(layers: ContextLayer[], ctx: Context, storage: StorageAdapter): Promise<void>;
+    disposeLayers(layers: ContextLayer[], ctx: Context): Promise<void>;
+    checkpoint(ctx: Context): Promise<void>;
+    restore(executionId: string, opts?: RestoreContextOptions): Promise<Context | null>;
+    /**
+     * Cancel an execution: abort `ctx` and every live descendant context, then
+     * run context-layer teardown (`onComplete` with `outcome: 'aborted'`, then
+     * `dispose`) bottom-up. A no-op on an already-cancelled context.
+     */
+    cancel(ctx: Context, reason?: string): Promise<void>;
+    /** Trace exporter spans are flushed to. Defaults to a no-op exporter. */
+    readonly traceExporter: TraceExporter;
+    createSpan(name: string, parent: Span | null): Span;
+    abort(scope?: unknown): Promise<void>;
+    getStatus(scope?: unknown): ContextHarnessStatus;
+    getQueueSize(scope?: unknown): number;
+    /** Cumulative token usage and cost a session has accumulated across its turns. */
+    getUsage(scope?: unknown): {
+        readonly inputTokens: number;
+        readonly outputTokens: number;
+        readonly cachedTokens?: number;
+        readonly cost?: number;
+    };
+    seedSessionHistory(threadId: string, items: ReadonlyArray<Item>): void;
+    executeRerender(requests: ContextRerenderRequest[], layers: ContextLayer[], ctx: Context, budgets: Map<string, number>, query?: string): Promise<ContextRecallLayerOutput[]>;
+}
+export {};

package/dist/types/context.d.ts

@@ -1,18 +1,13 @@
-import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { ItemSchemaRegistry } from '../schemas/item.js';
-import type { Channel, ChannelHandle, ExternalChannel } from './channel.js';
-import type { LLMResponse, ModelParams, StepMeta, TokenUsage } from './common.js';
-import type { ContextCacheConfig, ContextCacheStore } from './context-cache.js';
-import type { ContextData, ContextLayer, ProjectionPolicy, StorageAdapter } from './context-layer.js';
+import type { Channel } from './channel.js';
+import type { StepMeta, TokenUsage } from './common.js';
+import type { ContextHarness } from './context-harness.js';
+import type { ContextData, ContextLayer } from './context-layer.js';
 import type { ItemLog } from './context-parts/item-log.js';
 import type { LastLayerUsage } from './context-parts/layer-usage.js';
-import type { DetachedHandle } from './detached.js';
 import type { FsAdapter } from './fs-adapter.js';
-import type { HarnessResponse, StreamEvent, StreamingItem } from './harness-result.js';
-import type { ExecuteInput } from './items.js';
-import type { Span, TraceExporter } from './observability.js';
+import type { Span } from './observability.js';
 import type { ShellAdapter } from './shell-adapter.js';
-import type { SteeringDecision } from './steering.js';
 import type { SubprocessAdapter } from './subprocess-adapter.js';
 import type { Tool } from './tool.js';
 /**
@@ -26,44 +21,6 @@ export interface CwdState {
     cwd: string;
     previousCwd?: string;
 }
-export type ContextHarnessStatus = {
-    readonly kind: 'idle';
-} | {
-    readonly kind: 'generating';
-    readonly startedAt: number;
-    readonly turnId: string;
-} | {
-    readonly kind: 'aborting';
-    readonly turnId: string;
-};
-interface ContextCallModelRequestBase {
-    model: string;
-    items: ReadonlyArray<import('./items.js').Item>;
-    instructions?: string;
-    params?: ModelParams;
-    outputSchema?: StandardSchemaV1;
-    /** Explicit non-Zod override/fallback after StandardJSONSchemaV1 conversion. */
-    outputJsonSchema?: Record<string, unknown>;
-    emit?: boolean | ((eventType: string, data: Record<string, unknown>) => boolean);
-    signal?: AbortSignal;
-}
-interface ContextCallModelRequestWithTools extends ContextCallModelRequestBase {
-    tools: Tool[];
-    ctx: Context;
-    layers?: ContextLayer[];
-    allowedToolNames?: string[];
-}
-interface ContextCallModelRequestWithoutTools extends ContextCallModelRequestBase {
-    tools?: undefined;
-    ctx?: undefined;
-    layers?: undefined;
-}
-export type ContextCallModelRequest = ContextCallModelRequestWithTools | ContextCallModelRequestWithoutTools;
-export interface ContextDetachedSpawnOverrides {
-    threadId?: string;
-    resourceId?: string;
-    cwdInit?: string;
-}
 /**
  * @public Caller-supplied wiring forwarded to the `createContext` call that
  * `harness.restore()` makes internally.
@@ -88,122 +45,7 @@ export interface RestoreContextOptions {
     /** Opaque per-execution state, same as `createContext({ state })`. */
     state?: unknown;
     /** Context layers for the restored context. Defaults to the harness's configured layers. */
-    context?: ContextLayer[];
-    /** @deprecated Renamed to `context`. */
-    memory?: ContextLayer[];
-}
-export interface ContextRerenderRequest {
-    layerId: string;
-    slot: number;
-    timing: 'immediate' | 'batched';
-    scope: 'self' | 'slot-after' | 'all';
-}
-export interface ContextAppendPipelineResult {
-    readonly items: import('./items.js').Item[];
-    readonly rerenderRequests: ContextRerenderRequest[];
-}
-export interface ContextRecallLayerOutput {
-    layerId: string;
-    items: import('./items.js').Item[];
-    tokenCount: number;
-}
-export type ContextStep<TContext = ContextData, I = unknown, O = unknown> = {
-    readonly kind: 'run';
-    readonly id: string;
-    readonly execute: (input: I, ctx: Context<TContext>) => Promise<O>;
-} | {
-    readonly kind: 'llm';
-    readonly id: string;
-    readonly output?: StandardSchemaV1<unknown, O>;
-} | {
-    readonly kind: 'loop';
-    readonly id: string;
-    readonly steps: ReadonlyArray<ContextStep<TContext, I, O>>;
-    readonly prepareNext?: (output: O, verdict: unknown, ctx: Context<TContext>) => I;
-} | {
-    readonly kind: string;
-    readonly id: string;
-};
-/** @public Runtime surface exposed on Context without coupling Context's definition to the runtime type module. */
-export interface ContextHarness {
-    readonly config: {
-        readonly name: string;
-        readonly params: Record<string, unknown>;
-        /** Harness-wide default projection policy; a step's `projection` overrides it. */
-        readonly projection?: ProjectionPolicy;
-        /** Tuning for prompt-cache anchoring. */
-        readonly contextCache?: ContextCacheConfig;
-    };
-    readonly fs: FsAdapter;
-    readonly shell: ShellAdapter;
-    readonly subprocess: SubprocessAdapter;
-    readonly rootCwdState: CwdState;
-    callModel(request: ContextCallModelRequest): Promise<LLMResponse>;
-    execute(input: ExecuteInput, options?: unknown): Promise<void>;
-    getAgentResponse(scope?: unknown): Promise<HarnessResponse>;
-    getItemStream(scope?: unknown): AsyncIterable<StreamingItem>;
-    getTextStream(scope?: unknown): AsyncIterable<string>;
-    getReasoningStream(scope?: unknown): AsyncIterable<string>;
-    getFullStream(scope?: unknown): AsyncIterable<StreamEvent>;
-    run<I, O>(step: ContextStep<ContextData, I, O>, input: I, ctx: Context): Promise<O>;
-    detachedSpawn<I, O>(step: unknown, input: I, parentCtx: Context, overrides?: ContextDetachedSpawnOverrides): DetachedHandle<O>;
-    createContext(opts?: {
-        parent?: Context;
-        items?: import('./items.js').Item[];
-        state?: unknown;
-        threadId?: string;
-        resourceId?: string;
-        context?: ContextLayer[];
-        /** @deprecated Renamed to `context`. */
-        memory?: ContextLayer[];
-        cwdInit?: string;
-    }): Context;
-    setRootCwd(nextCwd: string): void;
-    getLayerState<T>(executionId: string, layerId: string): T | undefined;
-    setLayerState<T>(executionId: string, layerId: string, state: T): void;
-    beforeToolCall(layers: ContextLayer[], toolName: string, toolArgs: unknown, ctx: Context): Promise<SteeringDecision>;
-    afterModelCall(layers: ContextLayer[], response: LLMResponse, ctx: Context): Promise<SteeringDecision>;
-    runAppendPipeline(layers: ContextLayer[], items: import('./items.js').Item[], ctx: Context): Promise<ContextAppendPipelineResult>;
-    /** Pinned anchor output and epoch bookkeeping for prompt-cache anchoring. Absent on a harness that predates it. */
-    readonly contextCache?: ContextCacheStore;
-    recallLayers(layers: ContextLayer[], input: string, ctx: Context): Promise<ContextRecallLayerOutput[]>;
-    recallLayersAtomic(layers: ContextLayer[], input: string, ctx: Context, budgets: Map<string, number>): Promise<ContextRecallLayerOutput[]>;
-    recallLayersEventual(layers: ContextLayer[], input: string, ctx: Context, budgets: Map<string, number>): Promise<ContextRecallLayerOutput[]>;
-    projectHistory(layers: ContextLayer[], items: ReadonlyArray<import('./items.js').Item>, ctx: Context): Promise<ReadonlyArray<import('./items.js').Item>>;
-    storeLayers(layers: ContextLayer[], response: LLMResponse, ctx: Context): Promise<void>;
-    previewRequestItems(scope?: unknown): Promise<ReadonlyArray<import('./items.js').Item>>;
-    /**
-     * Internal-sender channel write. Resolves immediately unless the target
-     * queue channel is at capacity, in which case the send parks until a
-     * consumer frees a slot (back-pressure; default 30s timeout →
-     * `channel_timeout`, abort → `cancelled`).
-     */
-    send<T>(channel: Channel<T>, value: 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;
-    getChannelHandle<T>(channel: ExternalChannel<T>, executionId: string): ChannelHandle<T>;
-    /** Read-side counterpart to `getChannelHandle` — see `AgentHarnessContract.getChannelStream`. */
-    getChannelStream<T>(channel: ExternalChannel<T>, executionId: string): AsyncIterable<T>;
-    initLayers(layers: ContextLayer[], ctx: Context, storage: StorageAdapter): Promise<void>;
-    disposeLayers(layers: ContextLayer[], ctx: Context): Promise<void>;
-    checkpoint(ctx: Context): Promise<void>;
-    restore(executionId: string, opts?: RestoreContextOptions): Promise<Context | null>;
-    /**
-     * Cancel an execution: abort `ctx` and every live descendant context, then
-     * run context-layer teardown (`onComplete` with `outcome: 'aborted'`, then
-     * `dispose`) bottom-up. A no-op on an already-cancelled context.
-     */
-    cancel(ctx: Context, reason?: string): Promise<void>;
-    /** Trace exporter spans are flushed to. Defaults to a no-op exporter. */
-    readonly traceExporter: TraceExporter;
-    createSpan(name: string, parent: Span | null): Span;
-    abort(scope?: unknown): Promise<void>;
-    getStatus(scope?: unknown): ContextHarnessStatus;
-    getQueueSize(scope?: unknown): number;
-    seedSessionHistory(threadId: string, items: ReadonlyArray<import('./items.js').Item>): void;
-    executeRerender(requests: ContextRerenderRequest[], layers: ContextLayer[], ctx: Context, budgets: Map<string, number>, query?: string): Promise<ContextRecallLayerOutput[]>;
+    contextLayers?: ContextLayer[];
 }
 /** @public Execution context threaded through every step, carrying state, metrics, and channels. */
 export interface Context<TContext = ContextData, TState = unknown> {
@@ -238,14 +80,6 @@ export interface Context<TContext = ContextData, TState = unknown> {
     readonly layers?: ContextLayer[];
     /** Layer provides keyed by layer ID. Access data/functions via `ctx.context['layerId'].prop`. */
     readonly context: TContext;
-    /**
-     * @deprecated Renamed to `context`. Reads through to the same object.
-     *
-     * Required, not optional: pre-rename code does `ctx.memory['layerId']`, and an
-     * optional field would make that a `possibly undefined` compile error — which
-     * is exactly the break this alias exists to prevent.
-     */
-    readonly memory: TContext;
     /** Unified tool set collected from all LLM steps in the step tree before execution. */
     readonly unifiedTools?: ReadonlyArray<Tool>;
     /** Runtime item schema registry active for this context. */
@@ -282,4 +116,3 @@ export interface Context<TContext = ContextData, TState = unknown> {
      */
     abort(reason?: string): void;
 }
-export {};

package/dist/types/error.d.ts

@@ -7,18 +7,18 @@ export type NoeticError = {
     cause: Error;
     retriesExhausted: boolean;
 } | {
-    kind: 'llm_refused';
+    kind: 'model_refused';
     stepId: string;
     refusal: string;
 } | {
-    kind: 'llm_parse_error';
+    kind: 'model_parse_error';
     stepId: string;
     raw: string;
     schema: StandardSchemaV1;
     /** Real `ZodError` for Zod schemas; synthetic `custom` issues adapted from the vendor's Standard Schema issues otherwise. */
     zodError: ZodError;
 } | {
-    kind: 'llm_rate_limit';
+    kind: 'model_rate_limit';
     stepId: string;
     retryAfter?: number;
 } | {
@@ -76,5 +76,6 @@ export type NoeticError = {
     kind: 'handle_evicted';
     handleId: string;
     stepId: string;
-    gracePeriodMs: number;
+    /** Grace period in milliseconds. */
+    gracePeriod: number;
 };

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

@@ -30,6 +30,12 @@ export interface HarnessResponse {
     readonly usage: {
         readonly inputTokens: number;
         readonly outputTokens: number;
+        /**
+         * Prompt tokens served from the provider's cache across the turns this
+         * response covers. `undefined` — not `0` — while no model call has reported
+         * a cache figure, preserving the `RoundUsage` distinction between "nothing
+         * was cached" and "this provider says nothing about caching".
+         */
         readonly cachedTokens?: number;
     };
     readonly cost?: number;

package/dist/types/observability.d.ts

@@ -15,7 +15,8 @@ export interface TraceExporter {
 export interface LayerTraceSpan {
     layerId: string;
     hook: 'init' | 'recall' | 'store' | 'onSpawn' | 'onReturn' | 'onComplete' | 'dispose';
-    durationMs: number;
+    /** Duration in milliseconds. */
+    duration: number;
     status: 'ok' | 'error' | 'timeout' | 'skipped';
     budget?: {
         allocated: number;

package/dist/types/output-codec.d.ts

@@ -1,8 +1,8 @@
 /**
- * Streaming output-dialect contracts for `step.llm`.
+ * Streaming output-dialect contracts for `step.callModel`.
  *
  * An `OutputCodec` is the dialect-agnostic alternative to a Zod schema in
- * `StepLLM.output`: instead of JSON-parsing the assistant text once at turn
+ * `StepCallModel.output`: instead of JSON-parsing the assistant text once at turn
  * end, a codec is fed each text delta as it streams and produces a typed
  * value when the turn finishes. OpenUI Lang is one dialect; the contract
  * lives here — next to `ContextLayer` and `SubHarness` — so `core` and
@@ -35,8 +35,8 @@ export interface OutputCodecSession<O = unknown> {
     finish(fullText: string): O;
 }
 /**
- * A streaming output dialect for `step.llm`. Discriminated from a Zod schema
- * in `StepLLM.output` by the `kind: 'codec'` tag.
+ * A streaming output dialect for `step.callModel`. Discriminated from a Zod schema
+ * in `StepCallModel.output` by the `kind: 'codec'` tag.
  * @public
  */
 export interface OutputCodec<O = unknown> {
@@ -47,7 +47,7 @@ export interface OutputCodec<O = unknown> {
     start(): OutputCodecSession<O>;
 }
 /**
- * Narrows a `StepLLM.output` value to an `OutputCodec`. A Zod schema has no
+ * Narrows a `StepCallModel.output` value to an `OutputCodec`. A Zod schema has no
  * `kind: 'codec'` tag, so the discriminant is unambiguous.
  * @public
  */

package/dist/types/output-codec.js

@@ -1,15 +1,15 @@
 /**
- * Streaming output-dialect contracts for `step.llm`.
+ * Streaming output-dialect contracts for `step.callModel`.
  *
  * An `OutputCodec` is the dialect-agnostic alternative to a Zod schema in
- * `StepLLM.output`: instead of JSON-parsing the assistant text once at turn
+ * `StepCallModel.output`: instead of JSON-parsing the assistant text once at turn
  * end, a codec is fed each text delta as it streams and produces a typed
  * value when the turn finishes. OpenUI Lang is one dialect; the contract
  * lives here — next to `ContextLayer` and `SubHarness` — so `core` and
  * dialect packages both depend on it without forming a cycle.
  */
 /**
- * Narrows a `StepLLM.output` value to an `OutputCodec`. A Zod schema has no
+ * Narrows a `StepCallModel.output` value to an `OutputCodec`. A Zod schema has no
  * `kind: 'codec'` tag, so the discriminant is unambiguous.
  * @public
  */

package/dist/types/runtime.d.ts

@@ -19,16 +19,21 @@ export interface AgentHooks {
     beforeStep?: (step: Step, ctx: Context) => Promise<void>;
     afterStep?: (step: Step, result: unknown, ctx: Context) => Promise<void>;
 }
+/** @public Item-schema configuration: extension schemas plus validation strictness. */
+export interface ItemSchemaConfig {
+    /** Harness-wide item schema extensions used to validate emitted and returned items. */
+    schemas?: ItemSchemaExtensions;
+    /** Whether unknown extension item types must match a registered schema. Defaults to true. */
+    strict?: boolean;
+}
 /** @public Top-level configuration object that defines an agent's model, tools, context, and behavior. */
 export interface AgentConfig<TParams extends Record<string, unknown> = Record<string, unknown>> {
     name: string;
     storage?: StorageAdapter;
     hooks?: AgentHooks;
     params: TParams;
-    /** Harness-wide item schema extensions used to validate emitted and returned items. */
-    itemSchemas?: ItemSchemaExtensions;
-    /** Whether unknown extension item types must match a registered schema. Defaults to true. */
-    strictItemSchemas?: boolean;
+    /** Item schema extensions and validation strictness for emitted and returned items. */
+    itemSchemas?: ItemSchemaConfig;
     /** Default projection policy for all LLM steps. Individual steps override via `step.projection`. */
     projection?: ProjectionPolicy;
     /** When true, every layer is recalled atomically regardless of its `recallMode` (no eventual/cached recall). */
@@ -111,9 +116,7 @@ export interface ExecuteOptions {
     resourceId?: string;
     state?: unknown;
     /** Context layers to apply to the execution context. Overrides harness-level layers if provided. */
-    context?: ContextLayer[];
-    /** @deprecated Renamed to `context`. */
-    memory?: ContextLayer[];
+    contextLayers?: ContextLayer[];
     /** Override the harness's default delivery mode for this message only. */
     deliveryMode?: DeliveryMode;
     /**
@@ -136,6 +139,20 @@ export type HarnessStatus = {
     readonly kind: 'aborting';
     readonly turnId: string;
 };
+/** @public Cumulative token usage and cost a session has accumulated across all of its turns. */
+export interface SessionUsage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    /** Undefined when no turn reported a cache figure, so callers can tell "provider says nothing about caching" from "nothing was cached". */
+    readonly cachedTokens?: number;
+    /**
+     * Undefined when the accumulated cost is zero. Unlike `cachedTokens` this
+     * cannot distinguish "no provider reported a cost" from "the work was free" —
+     * per-turn cost is a plain number that starts at 0, so there is no
+     * "unreported" signal to preserve.
+     */
+    readonly cost?: number;
+}
 /** @public Identifies which session the accessor targets. All methods fall back to the harness's default thread when omitted. */
 export interface SessionScope {
     threadId?: string;
@@ -184,6 +201,12 @@ export interface AgentHarnessContract<TParams extends Record<string, unknown> =
     getStatus(scope?: SessionScope): HarnessStatus;
     /** Number of messages currently queued on a session. */
     getQueueSize(scope?: SessionScope): number;
+    /**
+     * Cumulative token usage and cost the session has accumulated across all of
+     * its turns, including turns that failed or were aborted after partial model
+     * work. Returns zeros for a session that has not run yet.
+     */
+    getUsage(scope?: SessionScope): SessionUsage;
     /**
      * Pre-populate a session's accumulated history with prior items so the next
      * `execute()` turn sees them as established context. Used by resume flows to
@@ -220,9 +243,7 @@ export interface AgentHarnessContract<TParams extends Record<string, unknown> =
         state?: unknown;
         threadId?: string;
         resourceId?: string;
-        context?: ContextLayer[];
-        /** @deprecated Renamed to `context`. */
-        memory?: ContextLayer[];
+        contextLayers?: ContextLayer[];
         /** Override the new context's initial cwd. */
         cwdInit?: string;
     }): Context;

package/dist/types/steering.d.ts

@@ -26,7 +26,8 @@ export interface LedgerEntry {
     toolName?: string;
     toolArgs?: unknown;
     success?: boolean;
-    durationMs?: number;
+    /** Duration in milliseconds. */
+    duration?: number;
     model?: string;
     tokenUsage?: {
         input: number;