@noetic-tools/types 3.0.0 → 3.2.0

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export * from './schemas/workflow.js';
 export * from './types/channel.js';
 export * from './types/common.js';
 export * from './types/context.js';
+export * from './types/context-cache.js';
 export * from './types/context-layer.js';
 export * from './types/context-parts/item-log.js';
 export * from './types/context-parts/layer-usage.js';
@@ -22,6 +23,7 @@ export * from './types/items.js';
 export * from './types/observability.js';
 export * from './types/output-codec.js';
 export * from './types/runtime.js';
+export * from './types/schema.js';
 export * from './types/shell-adapter.js';
 export * from './types/steering.js';
 export * from './types/step.js';
@@ -29,5 +31,6 @@ export * from './types/sub-harness.js';
 export * from './types/subprocess-adapter.js';
 export * from './types/tool.js';
 export * from './types/tool-context.js';
+export * from './util/content-hash.js';
 export * from './util/framework-cast.js';
 export * from './util/message-helpers.js';

package/dist/index.js

@@ -10,6 +10,7 @@ export * from './schemas/workflow.js';
 export * from './types/channel.js';
 export * from './types/common.js';
 export * from './types/context.js';
+export * from './types/context-cache.js';
 export * from './types/context-layer.js';
 export * from './types/context-parts/item-log.js';
 export * from './types/context-parts/layer-usage.js';
@@ -22,6 +23,7 @@ export * from './types/items.js';
 export * from './types/observability.js';
 export * from './types/output-codec.js';
 export * from './types/runtime.js';
+export * from './types/schema.js';
 export * from './types/shell-adapter.js';
 export * from './types/steering.js';
 export * from './types/step.js';
@@ -29,5 +31,6 @@ export * from './types/sub-harness.js';
 export * from './types/subprocess-adapter.js';
 export * from './types/tool.js';
 export * from './types/tool-context.js';
+export * from './util/content-hash.js';
 export * from './util/framework-cast.js';
 export * from './util/message-helpers.js';

package/dist/types/common.d.ts

@@ -56,25 +56,41 @@ export interface TokenUsage {
     total: number;
     cached?: number;
 }
+/**
+ * @public Token counts for a single model round.
+ *
+ * `cachedTokens` and `cacheWriteTokens` are `undefined` — not `0` — when the
+ * provider reports no prompt-cache figures at all. Callers that steer on cache
+ * behaviour must tell "nothing was cached" apart from "this provider doesn't
+ * say", so the distinction is preserved rather than defaulted away.
+ */
+export interface RoundUsage {
+    inputTokens: number;
+    outputTokens: number;
+    /** Prompt tokens served from the provider's cache (a cache *read*). */
+    cachedTokens?: number;
+    /** Prompt tokens written into the provider's cache (a cache *write*). */
+    cacheWriteTokens?: number;
+}
 /** @public Metadata captured from the most recent step execution. */
 export interface StepMeta {
     toolCalls?: FunctionCallItem[];
-    usage?: {
-        inputTokens: number;
-        outputTokens: number;
-        cachedTokens?: number;
-    };
+    usage?: RoundUsage;
     cost?: number;
     responseItems?: ReadonlyArray<Item>;
 }
 /** @public Structured response returned by a model adapter after an LLM call. */
 export interface LLMResponse {
     items: Item[];
-    usage: {
-        inputTokens: number;
-        outputTokens: number;
-        cachedTokens?: number;
-    };
+    /** Totals across every round of the call. */
+    usage: RoundUsage;
+    /**
+     * Per-round breakdown, oldest first. Rounds after the first replay the same
+     * assembled view plus appended tool traffic, so they hit the prompt cache
+     * regardless of whether the first round did — only `rounds[0]` answers
+     * "was my prefix cached?".
+     */
+    rounds?: ReadonlyArray<RoundUsage>;
     cost?: number;
 }
 /** @public Configuration for the LLM provider used by the agent harness. */

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

