@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

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.

ts
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.

ts
const planRequestSchema: ZodObject;

Also exported by @plurid/uitive-server.

repairText

What policy rejected, for the model to repair.

ts
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.

ts
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.

PropertyTypeDefaultDescription
modelModelThe model that plans, such as anthropic(), openai({ model: 'gpt-6.1-sol' }), google({ model: 'gemini-3.8-flash' }) or one of your own.
maxTokens?number16000Most 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.

ts
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.

PropertyDescription
statusWhether the model answered the request, found it ambiguous, or couldn't answer it.
candidatesFor an ambiguous request: what the words could mean.
noteA 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.

ts
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.

ts
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.

ts
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.

ts
function environmentModel(
  variables?: Readonly<Record<string, string | undefined>>,
): Model | undefined;

Also exported by @plurid/uitive-server.

Uses: Model.

google

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.

ts
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.

ts
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.

ts
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.

MemberDescription
publicMessageWhat 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.

PropertyTypeDefaultDescription
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?number60000How long a call may take before it fails.
fallbacks?booleantrueServer-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?stringThe 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 profileThe 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.

PropertyTypeDefaultDescription
modelstringThe model, such as gemini-3.8-flash.
apiKey?stringGEMINI_API_KEY, else GOOGLE_API_KEY, from the environmentThe 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?numberMost tokens the model may spend thinking, for models that think.
timeoutMs?number60000How long a call may take before it fails.
prices?ModelPricesUS dollars per million tokens, to report what plans cost.
fetch?FetchLikeglobalThis.fetchThe 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.

PropertyTypeDescription
providerstringThe provider, as plan results report it, such as openai.
namestringThe 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.

PropertyTypeDescription
rulesstringThe planner's rules: the same for every call.
contractstringThe contract as text: the same for every request about it, so providers can cache it.
messagesreadonly ModelMessage[]The conversation so far.
schemaRecord<string, unknown>The JSON Schema the answer must follow, as outputSchema compiles it.
maxTokensnumberMost tokens the model may write, thinking included.
signal?unknownAn AbortSignal that cancels the call, such as when the person leaves.
onText?(snapshot: string) => voidHears 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.

PropertyTypeDescription
role'user' | 'assistant'Who wrote it.
contentstringWhat it says.

ModelPrices

US dollars per million tokens, for reporting what plans cost.

Also exported by @plurid/uitive-server.

PropertyTypeDefaultDescription
inputnumberTokens read.
outputnumberTokens written.
cacheRead?numberinputTokens read from the cache.
cacheWrite?numberinputTokens written to the cache.

ModelReply

What a model answered, how it stopped, and what it used.

Also exported by @plurid/uitive-server.

Uses: ModelUsage.

PropertyTypeDescription
textstringThe 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.
modelstringThe model that answered, which may differ from the one asked, after a fallback.
usageModelUsageTokens used.
cost?numberWhat the call cost in US dollars, when the model's prices are known.

ModelUsage

Tokens a call used.

Also exported by @plurid/uitive-server.

PropertyTypeDescription
inputnumberTokens read, besides those from the cache.
outputnumberTokens written, thinking included.
cacheReadnumberTokens read from the provider's prompt cache.
cacheWritenumberTokens 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.

PropertyTypeDefaultDescription
modelstringThe model, such as gpt-6.1-sol, or one a compatible server offers, such as qwen3 on Ollama.
apiKey?stringOPENAI_API_KEY from the environment, for OpenAI's own APIThe 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?number60000How long a call may take before it fails.
prices?ModelPricesUS dollars per million tokens, to report what plans cost.
fetch?FetchLikeglobalThis.fetchThe fetch it calls.

@plurid/uitive-planner/schema

Source: schema.ts

limits

Counts what structured outputs limit per request: optional and union-typed parameters.

ts
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.

ts
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.

ts
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.

ts
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.

ts
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.

PropertyTypeDefaultDescription
subset?SubsetScopes sources, and the actions that act on them, to part of a large contract.
native?booleantrueWhether 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.

PropertyTypeDescription
listsstring[]The lists' surface names.
choicesstring[]The choices' surface names.
pagesstring[]The pages' surface names.
actionsstring[]Every action ID.
contextsstring[]Every context value.
valuesstring[]Every choice value.
regionsstring[]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.

ts
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.

ts
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.

ts
const RULES: string;

Also exported by @plurid/uitive-planner/prompt, @plurid/uitive-server.