JuliusBrussee/caveman · error · Error

caveman agent: tool Standard Schema must implement version 1

Error message

caveman agent: tool Standard Schema must implement version 1 validation

What it means

Before using an input as a Standard Schema, tool() inspects value["~standard"] and requires version === 1, a string vendor, and a function validate. Anything else that merely has a ~standard key (wrong version number, missing vendor, validate not callable) throws 'tool Standard Schema must implement version 1 validation'. This is a definition-time contract check of the Standard Schema v1 interface.

Source

Thrown at packages/agent/src/primitives.ts:215

      value: Function.prototype.toString.call(options.execute),
      enumerable: false,
      configurable: false,
      writable: false,
    },
  );
  return Object.freeze(definition);
}

function standardToolSchema(
  value: unknown,
): StandardSchemaV1.Props<unknown, unknown> & {
  jsonSchema?: StandardJSONSchemaV1.Converter;
} | undefined {
  if (!isRecord(value) || !isRecord(value["~standard"])) return undefined;
  const standard = value["~standard"];
  if (standard.version !== 1 || typeof standard.vendor !== "string" ||
      typeof standard.validate !== "function") {
    throw new Error(
      "caveman agent: tool Standard Schema must implement version 1 validation",
    );
  }
  if (standard.jsonSchema !== undefined &&
      (!isRecord(standard.jsonSchema) || typeof standard.jsonSchema.input !== "function")) {
    throw new Error("caveman agent: tool Standard JSON Schema converter is invalid");
  }
  return standard as unknown as StandardSchemaV1.Props<unknown, unknown> & {
    jsonSchema?: StandardJSONSchemaV1.Converter;
  };
}

function isRecord(value: unknown): value is Record<string, unknown> {
  return value !== null && typeof value === "object" && !Array.isArray(value);
}

function artifactResultPolicy(definition: ArtifactDefinition): ToolResultPolicy {
  if (definition.strategy === "verbatim") {

View on GitHub (pinned to 27d5a3981a)

Solutions

Pass a genuine Standard Schema v1 object (version 1, string vendor, function validate)
Pin schema library versions known to implement Standard Schema v1 until this package supports newer revisions
If you only have a JSON Schema, use a TypeBox schema or a validator that properly implements v1
If the value is not meant to be a Standard Schema at all, check why it carries a ~standard key

Example fix

// before
const input = { "~standard": { version: 2, validate: (v) => ({ value: v }) } }; // missing vendor, wrong version

// after
import { Type } from "@sinclair/typebox";
const input = Type.Object({ q: Type.String() }); // full Standard Schema v1 implementation

Defensive patterns

Strategy: type-guard

Validate before calling

function isStandardSchemaV1(v: unknown): boolean {
  const std = (v as { "~standard"?: Record<string, unknown> })["~standard"];
  return std !== undefined && (std as { version?: unknown }).version === 1 &&
    typeof (std as { vendor?: unknown }).vendor === "string" &&
    typeof (std as { validate?: unknown }).validate === "function";
}

Type guard

const isStandardSchemaV1 = (v: unknown): v is { "~standard": { version: 1; vendor: string; validate: (v: unknown) => unknown } } => {
  if (typeof v !== "object" || v === null) return false;
  const std = (v as Record<string, unknown>)["~standard"] as Record<string, unknown> | undefined;
  return std?.version === 1 && typeof std?.vendor === "string" && typeof std?.validate === "function";
};

Prevention

Pin schema library versions that implement Standard Schema v1 and lockfile-audit upgrades
Never hand-craft ~standard objects; use a library or TypeBox schemas directly
Add a canary test that constructs one tool per schema source after dependency bumps

When it happens

Trigger: Passing an object with a ~standard property shaped for a different spec version (e.g. version: 2 experiments), a partially implemented facade where validate is missing or not a function, or a schema library on an incompatible Standard Schema revision.

Common situations: A future Standard Schema v2 library wired in after a dependency upgrade, custom ~standard wrappers that omit vendor, or objects that coincidentally have a ~standard key (poisoned input treated as a schema).

Related errors

AI-assisted analysis of JuliusBrussee/caveman@27d5a3981a (2026-08-15). Data as JSON: /api/errors/cccc33f2799a814a. Report an issue: GitHub.