@plurid/uitive-planner
On this page
The model planner, for any provider: contracts compiled to structured outputs, the prompt, and models from Anthropic, OpenAI and every server that speaks its API, Gemini, or your own. It runs on servers and in extensions.
Install: pnpm add @plurid/uitive-planner, with zod ^4.2.0 as a peer, and optionally @anthropic-ai/sdk ^0.131.0. Guides: Planning.
- The model planner:
modelPlanner,planRequestSchema,repairText,toOperations,ModelPlannerOptions,PlannerOutput - Models:
anthropic,costOf,DEFAULT_MODELS,environmentModel,google,openai,PlannerError,AnthropicOptions,GoogleOptions,Model,ModelCall,ModelMessage,ModelPrices,ModelReply,ModelUsage,OpenAIOptions @plurid/uitive-planner/schema:limits,offeredBlocks,outputSchema,size,vocabulary,SchemaOptions,Vocabulary@plurid/uitive-planner/prompt:contractText,requestText,RULES
The model planner
Source: output.ts, plan.ts, request.ts
modelPlanner
Plans with a language model from any provider. The contract compiles to the schema the answer must follow, so a model that keeps to it can only name what the application offers; answers are checked against it all the same. Large contracts, by sources or by the size of their enums, are first scoped to the areas a request needs, and each scope's schema and prompt are prepared once, so providers' caches stay warm. An answer that strays from the schema, or that policy would partly reject, goes back once for repair; when the repair fails, what policy accepted of the first answer stands.
function modelPlanner(options: ModelPlannerOptions): Planner;Also exported by @plurid/uitive-server.
Uses: ModelPlannerOptions, Planner.
planRequestSchema
What a planner may be sent, as data from a client: every field typed, every string and list capped, the request and goal at most 500 characters, and the environment structure only (patterned names, counts and states). The handler answers 400 to anything else, before any model sees it.
const planRequestSchema: ZodObject;Also exported by @plurid/uitive-server.
repairText
What policy rejected, for the model to repair.
function repairText(rejected: readonly OutputRejection[]): string;Also exported by @plurid/uitive-server.
Uses: OutputRejection.
toOperations
Turns the model's flat output into proposed operations for policy to check. Only a command's
operations can be explicit: in a plan (kind: 'plan'), basis request counts for nothing.
function toOperations(output: PlannerOutput, kind?: PlanRequest['kind']): ProposedOperation[];Also exported by @plurid/uitive-server.
Uses: PlannerOutput, PlanRequest, ProposedOperation.
ModelPlannerOptions
How modelPlanner plans: with which model, and how much it may write.
Also exported by @plurid/uitive-server.
Uses: Model.
| Property | Type | Default | Description |
|---|---|---|---|
model | Model | The model that plans, such as anthropic(), openai({ model: 'gpt-6.1-sol' }), google({ model: 'gemini-3.8-flash' }) or one of your own. | |
maxTokens? | number | 16000 | Most tokens the model may write, thinking included. |
PlannerOutput
What the model writes, in the schema outputSchema compiles: a status, candidates for ambiguous
requests, a note and flat operations. Policy checks it after toOperations.
interface PlannerOutput {
status: 'done' | 'ambiguous' | 'unsupported';
candidates: string[];
note: string;
lists?: {
surface: string;
context: string;
op: 'promote' | 'demote' | 'move' | 'pin' | 'unpin' | 'hide' | 'restore';
target: string;
index: number;
basis: 'request' | 'goal' | 'usage';
metric: 'none' | Metric;
}[];
choices?: {
surface: string;
value: string;
basis: 'request' | 'goal' | 'usage';
}[];
pages?: {
surface: string;
context: string;
op: 'set' | 'reset' | 'create' | 'rename' | 'delete';
slug?: string;
title?: string;
root: string;
elements: {
id: string;
block: string;
props: unknown;
children: string[];
}[];
data?: {
name: string;
query: unknown;
}[];
basis: 'request' | 'goal' | 'usage';
}[];
}Also exported by @plurid/uitive-server.
Uses: Metric.
| Property | Description |
|---|---|
status | Whether the model answered the request, found it ambiguous, or couldn't answer it. |
candidates | For an ambiguous request: what the words could mean. |
note | A short note for the person, shown with the changes. |
lists? | Changes to lists, each with what it is based on. |
choices? | Values for choices, each with what it is based on. |
pages? | Pages to redesign, reset, or, for the person's own pages, create, rename or delete. |
Models
Source: anthropic.ts, environment.ts, google.ts, model.ts, openai.ts
anthropic
Claude, through Anthropic's structured outputs: the provider constrains every answer to the
schema. The rules and the contract are marked for prompt caching, so repeated requests about one
contract read them from the cache. Needs @anthropic-ai/sdk, loaded only when a call is made.
function anthropic(options?: AnthropicOptions): Model;Also exported by @plurid/uitive-server.
Uses: AnthropicOptions, Model.
costOf
What a call cost in US dollars, from its usage and the model's prices.
function costOf(usage: ModelUsage, prices: ModelPrices | undefined): number | undefined;Also exported by @plurid/uitive-server.
Uses: ModelPrices, ModelUsage.
DEFAULT_MODELS
The model each provider plans with when UITIVE_MODEL names none.
const DEFAULT_MODELS: {
readonly anthropic: 'claude-opus-5-5';
readonly openai: 'gpt-6.1-sol';
readonly google: 'gemini-3.8-flash';
};Also exported by @plurid/uitive-server.
environmentModel
The model whose key the environment holds, so a server plans with whichever provider it has a key
for: Anthropic (ANTHROPIC_API_KEY), else OpenAI (OPENAI_API_KEY), else Gemini
(GEMINI_API_KEY or GOOGLE_API_KEY), each with its default model. UITIVE_MODEL names the
model, with its provider first when its name doesn't tell (openai:qwen3); a model whose
provider is named or known (claude-…, gpt-…, gemini-…) plans only with that provider's key.
Without a key, nothing, for the deterministic planner to take over. Runtimes without a process
environment, such as Cloudflare Workers, pass their own variables.
function environmentModel(
variables?: Readonly<Record<string, string | undefined>>,
): Model | undefined;Also exported by @plurid/uitive-server.
Uses: Model.
Gemini, through the Gemini API's structured output: the provider constrains each answer to the
schema (responseJsonSchema). The rules and the contract lead every call unchanged, which
Gemini's implicit caching rewards. Calls fetch: no SDK.
function google(options: GoogleOptions): Model;Also exported by @plurid/uitive-server.
Uses: GoogleOptions, Model.
openai
A model behind OpenAI's Chat Completions API: OpenAI's own, or any compatible server, such as
Ollama, vLLM, LM Studio, OpenRouter or Groq. Uses structured outputs (strict JSON Schema) by
default; structured: 'json' or 'text' suits servers without them. Calls fetch: no SDK.
function openai(options: OpenAIOptions): Model;Also exported by @plurid/uitive-server.
Uses: Model, OpenAIOptions.
PlannerError
A planner failure, with the HTTP status the handler answers with. Its message may hold a
provider's own words and the address of a model's server, so only onError hears it; the
browser gets publicMessage.
class PlannerError extends Error {
readonly status: number;
readonly reason?: 'too-complex' | undefined;
readonly publicMessage: string;
constructor(message: string, status: number, reason?: 'too-complex' | undefined);
}Also exported by @plurid/uitive-server.
| Member | Description |
|---|---|
publicMessage | What the handler tells the browser: fixed for each status, so details stay on the server. |
AnthropicOptions
How anthropic() calls Claude: which model, how hard it thinks, how long it may take, and with
which key or client.
Also exported by @plurid/uitive-server.
| Property | Type | Default | Description |
|---|---|---|---|
model? | string | 'claude-opus-5-5' | The model. |
effort? | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'low' | How much the model thinks before answering; low keeps commands quick. Sent only to models that take it, which Haiku 4.5 doesn't. |
timeoutMs? | number | 60000 | How long a call may take before it fails. |
fallbacks? | boolean | true | Server-side refusal fallback (beta server-side-fallback-2026-07-01), sent only to models that offer it: Fable 5.1, Mythos 5.1, Opus 5 and later, and Sonnet 5.5, never Haiku. |
apiKey? | string | The API key, where there is no environment to read it from, such as in Cloudflare Workers. | |
client? | Pick<Anthropic, 'beta'> | one from the environment: ANTHROPIC_API_KEY or an ant auth login profile | The Anthropic client, such as one made for a browser extension's worker. |
GoogleOptions
How google() calls Gemini: which model, with which key, and how it keeps to the schema.
Also exported by @plurid/uitive-server.
Uses: FetchLike, ModelPrices.
| Property | Type | Default | Description |
|---|---|---|---|
model | string | The model, such as gemini-3.8-flash. | |
apiKey? | string | GEMINI_API_KEY, else GOOGLE_API_KEY, from the environment | The API key. |
baseURL? | string | 'https://generativelanguage.googleapis.com/v1beta' | The API's base URL. |
structured? | 'schema' | 'json' | 'text' | 'schema' | How the model keeps to the schema: schema for structured output, json for JSON with the schema in the prompt, text for neither. |
thinkingBudget? | number | Most tokens the model may spend thinking, for models that think. | |
timeoutMs? | number | 60000 | How long a call may take before it fails. |
prices? | ModelPrices | US dollars per million tokens, to report what plans cost. | |
fetch? | FetchLike | globalThis.fetch | The fetch it calls. |
Model
A language model that plans, from any provider: anthropic(), openai() for OpenAI and every
server that speaks its API, google(), or one of your own.
Also exported by @plurid/uitive-server.
Uses: ModelCall, ModelReply.
| Property | Type | Description |
|---|---|---|
provider | string | The provider, as plan results report it, such as openai. |
name | string | The model's name, such as gpt-6.1-sol. |
structured | 'schema' | 'json' | 'text' | How the model keeps to the schema. schema: the provider constrains the answer to it. json: the answer is JSON, and the schema goes in the prompt. text: neither. Answers are checked against the schema either way, and repaired once when they stray. |
generate() | (call: ModelCall) => Promise<ModelReply> | Calls the model; failures throw a PlannerError with the status the handler answers. |
ModelCall
What one call to a model takes: instructions, the conversation, the schema and its limits.
Also exported by @plurid/uitive-server.
Uses: ModelMessage.
| Property | Type | Description |
|---|---|---|
rules | string | The planner's rules: the same for every call. |
contract | string | The contract as text: the same for every request about it, so providers can cache it. |
messages | readonly ModelMessage[] | The conversation so far. |
schema | Record<string, unknown> | The JSON Schema the answer must follow, as outputSchema compiles it. |
maxTokens | number | Most tokens the model may write, thinking included. |
signal? | unknown | An AbortSignal that cancels the call, such as when the person leaves. |
onText? | (snapshot: string) => void | Hears the answer so far, as it streams. |
ModelMessage
One message of a planning conversation: the request, and for a repair, the answer and what to fix.
Also exported by @plurid/uitive-server.
| Property | Type | Description |
|---|---|---|
role | 'user' | 'assistant' | Who wrote it. |
content | string | What it says. |
ModelPrices
US dollars per million tokens, for reporting what plans cost.
Also exported by @plurid/uitive-server.
| Property | Type | Default | Description |
|---|---|---|---|
input | number | Tokens read. | |
output | number | Tokens written. | |
cacheRead? | number | input | Tokens read from the cache. |
cacheWrite? | number | input | Tokens written to the cache. |
ModelReply
What a model answered, how it stopped, and what it used.
Also exported by @plurid/uitive-server.
Uses: ModelUsage.
| Property | Type | Description |
|---|---|---|
text | string | The answer as text: JSON, when the model kept to the schema. |
stop | 'done' | 'refused' | 'cut' | refused when the model declined, cut when it ran out of tokens. |
model | string | The model that answered, which may differ from the one asked, after a fallback. |
usage | ModelUsage | Tokens used. |
cost? | number | What the call cost in US dollars, when the model's prices are known. |
ModelUsage
Tokens a call used.
Also exported by @plurid/uitive-server.
| Property | Type | Description |
|---|---|---|
input | number | Tokens read, besides those from the cache. |
output | number | Tokens written, thinking included. |
cacheRead | number | Tokens read from the provider's prompt cache. |
cacheWrite | number | Tokens written to the provider's prompt cache. |
OpenAIOptions
How openai() calls a model through OpenAI's Chat Completions API, which many providers and
local servers speak too: which model, where, with which key, and how it keeps to the schema.
Also exported by @plurid/uitive-server.
Uses: FetchLike, ModelPrices.
| Property | Type | Default | Description |
|---|---|---|---|
model | string | The model, such as gpt-6.1-sol, or one a compatible server offers, such as qwen3 on Ollama. | |
apiKey? | string | OPENAI_API_KEY from the environment, for OpenAI's own API | The API key. |
baseURL? | string | 'https://api.openai.com/v1' | The API's base URL, for compatible servers: http://localhost:11434/v1 for Ollama, https://openrouter.ai/api/v1 for OpenRouter. |
headers? | Readonly<Record<string, string>> | Headers sent with every call, such as a provider's own. | |
structured? | 'schema' | 'json' | 'text' | 'schema' | How the model keeps to the schema: schema for structured outputs, json for JSON mode with the schema in the prompt, text for neither. |
reasoningEffort? | 'minimal' | 'low' | 'medium' | 'high' | How much a reasoning model thinks before answering, where the model takes it. | |
timeoutMs? | number | 60000 | How long a call may take before it fails. |
prices? | ModelPrices | US dollars per million tokens, to report what plans cost. | |
fetch? | FetchLike | globalThis.fetch | The fetch it calls. |
@plurid/uitive-planner/schema
Source: schema.ts
limits
Counts what structured outputs limit per request: optional and union-typed parameters.
function limits(schema: unknown): {
optional: number;
unions: number;
};Also exported by @plurid/uitive-planner/schema, @plurid/uitive-server.
offeredBlocks
The blocks a request's schema offers pages besides sections, tabs and regions, by name: the
application's own, unless native is false, and the generic blocks its scope can feed. The
prompt describes these, so it never names a block the schema leaves out.
function offeredBlocks(
contract: AnyContract,
options?: SchemaOptions,
): {
own: string[];
generic: GenericName[];
};Also exported by @plurid/uitive-planner/schema, @plurid/uitive-server.
Uses: AnyContract, GenericName, SchemaOptions.
outputSchema
Compiles a contract into the one structured-output schema every call uses: flat operation
lists with every field required and explicit none sentinels, shared enums under $defs,
and pages as flat elements that name their children, since grammars can't recurse.
One schema per contract means one compiled grammar and one warm prompt cache.
function outputSchema(contract: AnyContract, options?: SchemaOptions): Record<string, unknown>;Also exported by @plurid/uitive-planner/schema, @plurid/uitive-server.
Uses: AnyContract, SchemaOptions.
size
How big a schema is: its bytes, and its largest enum, which grammars pay for most.
function size(schema: unknown): {
bytes: number;
largestEnum: number;
};Also exported by @plurid/uitive-planner/schema, @plurid/uitive-server.
vocabulary
Every value a planner may emit for a contract, lower-cased once: action IDs, surfaces by kind, contexts and choice values.
function vocabulary(contract: AnyContract): Vocabulary;Also exported by @plurid/uitive-planner/schema, @plurid/uitive-server.
Uses: AnyContract, Vocabulary.
SchemaOptions
What part of a contract a schema covers.
Also exported by @plurid/uitive-planner/schema, @plurid/uitive-server.
Uses: Subset.
| Property | Type | Default | Description |
|---|---|---|---|
subset? | Subset | Scopes sources, and the actions that act on them, to part of a large contract. | |
native? | boolean | true | Whether the application's own blocks are offered. |
Vocabulary type
The enum values a planner may emit for actions, contexts and the like, lower-cased once.
Also exported by @plurid/uitive-planner/schema, @plurid/uitive-server.
| Property | Type | Description |
|---|---|---|
lists | string[] | The lists' surface names. |
choices | string[] | The choices' surface names. |
pages | string[] | The pages' surface names. |
actions | string[] | Every action ID. |
contexts | string[] | Every context value. |
values | string[] | Every choice value. |
regions | string[] | Every region name. |
@plurid/uitive-planner/prompt
Source: prompt.ts
contractText
The application's contract as text: stable across users, so it caches. For large contracts,
a subset scopes the sources described to those chosen for the request. It names the blocks the
schema for the same subset and native offers, and no others.
function contractText(
contract: AnyContract,
subset?: Subset,
options?: Pick<SchemaOptions, 'native'>,
): string;Also exported by @plurid/uitive-planner/prompt, @plurid/uitive-server.
Uses: AnyContract, SchemaOptions, Subset.
requestText
The part of every request that changes: what was asked, what is on screen, how it is used.
function requestText(request: PlanRequest): string;Also exported by @plurid/uitive-planner/prompt, @plurid/uitive-server.
Uses: PlanRequest.
RULES
The frozen part of every request: how to work.
const RULES: string;Also exported by @plurid/uitive-planner/prompt, @plurid/uitive-server.