@noetic-tools/types 3.1.0 → 3.2.1

package/dist/types/schema.js

@@ -0,0 +1,63 @@
+import { ZodError } from 'zod';
+import { frameworkCast } from '../util/framework-cast.js';
+/** @public Type guard for Zod schemas (detected via the `_zod` internals marker). */
+export function isZodSchema(schema) {
+    return '_zod' in schema;
+}
+/** @public Type guard for schemas implementing the Standard JSON Schema v1 companion spec. */
+export function isStandardJsonSchema(schema) {
+    const standard = frameworkCast(schema['~standard']);
+    return typeof standard.jsonSchema?.input === 'function';
+}
+function issuePathToPropertyKeys(path) {
+    if (!path) {
+        return [];
+    }
+    return path.map((segment) => typeof segment === 'object' && segment !== null && 'key' in segment ? segment.key : segment);
+}
+/** @public Adapt Standard Schema issues into a synthetic `ZodError` of `custom` issues. */
+export function standardIssuesToZodError(issues) {
+    return new ZodError(issues.map((issue) => ({
+        code: 'custom',
+        message: issue.message,
+        path: issuePathToPropertyKeys(issue.path),
+    })));
+}
+/**
+ * Validates a value against any Standard Schema. Zod schemas take the
+ * `safeParse` fast path; other vendors run `schema['~standard'].validate`,
+ * awaiting sync or Promise results. The returned success value is the
+ * parsed/transformed output.
+ * @public
+ */
+export async function validateSchema(schema, value) {
+    if (isZodSchema(schema)) {
+        const result = schema.safeParse(value);
+        if (result.success) {
+            return {
+                success: true,
+                value: frameworkCast(result.data),
+            };
+        }
+        return {
+            success: false,
+            issues: result.error.issues.map((issue) => ({
+                message: issue.message,
+                path: issue.path,
+            })),
+            zodError: result.error,
+        };
+    }
+    const result = await schema['~standard'].validate(value);
+    if (result.issues) {
+        return {
+            success: false,
+            issues: result.issues,
+            zodError: standardIssuesToZodError(result.issues),
+        };
+    }
+    return {
+        success: true,
+        value: frameworkCast(result.value),
+    };
+}

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;

package/dist/types/step.d.ts

@@ -1,4 +1,4 @@
-import type { ZodType } from 'zod';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { Channel } from './channel.js';
 import type { ModelParams, RetryPolicy, ServerToolSpec, StepMeta } from './common.js';
 import type { Context } from './context.js';
