@noetic-tools/types 3.1.0 → 3.2.0

package/dist/index.d.ts

@@ -23,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';

package/dist/index.js

@@ -23,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';

package/dist/types/context.d.ts

@@ -1,4 +1,4 @@
-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';
@@ -41,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;
 }
@@ -112,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;

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,4 +1,4 @@
-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';
@@ -54,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);
     /**

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/package.json

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