@@ -0,0 +1,84 @@
+import type { Item } from './items.js';
+/**
+ * @public Tuning for the prompt-cache anchoring described on {@link LayerPlacement}.
+ *
+ * The defaults are chosen so that a layer set with no explicit placements still
+ * gets a stable prefix without any configuration.
+ */
+export interface ContextCacheConfig {
+    /** Master switch. Default `true`. When off, every layer renders before history, as it did before bands existed. */
+    enabled?: boolean;
+    /** Re-anchor when the first round reports fewer cached tokens than this. Default 100. */
+    minCachedTokens?: number;
+    /**
+     * Assemblies an epoch must reach before its cache figures are judged. Default 2.
+     * The first assembly after a re-anchor writes the cache rather than reading it,
+     * so judging it immediately would re-anchor forever and never pin anything.
+     */
+    minEpochAssemblies?: number;
+    /** Assemblies after which an epoch re-anchors regardless of cache figures. Default 50. */
+    maxEpochAssemblies?: number;
+    /** Re-anchor once supersedes cost more than this fraction of the anchor band. Default 0.15. */
+    deltaBudgetFraction?: number;
+    /** An `'auto'` layer changing at least this often moves to the live band. Default 0.5. */
+    autoDemoteChurn?: number;
+    /** An `'auto'` layer changing at most this often moves back to the anchor band. Default 0.2. */
+    autoPromoteChurn?: number;
+    /** Assemblies a layer must be watched for before its placement moves. Default 3. */
+    minChurnSamples?: number;
+    /** Fraction of the churn counters carried across a re-anchor. Default 0.5. */
+    churnDecay?: number;
+}
+/** @public Why an epoch re-anchored. */
+export type ReanchorReason = 'cold-start' | 'instructions-changed' | 'cache-miss' | 'delta-pressure' | 'delta-overflow' | 'max-age';
+/** @public One layer's rendered output, held byte-stable for the life of an epoch. */
+export interface AnchorPin {
+    layerId: string;
+    /** The exact items served every assembly this epoch. */
+    items: Item[];
+    tokenCount: number;
+    contentHash: string;
+    /** The layer state as of pinning. Held by reference — see `RenderDeltaParams.prevState`. */
+    state: unknown;
+    slot: number;
+}
+/** @public How often a layer's rendered output changes, and what that costs. */
+export interface LayerChurn {
+    /** Assemblies in which the layer produced output. */
+    observed: number;
+    /** Assemblies in which its output differed from its pin. */
+    changed: number;
+    /** Tokens invalidated downstream by those changes, had they not been pinned. */
+    rebillTokens: number;
+}
+/** @public One run of assemblies sharing a cacheable prompt prefix. */
+export interface ContextEpoch {
+    id: string;
+    /** Pinned output, keyed as `${scopeKey}:${layerId}`. */
+    pins: Map<string, AnchorPin>;
+    /** Band chosen for each `'auto'` layer at the last boundary, same key as `pins`. */
+    autoBand: Map<string, 'anchor' | 'live'>;
+    /** Hash of the resolved instructions this epoch was anchored against. */
+    instructionsHash: string;
+    assemblies: number;
+    anchorTokens: number;
+    deltaTokens: number;
+    /**
+     * Set once the provider has shown it reports no cache figures, or has missed
+     * so persistently that steering on its numbers is pointless. Suppresses the
+     * cache-miss trigger; age and delta pressure still apply.
+     */
+    cacheBlind: boolean;
+    /** Consecutive judged assemblies that came back a miss. */
+    misses: number;
+    lastReanchorReason: ReanchorReason;
+}
+/** @public Per-harness home for anchoring state, one epoch per cache lineage. */
+export interface ContextCacheStore {
+    /** Keyed by cache lineage — a thread at top level, an execution below it. */
+    epochs: Map<string, ContextEpoch>;
+    /** Churn per layer, outliving epochs so placement is not relearnt each time. */
+    churn: Map<string, LayerChurn>;
+    /** Re-anchors decided from a response, applied at the next assembly. */
+    pendingReanchor: Map<string, ReanchorReason>;
+}

package/dist/types/context-cache.js

@@ -0,0 +1,2 @@
+export {};
+//#endregion

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

