#Native API

The root exports Intent, IntentError, readonly INTENT_RESULT_SCHEMA, and public types. Model API and MCP adapters have separate exports; see Integrations.

#Intent

class Intent {
  constructor(config: IntentConfig);
  parse(request: IntentParseRequest, options?: IntentParseOptions): Promise<IntentResult>;
  dispose(): Promise<void>;
}

Construction validates and snapshots configuration, throwing IntentError synchronously if invalid. parse returns a Promise that resolves to a result or rejects on technical failure. dispose is idempotent, ends owned recognition, and releases owned resources without closing shared executors or indefinitely waiting for uncooperative external Promises. Parsing after disposal produces INSTANCE_DISPOSED.

#parse parameters

Supplied material is not mutated. Repeated parse calls do not inherit history implicitly. Root arrays/null/class instances are invalid context; functions, cycles, accessors, undefined, and nonfinite numbers are not JSON. Standard parameters reject unknown keys, without restricting business keys inside context. Nonempty fields or all without schema produce SCHEMA_NOT_CONFIGURED; enabling extensions without its definition also fails.

Start with Read the result, then IntentResult. See Configuration and Multi-turn material.

#IntentError

class IntentError extends Error {
  constructor(code: IntentErrorCode, options?: IntentErrorOptions);
  readonly code: IntentErrorCode;
  readonly stage: IntentErrorStage;
  readonly details?: IntentErrorDetails;
  readonly partialResult?: IntentResult;
  readonly cause?: unknown;
  toJSON(): SerializedIntentError;
  serialize(options?: ErrorSerializationOptions): SerializedIntentError;
}

code selects a generic English message; unknown codes throw TypeError. Options can specify stage/details/cause. toJSON equals default serialize. serialize({includePartialResult:true}) includes a partialResult only if it exists. cause is non-enumerable and excluded from the standard summary.

Not every error has a partialResult. It may contain original material and is not an ordinary successful result. MCP technical errors omit partialResult. diagnostics does not authorize logging every raw error. See Errors and recovery.

#INTENT_RESULT_SCHEMA

Readonly Draft-07 JSON Schema for the successful result version, including local definitions and references. It validates Result structure; it is not a business-field Schema, candidate Schema, formatter, or model-quality guarantee. Deep-copy before passing it to an SDK that modifies Schemas.

#ModelExecutor

interface ModelExecutor {
  readonly id: string;
  generate(request: ModelRequest): Promise<ModelReply>;
}
type ModelRequest = {
  instructions: string;
  input: JsonObject;
  outputSchema: object;
  signal: AbortSignal;
};
type ModelReply =
  | {outcome: 'complete'; text: string}
  | {outcome: 'refusal' | 'incomplete'; reason?: string};

Intent captures id and generate at construction; the caller still owns shared connections. generate calls a real model to produce one candidate text matching outputSchema, not a final IntentResult. Honor signal and do not add absent history or business tools. Native generates once per recognition, without implicit retries, model switching, or output-format fallback.

See Model APIs for configuration and a complete custom executor, and Types for nested declarations.