@noetic-tools/types 3.2.0 → 3.2.1

package/dist/types/step.d.ts

@@ -52,13 +52,14 @@ export interface Verdict {
 export type Until = (snapshot: Snapshot) => Verdict | Promise<Verdict>;
 /**
  * Field type that accepts either an eager value or a `(ctx) => value` getter.
- * Used by `step.llm` for params that may vary per execution (model, instructions,
- * tool list). The getter runs at step execution time with the live context.
+ * Used by `step.callModel` for params that may vary per execution (model,
+ * instructions, tool list). The getter runs at step execution time with the
+ * live context.
  * @public
  */
 export type Lazy<T, TContext = ContextData> = T | ((ctx: Context<TContext>) => T | Promise<T>);
 /**
- * Outcome of a single path in a `settle`-mode fork (mirrors `Promise.allSettled`).
+ * Outcome of a single path in a `settle`-mode inParallel step (mirrors `Promise.allSettled`).
  * @public
  */
 export interface SettleResult<O> {
@@ -72,10 +73,10 @@ export interface SettleResult<O> {
     error?: NoeticError;
 }
 /** @public Discriminated union of all step kinds that can be composed into an execution tree. */
-export type Step<TContext = ContextData, I = unknown, O = unknown> = StepRun<TContext, I, O> | StepLLM<TContext, I, O> | StepSubHarness<TContext, I, O> | StepTool<TContext, I, O> | StepBranch<TContext, I, O> | StepFork<TContext, I, O> | StepSpawn<TContext, I, O> | StepProvide<TContext, I, O> | StepLoop<TContext, I, O> | StepEvery<TContext, I, O>;
+export type Step<TContext = ContextData, I = unknown, O = unknown> = StepRunCode<TContext, I, O> | StepCallModel<TContext, I, O> | StepSubHarness<TContext, I, O> | StepInvokeTool<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 StepRun<TContext = ContextData, I = unknown, O = unknown> {
-    kind: 'run';
+export interface StepRunCode<TContext = ContextData, I = unknown, O = unknown> {
+    kind: 'runCode';
     id: string;
     execute: (input: I, ctx: Context<TContext>) => Promise<O>;
     retry?: RetryPolicy;
@@ -88,8 +89,8 @@ export interface StepRun<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 StepLLM<TContext = ContextData, _I = unknown, O = unknown> {
-    kind: 'llm';
+export interface StepCallModel<TContext = ContextData, _I = unknown, O = unknown> {
+    kind: 'callModel';
     id: string;
     /** Model id. Accepts either an eager string or a `(ctx) => string` getter. */
     model: Lazy<string, TContext>;
@@ -151,34 +152,34 @@ export interface StepSubHarness<TContext = ContextData, _I = unknown, O = unknow
     /** Controls framework event emission for this step. Defaults to `true`. */
     emit?: boolean | ((eventType: string, data: Record<string, unknown>) => boolean);
 }
-/** @public A step that invokes a single tool directly, bypassing the LLM. */
-export interface StepTool<_TContext = ContextData, I = unknown, O = unknown> {
-    kind: 'tool';
+/** @public A step that invokes a single tool directly, bypassing the model. */
+export interface StepInvokeTool<_TContext = ContextData, I = unknown, O = unknown> {
+    kind: 'invokeTool';
     id: string;
     tool: Tool<StandardSchemaV1<unknown, I>, StandardSchemaV1<unknown, O>>;
     args?: Partial<I>;
 }
 /** @public A step that dynamically selects and executes one of several possible sub-steps. */
-export interface StepBranch<TContext = ContextData, I = unknown, O = unknown> {
-    kind: 'branch';
+export interface StepConditional<TContext = ContextData, I = unknown, O = unknown> {
+    kind: 'conditional';
     id: string;
     route: (input: I, ctx: Context<TContext>) => Step<TContext, I, O> | null | Promise<Step<TContext, I, O> | null>;
     _optimizable?: Step<TContext>[];
 }
-/** @public Union of fork step variants (`race`, `all`, `settle`) for concurrent path execution. */
-export type StepFork<TContext = ContextData, I = unknown, O = unknown> = StepForkRace<TContext, I, O> | StepForkAll<TContext, I, O> | StepForkSettle<TContext, I, O>;
-/** @public A fork step that returns the result of the first path to complete. */
-export interface StepForkRace<TContext = ContextData, I = unknown, O = unknown> {
-    kind: 'fork';
+/** @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> {
+    kind: 'inParallel';
     id: string;
     mode: 'race';
     paths: (input: I, ctx: Context<TContext>) => Step<TContext, I, O>[];
     concurrency?: number;
     _optimizable?: Step<TContext>[];
 }
-/** @public A fork step that runs all paths and merges their results. */
-export interface StepForkAll<TContext = ContextData, I = unknown, O = unknown> {
-    kind: 'fork';
+/** @public An inParallel step that runs all paths and merges their results. */
+export interface StepInParallelAll<TContext = ContextData, I = unknown, O = unknown> {
+    kind: 'inParallel';
     id: string;
     mode: 'all';
     paths: (input: I, ctx: Context<TContext>) => Step<TContext, I, O>[];
@@ -186,9 +187,9 @@ export interface StepForkAll<TContext = ContextData, I = unknown, O = unknown> {
     concurrency?: number;
     _optimizable?: Step<TContext>[];
 }
-/** @public A fork step that runs all paths and collects fulfilled/rejected outcomes. */
-export interface StepForkSettle<TContext = ContextData, I = unknown, O = unknown> {
-    kind: 'fork';
+/** @public An inParallel step that runs all paths and collects fulfilled/rejected outcomes. */
+export interface StepInParallelSettle<TContext = ContextData, I = unknown, O = unknown> {
+    kind: 'inParallel';
     id: string;
     mode: 'settle';
     paths: (input: I, ctx: Context<TContext>) => Step<TContext, I, O>[];
@@ -202,8 +203,8 @@ export interface StepForkSettle<TContext = ContextData, I = unknown, O = unknown
  * Spawn and detachedSpawn break the inheritance chain.
  * @public
  */
-export interface StepProvide<TContext = ContextData, I = unknown, O = unknown> {
-    kind: 'provide';
+export interface StepWithContext<TContext = ContextData, I = unknown, O = unknown> {
+    kind: 'withContext';
     id: string;
     child: Step<TContext, I, O>;
     context: ContextConfig | ContextLayer[];
@@ -248,33 +249,33 @@ export interface StepLoop<TContext = ContextData, I = unknown, O = unknown> {
     onError?: (error: NoeticError, ctx: Context<TContext>) => 'retry' | 'skip' | 'abort';
 }
 /**
- * Error policy for the `every` operator when its body step throws.
+ * Error policy for the `schedule` operator when its body step throws.
  * - `'continue'` (default): emit a span event recording the error and continue parking.
  * - `'fail'`: re-throw, terminating the operator.
  * @public
  */
-export type EveryErrorPolicy = 'continue' | 'fail';
+export type ScheduleErrorPolicy = 'continue' | 'fail';
 /**
  * A step that runs a body step on a fixed-interval schedule, optionally woken
- * sooner by a wake channel. Runs forever until the executing context is cancelled.
+ * sooner by an inbox channel. Runs forever until the executing context is cancelled.
  *
- * The operator output is `void` — `every` does not accumulate iteration outputs.
+ * The operator output is `void` — `schedule` does not accumulate iteration outputs.
  * The `O` type parameter exists only to anchor the body step's output type.
  *
  * @public
  */
-export interface StepEvery<TContext = ContextData, I = unknown, O = unknown> {
-    kind: 'every';
+export interface StepSchedule<TContext = ContextData, I = unknown, O = unknown> {
+    kind: 'schedule';
     /** Unique step identifier used in traces and error messages. */
     id: string;
     /** Body step executed on each iteration. */
     step: Step<TContext, I, O>;
     /** Park duration between iterations in milliseconds. Must be >= 0. */
-    ms: number;
+    interval: number;
     /** Optional channel that wakes the parking interval when any value arrives. */
-    wakeOn?: Channel<unknown>;
+    inbox?: Channel<unknown>;
     /** Behavior when `step` throws. Defaults to `'continue'`. */
-    onError?: EveryErrorPolicy;
+    onError?: ScheduleErrorPolicy;
     /** Random jitter applied to the park duration in milliseconds. Must be >= 0. Default 0. */
     jitter?: number;
 }

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

@@ -25,13 +25,6 @@ export interface ToolExecutionContext {
     readonly shell: ShellAdapter;
     /** Per-layer state accessor for reading/writing tool-specific state. */
     readonly context: ToolContext;
-    /**
-     * @deprecated Renamed to `context`. Returns the same accessor.
-     *
-     * Required for the same reason as `Context.memory` — pre-rename code calls
-     * `toolCtx.memory.get(...)` directly.
-     */
-    readonly memory: ToolContext;
     /** The fully assembled conversation view at the point of tool invocation. */
     readonly assembledView: ReadonlyArray<Item>;
     /** Metadata from the most recent step execution (token usage, tool calls, etc.). */

package/dist/util/message-helpers.js

@@ -98,7 +98,14 @@ export function trackUsage(ctx, response) {
     ctx.tokens.input += response.usage.inputTokens;
     ctx.tokens.output += response.usage.outputTokens;
     ctx.tokens.total += response.usage.inputTokens + response.usage.outputTokens;
-    ctx.tokens.cached = (ctx.tokens.cached ?? 0) + (response.usage.cachedTokens ?? 0);
+    // Only write `cached` when the response 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;
+    }
     if (response.cost) {
         ctx.cost = ctx.cost + response.cost;
     }

package/package.json

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

package/dist/deprecated.d.ts

@@ -1,39 +0,0 @@
-/**
- * Deprecated aliases from the "memory layer" era of the framework.
- *
- * The layer system assembles the model's *context window* — recall, budget
- * allocation, history projection, the item-append pipeline — so it is named
- * after context, not memory. Every name below still resolves to its
- * replacement; nothing here changes behaviour.
- *
- * These are scheduled for removal in the next major of `@noetic-tools/types`.
- */
-import type { ContextConfig, ContextData, ContextLayer, ContextLayerHooks, InferContext, InferContextShape } from './types/context-layer.js';
-import type { ContextScope, LayerCallModelRequest } from './types/context-scope.js';
-import type { LayerTraceSpan } from './types/observability.js';
-import type { ToolContextDeclaration } from './types/tool.js';
-import type { ToolContext } from './types/tool-context.js';
-/** @public @deprecated Renamed to {@link ContextLayer}. */
-export type MemoryLayer<TState = unknown> = ContextLayer<TState>;
-/** @public @deprecated Renamed to {@link ContextLayerHooks}. */
-export type MemoryHooks<TState = unknown> = ContextLayerHooks<TState>;
-/** @public @deprecated Renamed to {@link ContextConfig}. */
-export type MemoryConfig<TLayers extends readonly ContextLayer[] = readonly ContextLayer[]> = ContextConfig<TLayers>;
-/** @public @deprecated Renamed to {@link ContextData}. */
-export type ContextMemory = ContextData;
-/** @public @deprecated Renamed to {@link InferContext}. */
-export type InferMemory<T extends {
-    readonly _shape: unknown;
-}> = InferContext<T>;
-/** @public @deprecated Renamed to {@link InferContextShape}. */
-export type InferMemoryShape<T extends readonly ContextLayer[]> = InferContextShape<T>;
-/** @public @deprecated Renamed to {@link ContextScope}. */
-export type MemoryScope = ContextScope;
-/** @public @deprecated Renamed to {@link LayerCallModelRequest}. */
-export type MemoryCallModelRequest = LayerCallModelRequest;
-/** @public @deprecated Renamed to {@link LayerTraceSpan}. */
-export type MemoryTraceSpan = LayerTraceSpan;
-/** @public @deprecated Renamed to {@link ToolContext}. */
-export type ToolMemory = ToolContext;
-/** @public @deprecated Renamed to {@link ToolContextDeclaration}. */
-export type ToolMemoryDeclaration<TState = unknown> = ToolContextDeclaration<TState>;