@@ -179,6 +179,42 @@ export interface StoreParams<TState> {
 export interface StoreResult<TState> {
     state: TState;
 }
+/**
+ * @public Which band of the assembled view a layer's recall output sits in.
+ *
+ * Prompt caches match on a prefix, so a layer that re-renders every turn
+ * invalidates everything after it. The bands let stable content sit ahead of
+ * conversation history where it can be cached, and volatile content sit after
+ * it where re-rendering is nearly free.
+ *
+ * - `'anchor'` — before history. Pinned for the epoch: the bytes sent on the
+ *   first assembly are re-sent unchanged until the next re-anchor, and any
+ *   change is published as a supersede instead of rewriting the prefix.
+ * - `'live'` — after history. Re-rendered freely. Use for content that changes
+ *   every turn, or whose `recall()` mutates state and so cannot be replayed.
+ * - `'auto'` (default) — starts anchored; the runtime may move it to `'live'`
+ *   at an epoch boundary once it has watched how often the layer changes.
+ *   An explicit `'anchor'` or `'live'` is never overridden.
+ */
+export type LayerPlacement = 'anchor' | 'live' | 'auto';
+/** @public Parameters passed to a context layer's `renderDelta` hook when its pinned output goes stale. */
+export interface RenderDeltaParams<TState = unknown> {
+    /** The items still pinned in the anchor band — what the model can currently see. */
+    prev: ReadonlyArray<Item>;
+    /** The freshly recalled items that would have replaced them. */
+    next: ReadonlyArray<Item>;
+    /**
+     * The layer state captured when `prev` was pinned. Best-effort: it is held by
+     * reference, so a layer that mutates its state in place sees the current
+     * object here rather than a snapshot.
+     */
+    prevState: TState | undefined;
+    /** The layer's current state. */
+    state: TState | undefined;
+    ctx: ExecutionContext;
+    /** Soft token budget for the returned text. */
+    budget: number;
+}
 /** @public Parameters passed to a context layer's `onSpawn` hook when a child execution starts. */
 export interface SpawnParams<TState> {
     parentState: TState;
@@ -297,6 +333,16 @@ export interface ContextLayerHooks<TState = unknown> {
      * Use for: capping history, summarising old turns, redacting items.
      */
     projectHistory?(params: ProjectHistoryParams<TState>): Promise<ProjectHistoryResult>;
+    /**
+     * Called for an anchored layer whose pinned output has gone stale, to describe
+     * the change compactly instead of re-sending the whole block.
+     *
+     * Return `null` to fall back to the default, which republishes the full new
+     * content. Worth implementing only when the layer's output is large and its
+     * changes are small — a file set where one file changed, a ledger that gained
+     * a row. Never called for layers in the `'live'` band, which re-render anyway.
+     */
+    renderDelta?(params: RenderDeltaParams<TState>): Promise<string | null>;
 }
 /**
  * A composable context layer that participates in the recall/store lifecycle.
@@ -343,6 +389,11 @@ export interface ContextLayer<TState = unknown> {
     itemSchemas?: Pick<ItemSchemaExtensions, 'developerMessages' | 'items'>;
     /** Default re-render timing when `onItemAppend` requests a re-render. */
     rerenderTiming?: 'immediate' | 'batched';
+    /**
+     * Which band of the assembled view this layer's recall output sits in, and so
+     * whether it is pinned for the prompt cache. Defaults to `'auto'`.
+     */
+    placement?: LayerPlacement;
 }
 /** @public Configuration for how the runtime projects conversation items into the model's context window. */
 export interface ProjectionPolicy {

package/dist/types/context-parts/layer-usage.d.ts

@@ -1,3 +1,4 @@
+import type { ReanchorReason } from '../context-cache.js';
 import type { Item } from '../items.js';
 /** @public Per-layer contribution to the context window on the most recent LLM call. */
 export interface LayerUsageEntry {
@@ -5,6 +6,27 @@ export interface LayerUsageEntry {
     readonly tokenCount: number;
     /** Items this layer contributed to the context view for the last LLM call. */
     readonly items: ReadonlyArray<Item>;
+    /** Which band the layer rendered into. */
+    readonly placement: 'anchor' | 'live';
+    /** `'pinned'` when the items are a replay of an earlier render, held for the prompt cache. */
+    readonly served: 'fresh' | 'pinned';
+    /** Whether the layer's fresh output differed from its pin, and so was superseded. */
+    readonly changed: boolean;
+    /** Share of watched assemblies in which this layer's output changed, 0–1. */
+    readonly churnRate: number;
+    /** Tokens this layer's changes would have re-billed had it not been pinned. */
+    readonly rebillTokens: number;
+}
+/** @public Prompt-cache anchoring state behind the most recent assembly. */
+export interface EpochUsage {
+    readonly id: string;
+    /** Assemblies served by this epoch, including the one just made. */
+    readonly age: number;
+    readonly anchorTokens: number;
+    readonly liveTokens: number;
+    readonly deltaTokens: number;
+    /** Set only on an assembly that re-anchored. */
+    readonly reanchorReason?: ReanchorReason;
 }
 /** @public Breakdown of the context window as of the most recent LLM call in an execution. */
 export interface LastLayerUsage {
@@ -15,4 +37,6 @@ export interface LastLayerUsage {
     readonly toolsTokens: number;
     readonly historyTokens: number;
     readonly totalUsedTokens: number;
+    /** Absent when context caching is switched off. */
+    readonly epoch?: EpochUsage;
 }

package/dist/types/context.d.ts

@@ -1,7 +1,8 @@
-import type { ZodType } from 'zod';
+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 { ItemLog } from './context-parts/item-log.js';
 import type { LastLayerUsage } from './context-parts/layer-usage.js';
@@ -40,7 +41,9 @@ interface ContextCallModelRequestBase {
     items: ReadonlyArray<import('./items.js').Item>;
     instructions?: string;
     params?: ModelParams;
-    outputSchema?: ZodType;
+    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;
 }
@@ -111,7 +114,7 @@ export type ContextStep<TContext = ContextData, I = unknown, O = unknown> = {
 } | {
     readonly kind: 'llm';
     readonly id: string;
-    readonly output?: ZodType<O>;
+    readonly output?: StandardSchemaV1<unknown, O>;
 } | {
     readonly kind: 'loop';
     readonly id: string;
@@ -128,6 +131,8 @@ export interface ContextHarness {
         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;
@@ -159,6 +164,8 @@ export interface ContextHarness {
     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[]>;

package/dist/types/error.d.ts

@@ -1,4 +1,5 @@
-import type { ZodError, ZodType } from 'zod';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { ZodError } from 'zod';
 /** @public Discriminated union of all structured error kinds raised by the runtime. */
 export type NoeticError = {
     kind: 'step_failed';
@@ -13,7 +14,8 @@ export type NoeticError = {
     kind: 'llm_parse_error';
     stepId: string;
     raw: string;
-    schema: ZodType;
+    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';

package/dist/types/runtime.d.ts

@@ -1,7 +1,8 @@
-import type { ZodType } from 'zod';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { Channel, ChannelHandle, ExternalChannel } from './channel.js';
 import type { LLMResponse, ModelParams, ServerToolSpec } 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';
@@ -32,6 +33,8 @@ export interface AgentConfig<TParams extends Record<string, unknown> = Record<st
     projection?: ProjectionPolicy;
     /** When true, every layer is recalled atomically regardless of its `recallMode` (no eventual/cached recall). */
     forceAtomicRecall?: boolean;
+    /** Tuning for prompt-cache anchoring. See `ContextCacheConfig` for the defaults. */
+    contextCache?: ContextCacheConfig;
 }
 /** @public How a message submitted during an active turn is delivered to the model.
  *
@@ -51,7 +54,12 @@ interface CallModelRequestBase {
     instructions?: string;
     params?: ModelParams;
     /** When provided, the harness sends a JSON Schema constraint to the model so it returns structured JSON. */
-    outputSchema?: ZodType;
+    outputSchema?: StandardSchemaV1;
+    /**
+     * Explicit raw JSON Schema override for the structured-output constraint.
+     * For non-Zod schemas, it takes precedence over StandardJSONSchemaV1 conversion.
+     */
+    outputJsonSchema?: Record<string, unknown>;
     /** Controls framework event emission. Defaults to `true`. Passed through from `StepLLM.emit`. */
     emit?: boolean | ((eventType: string, data: Record<string, unknown>) => boolean);
     /**
@@ -245,6 +253,13 @@ export interface AgentHarnessContract<TParams extends Record<string, unknown> =
      * iterable owns a single iterator; subscribe again for a second consumer.
      */
     getChannelStream<T>(channel: ExternalChannel<T>, executionId: string): AsyncIterable<T>;
+    /**
+     * Pinned anchor output and epoch bookkeeping for prompt-cache anchoring,
+     * shared by every thread on this harness. Optional so a hand-written harness
+     * stays valid: without it nothing is pinned across turns and layers render
+     * fresh every time, as they did before anchoring existed.
+     */
+    readonly contextCache?: ContextCacheStore;
     initLayers(layers: ContextLayer[], ctx: Context, storage: StorageAdapter): Promise<void>;
     recallLayers(layers: ContextLayer[], input: string, ctx: Context): Promise<RecallLayerOutput[]>;
     /** Recall only atomic layers (or all layers when the harness forces atomic recall). Blocks until complete. */
@@ -307,6 +322,13 @@ export interface RecallLayerOutput {
     layerId: string;
     items: Item[];
     tokenCount: number;
+    /**
+     * Set when the layer's `recall` returned new state, meaning the call changed
+     * something and cannot be replayed. Such a layer is never pinned — serving an
+     * older render would drop the very thing the call committed (the steering
+     * layer, for one, drains its queue as it renders).
+     */
+    mutatedState?: boolean;
 }
 /** @public A request to re-render the context window, collected from onItemAppend hooks. */
 export interface RerenderRequest {

package/dist/types/schema.d.ts

@@ -0,0 +1,62 @@
+import type { StandardJSONSchemaV1, StandardSchemaV1 } from '@standard-schema/spec';
+import type { ZodTypeAny, z } from 'zod';
+import { ZodError } from 'zod';
+export type { StandardJSONSchemaV1, StandardSchemaV1 } from '@standard-schema/spec';
+/**
+ * Input type inferred from any Standard Schema. Zod schemas keep their exact
+ * `z.input` inference; other vendors use `StandardSchemaV1.InferInput`.
+ * @public
+ */
+export type InferSchemaInput<S extends StandardSchemaV1> = S extends ZodTypeAny ? z.input<S> : StandardSchemaV1.InferInput<S>;
+/**
+ * Output type inferred from any Standard Schema. Zod schemas keep their exact
+ * `z.output` inference; other vendors use `StandardSchemaV1.InferOutput`.
+ * @public
+ */
+export type InferSchemaOutput<S extends StandardSchemaV1> = S extends ZodTypeAny ? z.output<S> : StandardSchemaV1.InferOutput<S>;
+/**
+ * JSON Schema configuration for a tool input schema. Zod and Standard JSON
+ * Schema implementations can derive their wire schema; validation-only
+ * Standard Schemas require an explicit fallback.
+ * @public
+ */
+export type InputSchemaConfig<S extends StandardSchemaV1> = StandardSchemaV1 extends S ? {
+    inputJsonSchema?: Record<string, unknown>;
+} : S extends ZodTypeAny | StandardJSONSchemaV1 ? {
+    inputJsonSchema?: Record<string, unknown>;
+} : {
+    inputJsonSchema: Record<string, unknown>;
+};
+/** @public Type guard for Zod schemas (detected via the `_zod` internals marker). */
+export declare function isZodSchema(schema: StandardSchemaV1): schema is ZodTypeAny;
+/** @public Type guard for schemas implementing the Standard JSON Schema v1 companion spec. */
+export declare function isStandardJsonSchema(schema: StandardSchemaV1): schema is StandardSchemaV1 & StandardJSONSchemaV1;
+/** @public Successful result of `validateSchema` — carries the parsed/transformed value. */
+export interface SchemaValidationSuccess<T> {
+    success: true;
+    value: T;
+}
+/**
+ * Failed result of `validateSchema`. `issues` are the vendor's issues in
+ * Standard Schema form; `zodError` adapts them into a `ZodError` (the
+ * original error for Zod schemas, synthetic `custom` issues otherwise) so
+ * consumers like `llm_parse_error` keep a single error surface.
+ * @public
+ */
+export interface SchemaValidationFailure {
+    success: false;
+    issues: readonly StandardSchemaV1.Issue[];
+    zodError: ZodError;
+}
+/** @public Result of `validateSchema`. */
+export type SchemaValidationResult<T> = SchemaValidationSuccess<T> | SchemaValidationFailure;
+/** @public Adapt Standard Schema issues into a synthetic `ZodError` of `custom` issues. */
+export declare function standardIssuesToZodError(issues: readonly StandardSchemaV1.Issue[]): ZodError;
+/**
+ * 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 declare function validateSchema<S extends StandardSchemaV1>(schema: S, value: unknown): Promise<SchemaValidationResult<InferSchemaOutput<S>>>;

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/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';
@@ -104,11 +104,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,8 +144,8 @@ 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`. */
@@ -149,7 +155,7 @@ export interface StepSubHarness<TContext = ContextData, _I = unknown, O = unknow
 export interface StepTool<_TContext = ContextData, I = unknown, O = unknown> {
     kind: 'tool';
     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. */

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/content-hash.d.ts

@@ -0,0 +1,25 @@
+import type { Item } from '../types/items.js';
+/**
+ * @public Hash a string to 16 hex chars (64 bits).
+ *
+ * Not cryptographic — it exists to answer "is this byte-identical to last
+ * time?" cheaply. 64 bits keeps accidental collisions far enough away that a
+ * stale-content false match is not a practical concern.
+ *
+ * Adapted from bryc's cyrb64 (public domain):
+ * https://github.com/bryc/code/blob/master/jshash/experimental/cyrb1.js
+ */
+export declare function hashString(input: string): string;
+/**
+ * @public Hash rendered items by the content that actually reaches the model.
+ *
+ * `createMessage` mints a fresh `id` on every render, so hashing items verbatim
+ * would report a change every turn even when the text is identical. Message
+ * items are sent as `{role, content}` alone, so `id` and `status` are dropped
+ * before hashing; every other item type is hashed whole, since their ids can
+ * reach the wire.
+ *
+ * Object keys are sorted, so a layer that builds its items in a different key
+ * order between renders still hashes the same.
+ */
+export declare function hashItems(items: ReadonlyArray<Item>): string;

package/dist/util/content-hash.js

@@ -0,0 +1,65 @@
+//#region Public API
+/**
+ * @public Hash a string to 16 hex chars (64 bits).
+ *
+ * Not cryptographic — it exists to answer "is this byte-identical to last
+ * time?" cheaply. 64 bits keeps accidental collisions far enough away that a
+ * stale-content false match is not a practical concern.
+ *
+ * Adapted from bryc's cyrb64 (public domain):
+ * https://github.com/bryc/code/blob/master/jshash/experimental/cyrb1.js
+ */
+export function hashString(input) {
+    let h1 = 0xdeadbeef;
+    let h2 = 0x41c6ce57;
+    for (let i = 0; i < input.length; i++) {
+        const ch = input.charCodeAt(i);
+        h1 = Math.imul(h1 ^ ch, 2654435761);
+        h2 = Math.imul(h2 ^ ch, 1597334677);
+    }
+    h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507);
+    h1 ^= Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+    h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507);
+    h2 ^= Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+    return `${(h2 >>> 0).toString(16).padStart(8, '0')}${(h1 >>> 0).toString(16).padStart(8, '0')}`;
+}
+/**
+ * @public Hash rendered items by the content that actually reaches the model.
+ *
+ * `createMessage` mints a fresh `id` on every render, so hashing items verbatim
+ * would report a change every turn even when the text is identical. Message
+ * items are sent as `{role, content}` alone, so `id` and `status` are dropped
+ * before hashing; every other item type is hashed whole, since their ids can
+ * reach the wire.
+ *
+ * Object keys are sorted, so a layer that builds its items in a different key
+ * order between renders still hashes the same.
+ */
+export function hashItems(items) {
+    return hashString(stableStringify(items.map(wireShape)));
+}
+//#endregion
+//#region Helpers
+/** Drops the fields the provider adapter strips before sending a message item. */
+function wireShape(item) {
+    if (item.type !== 'message') {
+        return item;
+    }
+    const { id: _id, status: _status, ...rest } = item;
+    return rest;
+}
+/** `JSON.stringify` with object keys sorted at every depth. */
+function stableStringify(value) {
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value) ?? 'null';
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(stableStringify).join(',')}]`;
+    }
+    const entries = Object.entries(value)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`);
+    return `{${entries.join(',')}}`;
+}
+//#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noetic-tools/types",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "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": {