@noetic-tools/types 2.2.0 → 3.0.0

package/dist/types/step.d.ts

@@ -2,8 +2,8 @@ import type { ZodType } from 'zod';
 import type { Channel } from './channel.js';
 import type { ModelParams, RetryPolicy, ServerToolSpec, StepMeta } from './common.js';
 import type { Context } from './context.js';
+import type { ContextConfig, ContextData, ContextLayer, ProjectionPolicy } from './context-layer.js';
 import type { NoeticError } from './error.js';
-import type { ContextMemory, MemoryConfig, MemoryLayer, ProjectionPolicy } from './memory.js';
 import type { OutputCodec } from './output-codec.js';
 import type { SubHarness, SubHarnessKind, SubHarnessSessionPolicy, SubHarnessSettings } from './sub-harness.js';
 import type { SubprocessAdapter } from './subprocess-adapter.js';
@@ -56,7 +56,7 @@ export type Until = (snapshot: Snapshot) => Verdict | Promise<Verdict>;
  * tool list). The getter runs at step execution time with the live context.
  * @public
  */
-export type Lazy<T, TMemory = ContextMemory> = T | ((ctx: Context<TMemory>) => T | Promise<T>);
+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`).
  * @public
@@ -72,12 +72,12 @@ export interface SettleResult<O> {
     error?: NoeticError;
 }
 /** @public Discriminated union of all step kinds that can be composed into an execution tree. */
-export type Step<TMemory = ContextMemory, I = unknown, O = unknown> = StepRun<TMemory, I, O> | StepLLM<TMemory, I, O> | StepSubHarness<TMemory, I, O> | StepTool<TMemory, I, O> | StepBranch<TMemory, I, O> | StepFork<TMemory, I, O> | StepSpawn<TMemory, I, O> | StepProvide<TMemory, I, O> | StepLoop<TMemory, I, O> | StepEvery<TMemory, I, O>;
+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>;
 /** @public A step that executes arbitrary async logic via a user-supplied function. */
-export interface StepRun<TMemory = ContextMemory, I = unknown, O = unknown> {
+export interface StepRun<TContext = ContextData, I = unknown, O = unknown> {
     kind: 'run';
     id: string;
-    execute: (input: I, ctx: Context<TMemory>) => Promise<O>;
+    execute: (input: I, ctx: Context<TContext>) => Promise<O>;
     retry?: RetryPolicy;
     /**
      * Per-step subprocess adapter override. When set, the interpreter
@@ -88,13 +88,13 @@ export interface StepRun<TMemory = ContextMemory, I = unknown, O = unknown> {
     subprocess?: SubprocessAdapter;
 }
 /** @public A step that sends a prompt to a language model and returns its response. */
-export interface StepLLM<TMemory = ContextMemory, _I = unknown, O = unknown> {
+export interface StepLLM<TContext = ContextData, _I = unknown, O = unknown> {
     kind: 'llm';
     id: string;
     /** Model id. Accepts either an eager string or a `(ctx) => string` getter. */
-    model: Lazy<string, TMemory>;
+    model: Lazy<string, TContext>;
     /** System instructions. Eager string or `(ctx) => string | undefined` getter. */
-    instructions?: Lazy<string | undefined, TMemory>;
+    instructions?: Lazy<string | undefined, TContext>;
     /**
      * Tools exposed to the LLM. Eager array or `(ctx) => (...)[] | undefined` getter.
      * Entries are either a client `Tool` or an inline `ServerToolSpec` (an
@@ -102,7 +102,7 @@ export interface StepLLM<TMemory = ContextMemory, _I = unknown, O = unknown> {
      * Function-form tools do not contribute to the pre-computed `ctx.unifiedTools`;
      * they are resolved per execution.
      */
-    tools?: Lazy<(Tool | ServerToolSpec)[] | undefined, TMemory>;
+    tools?: Lazy<(Tool | ServerToolSpec)[] | undefined, TContext>;
     /**
      * Structured output: a Zod schema (assistant text is JSON-parsed and
      * validated) or a streaming `OutputCodec` (fed each text delta, produces
@@ -122,7 +122,7 @@ export interface StepLLM<TMemory = ContextMemory, _I = unknown, O = unknown> {
  * interpreter handler.
  * @public
  */
-export interface StepSubHarness<TMemory = ContextMemory, _I = unknown, O = unknown> {
+export interface StepSubHarness<TContext = ContextData, _I = unknown, O = unknown> {
     /** The harness kind, equal to the backing adapter's `harnessId`. */
     kind: SubHarnessKind;
     id: string;
@@ -131,13 +131,13 @@ export interface StepSubHarness<TMemory = ContextMemory, _I = unknown, O = unkno
      * Programmatic builders take it inline; the JSON hydrator resolves it from
      * the workflow's harness registry and inlines it here.
      */
-    harness: Lazy<SubHarness, TMemory>;
+    harness: Lazy<SubHarness, TContext>;
     /** Turn prompt. Eager string or `(ctx) => string` getter. */
-    prompt: Lazy<string, TMemory>;
+    prompt: Lazy<string, TContext>;
     /** Shared harness settings (model, permission mode, …). */
     settings?: SubHarnessSettings;
     /** System instructions applied on the first message of a fresh session. */
-    instructions?: Lazy<string | undefined, TMemory>;
+    instructions?: Lazy<string | undefined, TContext>;
     /** When set, the assistant text is JSON-parsed and validated against this schema. */
     output?: ZodType<O>;
     /** Session reuse + teardown policy across steps. */
@@ -146,68 +146,68 @@ export interface StepSubHarness<TMemory = ContextMemory, _I = unknown, O = unkno
     emit?: boolean | ((eventType: string, data: Record<string, unknown>) => boolean);
 }
 /** @public A step that invokes a single tool directly, bypassing the LLM. */
-export interface StepTool<_TMemory = ContextMemory, I = unknown, O = unknown> {
+export interface StepTool<_TContext = ContextData, I = unknown, O = unknown> {
     kind: 'tool';
     id: string;
     tool: Tool<ZodType<I>, ZodType<O>>;
     args?: Partial<I>;
 }
 /** @public A step that dynamically selects and executes one of several possible sub-steps. */
-export interface StepBranch<TMemory = ContextMemory, I = unknown, O = unknown> {
+export interface StepBranch<TContext = ContextData, I = unknown, O = unknown> {
     kind: 'branch';
     id: string;
-    route: (input: I, ctx: Context<TMemory>) => Step<TMemory, I, O> | null | Promise<Step<TMemory, I, O> | null>;
-    _optimizable?: Step<TMemory>[];
+    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<TMemory = ContextMemory, I = unknown, O = unknown> = StepForkRace<TMemory, I, O> | StepForkAll<TMemory, I, O> | StepForkSettle<TMemory, I, O>;
+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<TMemory = ContextMemory, I = unknown, O = unknown> {
+export interface StepForkRace<TContext = ContextData, I = unknown, O = unknown> {
     kind: 'fork';
     id: string;
     mode: 'race';
-    paths: (input: I, ctx: Context<TMemory>) => Step<TMemory, I, O>[];
+    paths: (input: I, ctx: Context<TContext>) => Step<TContext, I, O>[];
     concurrency?: number;
-    _optimizable?: Step<TMemory>[];
+    _optimizable?: Step<TContext>[];
 }
 /** @public A fork step that runs all paths and merges their results. */
-export interface StepForkAll<TMemory = ContextMemory, I = unknown, O = unknown> {
+export interface StepForkAll<TContext = ContextData, I = unknown, O = unknown> {
     kind: 'fork';
     id: string;
     mode: 'all';
-    paths: (input: I, ctx: Context<TMemory>) => Step<TMemory, I, O>[];
-    merge: (results: O[], ctx: Context<TMemory>) => O;
+    paths: (input: I, ctx: Context<TContext>) => Step<TContext, I, O>[];
+    merge: (results: O[], ctx: Context<TContext>) => O;
     concurrency?: number;
-    _optimizable?: Step<TMemory>[];
+    _optimizable?: Step<TContext>[];
 }
 /** @public A fork step that runs all paths and collects fulfilled/rejected outcomes. */
-export interface StepForkSettle<TMemory = ContextMemory, I = unknown, O = unknown> {
+export interface StepForkSettle<TContext = ContextData, I = unknown, O = unknown> {
     kind: 'fork';
     id: string;
     mode: 'settle';
-    paths: (input: I, ctx: Context<TMemory>) => Step<TMemory, I, O>[];
-    merge: (results: SettleResult<O>[], ctx: Context<TMemory>) => O;
+    paths: (input: I, ctx: Context<TContext>) => Step<TContext, I, O>[];
+    merge: (results: SettleResult<O>[], ctx: Context<TContext>) => O;
     concurrency?: number;
-    _optimizable?: Step<TMemory>[];
+    _optimizable?: Step<TContext>[];
 }
 /**
- * A step that provides memory layers to its child without creating an isolated context.
+ * A step that provides context layers to its child without creating an isolated context.
  * Like React's Context.Provider — layers are available to all descendant steps.
  * Spawn and detachedSpawn break the inheritance chain.
  * @public
  */
-export interface StepProvide<TMemory = ContextMemory, I = unknown, O = unknown> {
+export interface StepProvide<TContext = ContextData, I = unknown, O = unknown> {
     kind: 'provide';
     id: string;
-    child: Step<TMemory, I, O>;
-    memory: MemoryConfig | MemoryLayer[];
+    child: Step<TContext, I, O>;
+    context: ContextConfig | ContextLayer[];
 }
-/** @public A step that launches a child execution with its own memory scope. */
-export interface StepSpawn<TMemory = ContextMemory, I = unknown, O = unknown> {
+/** @public A step that launches a child execution with its own context scope. */
+export interface StepSpawn<TContext = ContextData, I = unknown, O = unknown> {
     kind: 'spawn';
     id: string;
-    child: Step<TMemory, I, O>;
-    memory?: MemoryConfig | MemoryLayer[];
+    child: Step<TContext, I, O>;
+    context?: ContextConfig | ContextLayer[];
     timeout?: number;
     /**
      * Per-step subprocess adapter override applied when the interpreter
@@ -220,12 +220,12 @@ export interface StepSpawn<TMemory = ContextMemory, I = unknown, O = unknown> {
  * A loop step that iterates a body step until a termination predicate is satisfied.
  * @public
  */
-export interface StepLoop<TMemory = ContextMemory, I = unknown, O = unknown> {
+export interface StepLoop<TContext = ContextData, I = unknown, O = unknown> {
     kind: 'loop';
     /** Unique step identifier used in traces and error messages. */
     id: string;
     /** Steps to execute sequentially on each iteration. */
-    steps: ReadonlyArray<Step<TMemory, I, O>>;
+    steps: ReadonlyArray<Step<TContext, I, O>>;
     /** Termination predicate evaluated after each iteration with a cumulative snapshot. */
     until: Until;
     /** Hard safety cap on iterations (default: 1000). */
@@ -237,9 +237,9 @@ export interface StepLoop<TMemory = ContextMemory, I = unknown, O = unknown> {
     /** Ms to wait on inbox before the loop parks itself (default: 0 = no parking). */
     parkTimeout?: number;
     /** Transforms the previous iteration's output into the next iteration's input. */
-    prepareNext?: (output: O, verdict: Verdict, ctx: Context<TMemory>) => I;
+    prepareNext?: (output: O, verdict: Verdict, ctx: Context<TContext>) => I;
     /** Per-iteration error handler: retry the iteration, skip it, or abort the loop. */
-    onError?: (error: NoeticError, ctx: Context<TMemory>) => 'retry' | 'skip' | 'abort';
+    onError?: (error: NoeticError, ctx: Context<TContext>) => 'retry' | 'skip' | 'abort';
 }
 /**
  * Error policy for the `every` operator when its body step throws.
@@ -257,12 +257,12 @@ export type EveryErrorPolicy = 'continue' | 'fail';
  *
  * @public
  */
-export interface StepEvery<TMemory = ContextMemory, I = unknown, O = unknown> {
+export interface StepEvery<TContext = ContextData, I = unknown, O = unknown> {
     kind: 'every';
     /** Unique step identifier used in traces and error messages. */
     id: string;
     /** Body step executed on each iteration. */
-    step: Step<TMemory, I, O>;
+    step: Step<TContext, I, O>;
     /** Park duration between iterations in milliseconds. Must be >= 0. */
     ms: number;
     /** Optional channel that wakes the parking interval when any value arrives. */
@@ -273,4 +273,4 @@ export interface StepEvery<TMemory = ContextMemory, I = unknown, O = unknown> {
     jitter?: number;
 }
 /** @public Function signature used by the interpreter to recursively execute a step. */
-export type ExecuteStepFn = <TMemory, I, O>(step: Step<TMemory, I, O>, input: I, ctx: Context<TMemory>) => Promise<O>;
+export type ExecuteStepFn = <TContext, I, O>(step: Step<TContext, I, O>, input: I, ctx: Context<TContext>) => Promise<O>;

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

@@ -3,7 +3,7 @@
  *
  * A "harness" here is a pluggable backend that drives an external agentic
  * coding tool — Claude Code, Codex, opencode, pi — as a Noetic step. It is the
- * direct analogue of the `MemoryLayer` contract: defined in the dependency-free
+ * direct analogue of the `ContextLayer` contract: defined in the dependency-free
  * `@noetic-tools/types` foundation so both `@noetic-tools/core` (which executes
  * harness steps) and the per-tool `@noetic-tools/sub-harness-*` packages (which
  * implement them) can depend on it without forming a cycle.

package/dist/types/sub-harness.js

@@ -3,7 +3,7 @@
  *
  * A "harness" here is a pluggable backend that drives an external agentic
  * coding tool — Claude Code, Codex, opencode, pi — as a Noetic step. It is the
- * direct analogue of the `MemoryLayer` contract: defined in the dependency-free
+ * direct analogue of the `ContextLayer` contract: defined in the dependency-free
  * `@noetic-tools/types` foundation so both `@noetic-tools/core` (which executes
  * harness steps) and the per-tool `@noetic-tools/sub-harness-*` packages (which
  * implement them) can depend on it without forming a cycle.

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

@@ -6,7 +6,7 @@ import type { Item } from './items.js';
 import type { AgentHarnessContract } from './runtime.js';
 import type { ShellAdapter } from './shell-adapter.js';
 /** @public Accessor for reading and writing per-layer state from within a tool execution. */
-export interface ToolMemory {
+export interface ToolContext {
     get<T>(layerId: string): T | undefined;
     set<T>(layerId: string, state: T): void;
 }
@@ -23,8 +23,15 @@ export interface ToolExecutionContext {
     readonly fs: FsAdapter;
     /** Shell adapter for virtual or real shell command execution. */
     readonly shell: ShellAdapter;
-    /** Per-layer memory accessor for reading/writing tool-specific state. */
-    readonly memory: ToolMemory;
+    /** 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/types/tool.d.ts

@@ -2,10 +2,10 @@ import type { ZodTypeAny, z } from 'zod';
 import type { FunctionCallItem, FunctionCallOutputItem, Item, ItemSchemaExtensions, ToolResultExtensionItem } from './items.js';
 type ToolExecutionResult<O extends ZodTypeAny> = Promise<z.infer<O>> | AsyncGenerator<unknown, z.infer<O>>;
 /**
- * Declares tool-owned memory that the runtime materializes into a MemoryLayer.
+ * Declares tool-owned state that the runtime materializes into a ContextLayer.
  * @public
  */
-export interface ToolMemoryDeclaration<TState = unknown> {
+export interface ToolContextDeclaration<TState = unknown> {
     /** Shared id — tools with the same id share state. Defaults to `tool.name`. */
     id?: string;
     /** Factory for the initial state. */
@@ -13,8 +13,8 @@ export interface ToolMemoryDeclaration<TState = unknown> {
     /**
      * Project state into the LLM context. Return null to omit.
      * Declared as a method (bivariant params) so a concrete
-     * `ToolMemoryDeclaration<MyState>` assigns to the erased
-     * `ToolMemoryDeclaration` the `tool()` builder and runtime consume.
+     * `ToolContextDeclaration<MyState>` assigns to the erased
+     * `ToolContextDeclaration` the `tool()` builder and runtime consume.
      */
     recall(state: TState): string | null;
 }
@@ -22,7 +22,7 @@ export interface ToolMemoryDeclaration<TState = unknown> {
  * A renderable UI fragment in a named dialect (e.g. `'openui-lang/0.5'`).
  * The framework never interprets `source` — it forwards fragments as
  * `openui.fragment` framework events and attaches them to items; a UI
- * surface (memory layer + transport) composes and renders them.
+ * surface (context layer + transport) composes and renders them.
  * @public
  */
 export interface UiFragment {
@@ -34,7 +34,7 @@ export interface UiFragment {
 /**
  * Declares tool-owned UI: programmatic render functions invoked at tool
  * lifecycle points. All methods are optional — an omitted point renders
- * nothing (mirrors `ToolMemoryDeclaration`). Declared as methods (bivariant
+ * nothing (mirrors `ToolContextDeclaration`). Declared as methods (bivariant
  * params) so a concretely-typed declaration assigns to the erased form the
  * `tool()` builder and runtime consume.
  * @public
@@ -89,8 +89,8 @@ export interface Tool<I extends ZodTypeAny = ZodTypeAny, O extends ZodTypeAny =
     execute(args: z.infer<I>, toolCtx: unknown): ToolExecutionResult<O>;
     /** When true, execution pauses for human approval before running. */
     needsApproval?: boolean;
-    /** Optional memory declaration — the runtime generates a MemoryLayer from this. */
-    memory?: ToolMemoryDeclaration;
+    /** Optional context declaration — the runtime generates a ContextLayer from this. */
+    context?: ToolContextDeclaration;
     /** Optional UI declaration — the runtime emits the rendered fragments at call/progress/result points. */
     ui?: ToolUiDeclaration<I, O>;
 }

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

@@ -20,10 +20,10 @@ export declare function isTextPart(part: {
     type: string;
     text: string;
 };
-/** Extracts assistant/output text from items for memory buffering (one string per message). */
+/** Extracts assistant/output text from items for context buffering (one string per message). */
 export declare function collectOutputText(items: ReadonlyArray<Item>): string[];
 /**
- * Extracts text from INPUT items for memory buffering: concatenates the text
+ * Extracts text from INPUT items for context buffering: concatenates the text
  * content parts of message items (user `input_text` and any text parts) and
  * appends the `output` of `function_call_output` (tool result) items. Empty
  * strings are dropped.

package/dist/util/message-helpers.js

@@ -25,7 +25,7 @@ export function isOutputText(part) {
 export function isTextPart(part) {
     return 'text' in part && typeof part.text === 'string';
 }
-/** Extracts assistant/output text from items for memory buffering (one string per message). */
+/** Extracts assistant/output text from items for context buffering (one string per message). */
 export function collectOutputText(items) {
     return items
         .filter(isAssistantMessage)
@@ -36,7 +36,7 @@ export function collectOutputText(items) {
         .filter((t) => t.length > 0);
 }
 /**
- * Extracts text from INPUT items for memory buffering: concatenates the text
+ * Extracts text from INPUT items for context buffering: concatenates the text
  * content parts of message items (user `input_text` and any text parts) and
  * appends the `output` of `function_call_output` (tool result) items. Empty
  * strings are dropped.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noetic-tools/types",
-  "version": "2.2.0",
+  "version": "3.0.0",
   "type": "module",
   "description": "Foundational type contracts and primitives shared across the Noetic framework (items, LLM config, adapters, steering, errors).",
   "license": "Apache-2.0",
@@ -27,8 +27,8 @@
       "default": "./dist/index.js"
     },
     "./contract": {
-      "types": "./dist/types/memory.d.ts",
-      "default": "./dist/types/memory.js"
+      "types": "./dist/types/context-layer.d.ts",
+      "default": "./dist/types/context-layer.js"
     },
     "./package.json": "./package.json"
   },