@@ -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>;
@@ -104,11 +105,17 @@ export interface StepLLM<TContext = ContextData, _I = unknown, O = unknown> {
      */
     tools?: Lazy<(Tool | ServerToolSpec)[] | undefined, TContext>;
     /**
-     * Structured output: a Zod schema (assistant text is JSON-parsed and
+     * Structured output: a Standard Schema (assistant text is JSON-parsed and
      * validated) or a streaming `OutputCodec` (fed each text delta, produces
-     * the typed value at turn end).
+     * the typed value at turn end). Non-Zod schemas can derive the model
+     * constraint through StandardJSONSchemaV1 or provide `outputJsonSchema`.
      */
-    output?: ZodType<O> | OutputCodec<O>;
+    output?: StandardSchemaV1<unknown, O> | OutputCodec<O>;
+    /**
+     * Explicit raw JSON Schema override sent to the model. For non-Zod schemas,
+     * it takes precedence over StandardJSONSchemaV1 conversion.
+     */
+    outputJsonSchema?: Record<string, unknown>;
     params?: ModelParams;
     /** Controls framework event emission for this step. Defaults to `true`. Set `false` to suppress all framework events. A filter function receives `(eventType, data)` and returns `boolean`. */
     emit?: boolean | ((eventType: string, data: Record<string, unknown>) => boolean);
@@ -138,41 +145,41 @@ export interface StepSubHarness<TContext = ContextData, _I = unknown, O = unknow
     settings?: SubHarnessSettings;
     /** System instructions applied on the first message of a fresh session. */
     instructions?: Lazy<string | undefined, TContext>;
-    /** When set, the assistant text is JSON-parsed and validated against this schema. */
-    output?: ZodType<O>;
+    /** When set, the assistant text is JSON-parsed and validated against this Standard Schema. */
+    output?: StandardSchemaV1<unknown, O>;
     /** Session reuse + teardown policy across steps. */
     session?: SubHarnessSessionPolicy;
     /** 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<ZodType<I>, ZodType<O>>;
+    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>[];
@@ -180,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>[];
@@ -196,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[];
@@ -242,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/types/tool.d.ts

@@ -1,6 +1,7 @@
-import type { ZodTypeAny, z } from 'zod';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { FunctionCallItem, FunctionCallOutputItem, Item, ItemSchemaExtensions, ToolResultExtensionItem } from './items.js';
-type ToolExecutionResult<O extends ZodTypeAny> = Promise<z.infer<O>> | AsyncGenerator<unknown, z.infer<O>>;
+import type { InferSchemaOutput } from './schema.js';
+type ToolExecutionResult<O extends StandardSchemaV1> = Promise<InferSchemaOutput<O>> | AsyncGenerator<unknown, InferSchemaOutput<O>>;
 /**
  * Declares tool-owned state that the runtime materializes into a ContextLayer.
  * @public
@@ -39,44 +40,55 @@ export interface UiFragment {
  * `tool()` builder and runtime consume.
  * @public
  */
-export interface ToolUiDeclaration<I extends ZodTypeAny = ZodTypeAny, O extends ZodTypeAny = ZodTypeAny, E = unknown> {
+export interface ToolUiDeclaration<I extends StandardSchemaV1 = StandardSchemaV1, O extends StandardSchemaV1 = StandardSchemaV1, E = unknown> {
     /** Rendered as soon as the call streams in — args may be partial. */
-    call?(args: Partial<z.infer<I>>): UiFragment | null;
+    call?(args: Partial<InferSchemaOutput<I>>): UiFragment | null;
     /** Re-rendered on each event an AsyncGenerator `execute` yields. Receives all events so far. */
     progress?(events: E[]): UiFragment | null;
     /** Replaces the tool's region on successful completion. */
-    result?(output: z.infer<O>, args: z.infer<I>): UiFragment | null;
+    result?(output: InferSchemaOutput<O>, args: InferSchemaOutput<I>): UiFragment | null;
     /** Replaces the tool's region when execution throws. */
-    error?(err: unknown, args: z.infer<I>): UiFragment | null;
+    error?(err: unknown, args: InferSchemaOutput<I>): UiFragment | null;
 }
 /**
  * A tool definition that an LLM can invoke during execution.
  *
+ * Input and output schemas accept any Standard Schema v1 implementation
+ * (Zod, Valibot, ArkType, …). Zod remains the fast path; other validators
+ * can provide JSON Schema through the Standard JSON Schema v1 companion
+ * trait or an explicit `inputJsonSchema` override.
+ *
  * The runtime passes a `ToolExecutionContext` (from `./tool-context`) as
  * the second argument to `execute`. Callers that need the concrete type
  * should import `Tool` from the package root (`@noetic-tools/core`), which
  * re-exports it with `ToolExecutionContext` substituted in.
  * @public
  */
-export interface Tool<I extends ZodTypeAny = ZodTypeAny, O extends ZodTypeAny = ZodTypeAny> {
+export interface Tool<I extends StandardSchemaV1 = StandardSchemaV1, O extends StandardSchemaV1 = StandardSchemaV1> {
     /** Unique tool name used by the LLM for selection. */
     name: string;
     /** Human-readable description shown to the LLM. */
     description: string;
-    /** Zod schema validating tool input arguments. */
+    /** Schema validating tool input arguments (any Standard Schema v1). */
     input: I;
-    /** Zod schema validating tool return value. */
+    /** Schema validating tool return value (any Standard Schema v1). */
     output: O;
-    /** Optional Zod schema validating streaming events yielded during execution. */
-    event?: ZodTypeAny;
+    /**
+     * Explicit raw JSON Schema for the tool input, sent to the LLM wire format.
+     * For non-Zod schemas, overrides StandardJSONSchemaV1 conversion and serves
+     * as the required fallback for validation-only schemas.
+     */
+    inputJsonSchema?: Record<string, unknown>;
+    /** Optional schema validating streaming events yielded during execution. */
+    event?: StandardSchemaV1;
     /** Optional item schemas contributed by this tool for tool call/result extensions. */
     itemSchemas?: Pick<ItemSchemaExtensions, 'toolCalls' | 'toolResults' | 'items'>;
     /** Decorate the harness-created tool result item before it is appended/emitted. */
     decorateResultItem?(params: {
         baseItem: FunctionCallOutputItem;
         callItem: FunctionCallItem;
-        args: z.infer<I>;
-        result: z.infer<O> | undefined;
+        args: InferSchemaOutput<I>;
+        result: InferSchemaOutput<O> | undefined;
         output: string;
         error?: boolean;
     }): Item | ToolResultExtensionItem;
@@ -86,7 +98,7 @@ export interface Tool<I extends ZodTypeAny = ZodTypeAny, O extends ZodTypeAny =
      * this type a dependency leaf. Use `tool()` from `builders/` or cast at
      * the call site to get a typed handle.
      */
-    execute(args: z.infer<I>, toolCtx: unknown): ToolExecutionResult<O>;
+    execute(args: InferSchemaOutput<I>, toolCtx: unknown): ToolExecutionResult<O>;
     /** When true, execution pauses for human approval before running. */
     needsApproval?: boolean;
     /** Optional context declaration — the runtime generates a ContextLayer from this. */

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.1.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",
@@ -55,6 +55,7 @@
   },
   "dependencies": {
     "@openrouter/agent": "^0.6.0",
+    "@standard-schema/spec": "1.1.0",
     "zod": "^4.0.0"
   },
   "scripts": {

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>;