Usage and constraints

Usage, JSON Schema and constraints

Ownership and imports

ai-core owns non-React actions, proposals, UI data validation, chat protocol adapters and output parsing. react-ai depends on it for UI bindings. Task graph calculation belongs to task-graph; graph-aware agent dispatch, DB adapters and schema/DDL composition stay in data-engine. This package does not import them. Use domain subpaths to select APIs. engine’s existing domain and root exports remain compatibility re-exports, so class and session identities are shared.

Input schemas and runtime validation

ActionToolInputSchema describes an application-owned object-root JSON Schema, independently of engine vendor-extension types. TypeScript types do not validate incoming model data. defineActionTool requires parseInput to establish the handler’s input type after schema validation; parse failures stop execution.

Tool input supports synchronous draft-07 (default) and 2020-12. Declare $schema when selecting the dialect, for example https://json-schema.org/draft/2020-12/schema. Other declared dialects and async tool schemas are rejected. Use properties, required, additionalProperties, ranges, lengths and other supported Ajv keywords explicitly. required and additionalProperties: false are opt-in. No coercion, default insertion or property removal occurs at AI tool boundaries. Schemas compile at configuration time; invalid schemas throw. Schema-invalid data returns a failure. An unknown x-* keyword does not implement a business rule, authorization, SQL constraint or UI behavior. Registered business validation still runs after structural validation. Schemas must resolve locally; no remote schema loader is installed. After compilation use a fresh schema object for changes.

createAjvValidator is exported at /validation. Its default configuration is non-coercing. Explicit ajvOptions can enable mutation, so callers own that choice. Its draft and locale options and returned Ajv instance are described in source JSDoc. engine reuses this helper rather than maintaining another implementation. Ajv generates functions at runtime: host policies must permit compilation.

JSON snapshots and execution boundaries

Tool schemas, arguments and projected results are detached immutable finite JSON: plain objects/arrays, strings, finite numbers, booleans and null. Accessors, custom prototypes, toJSON hooks, functions, undefined, sparse arrays, cycles and non-finite numbers are rejected. Per value, bounds are depth 64, 10,000 visited values and 1,000,000 serialized JavaScript UTF-16 code units. This is not a UTF-8 byte limit; limit transport/request bodies before parsing as well.

Nothing registers or exposes automatically. The application explicitly registers actions, chooses tool bindings and supplies mapOutput. Validate/project only fields permitted to leave the app. Registry identity replacement can change output types, so projection receives unknown. A bridge rejects duplicate call IDs within its session, keeps up to maxCalls (default 1000) and does not evict old IDs. Start a fresh session for a new conversation. Closing suppresses future/results but cannot undo side effects. Cancellation is cooperative; an execution lock stays held until work settles. These are not authorization, durable idempotency, transaction or cross-process locking mechanisms. Server authorization, tenant isolation, persistence and retry policy belong to the application.

Generative UI schemas

A v1 document has version: 1, nonempty id, and at most 32 flat blocks. Each block has a unique id, an explicitly registered component type and object data. The document contains data, not executable HTML, React nodes or callbacks. validateGenerativeUIDocument checks the envelope and bounded JSON, not the application’s component data. createGenerativeUIContract adds registration-specific validation and exports a response schema from the same registrations.

Component schemas must be inline synchronous draft-07 with an object root. References, IDs, anchors, dialect declarations and async keywords are rejected recursively, including reserved keys nested in schema objects. At most 32 unique component names are accepted. Data is not coerced/defaulted. Unique block IDs and JSON limits require runtime checks beyond the exported JSON Schema. Provider schema subsets may require a host adapter; exporting a schema does not establish compatibility with every model. Application business validation and authorization remain necessary. React component rendering belongs to react-ai and the host.

Proposals, chat and output

Proposal v1 accepts configured primitive fields; nested object/array changes are not supported. Field validators are explicit. Review decisions, before-values and versions are checked; batch preparation returns no executable partial payload if one selected entry fails. Applying payloads still requires an atomic server-side version check/transaction: client preflight cannot prevent a concurrent write.

Chat adapters normalize OpenAI-compatible and AI SDK streams, assemble tool calls and carry results; they do not execute model tool calls. Supply URLs, headers, model parameters and an injected transport explicitly. Retain privileged API keys on the server. maxResponseChars defaults to 1,000,000 decoded characters and is bounded above by 10,000,000. Stream completion, cancellation and errors are checked; this does not certify any live provider account, model or protocol variant.

extractAgentMessageText parses completed agent-message JSONL events and falls back to the original output when none are found. It neither executes output nor establishes trust, correctness or successful completion of an agent task.

Verification and publication

Run bun run verify: dependency boundaries, test type checking, unit tests, dual build and isolated tarball consumers on Node/Bun ESM/CJS and strict NodeNext types, with/without Node ambient types, plus a browser bundle. No engine/DB/storage/React package is installed in those consumers. Package sources are canonical; docs reads these local package guides from the same checkout. See the root RELEASING.md for Changesets and the single workspace lockfile.

Synchronous createAjvValidator rejects compiled async schemas before invocation in draft-07 and 2020-12. Schema compilation errors throw; invalid synchronous data returns valid:false. Awaiting an async validator is not supported by this synchronous API.