@plurid/uitive-server

On this page

The Fetch-standard handler that serves the model planner, with its limits and streaming. It re-exports the planner.

Install: pnpm add @plurid/uitive-server, with zod ^4.2.0 as a peer. Guides: Planning.

The handler

Source: handler.ts

createUitiveHandler

A Fetch-standard handler: POST …/plan and POST …/command take a plan request as JSON and answer with a plan result. It owns the contract (clients send only its hash), refuses cross-site requests, checks every request's shape before a planner sees it, never logs bodies, and tells the browser only what failed, never a provider's details. Clients that accept application/x-ndjson get progress lines, then the result or an error.

ts
function createUitiveHandler(options: HandlerOptions): (request: Request) => Promise<Response>;

Uses: HandlerOptions.

HandlerOptions

What createUitiveHandler takes: the contract it serves, who plans, who may ask, and its limits.

Uses: AnyContract, Planner.

PropertyTypeDefaultDescription
contractAnyContractThe contract the application's clients use; requests made with another are refused with 409.
plannerPlannerWho plans, such as modelPlanner({ model }), with the server's own key.
authorize()(request: Request) => boolean | Promise<boolean>Whether a request may plan: the application's own check of the person's session, the one its API makes. Planning spends money, so there is no default. Until the application has one, allowing requests only outside production (process.env.NODE_ENV !== 'production') keeps local development working and refuses everyone once deployed.
maxBody?number131072Largest request body in bytes.
perMinute?number20Requests per minute per client, as client tells them apart.
client?()(request: Request) => stringthe right-most X-Forwarded-For entry, which the proxy in front of the server wrote, else 'local', one budget for every requestTells clients apart for perMinute. Behind more than one proxy, return the address your own proxy recorded.
onError?()(error: unknown) => voidlogs the message to the consoleTold about failures; never sees request bodies.

@plurid/uitive-server/node

Source: node.ts

toNodeListener

Serves a Fetch-standard handler from Node's (request, response) listeners: Express, Fastify's raw routes and node:http alike, in CommonJS or ES modules. A body that middleware such as express.json() already parsed is used as it is. Responses stream, so progress lines arrive as they are written, and a request the client abandons is aborted. The request keeps its path and query under a fixed origin, since its Host header proves nothing. The listener never rejects: a request it can't read is answered 400, and a handler that throws, 500.

ts
app.use('/api/uitive', toNodeListener(handler));
ts
function toNodeListener(handler: FetchHandler, options?: NodeListenerOptions): NodeListener;

Import from @plurid/uitive-server/node.

Uses: FetchHandler, NodeListener, NodeListenerOptions.

FetchHandler

A Fetch-standard handler, such as createUitiveHandler returns.

ts
type FetchHandler = (request: Request) => Promise<Response>;

Import from @plurid/uitive-server/node.

NodeListener

A Node (request, response) listener, as node:http and Express take one.

ts
type NodeListener = (request: NodeRequest, response: ServerResponse) => Promise<void>;

Import from @plurid/uitive-server/node.

Uses: NodeRequest.

NodeListenerOptions

How toNodeListener reads requests, and whom it tells when the handler fails.

Import from @plurid/uitive-server/node.

PropertyTypeDefaultDescription
maxBody?number131072, the handler's defaultLargest request body read, in bytes; larger ones are refused unread. It is checked before the handler's own maxBody, so raise both together.
onError?()(error: unknown) => voidlogs the message to the consoleTold when the handler throws or its response breaks off; never sees request bodies.

NodeRequest

Node's request, with what Express and similar frameworks may add to it.

ts
type NodeRequest = IncomingMessage & {
  originalUrl?: string;
  body?: unknown;
};

Import from @plurid/uitive-server/node.

Re-exported

From @plurid/uitive-planner: anthropic, contractText, costOf, DEFAULT_MODELS, environmentModel, google, limits, modelPlanner, offeredBlocks, openai, outputSchema, PlannerError, planRequestSchema, repairText, requestText, RULES, size, toOperations, vocabulary, AnthropicOptions, GoogleOptions, Model, ModelCall, ModelMessage, ModelPlannerOptions, ModelPrices, ModelReply, ModelUsage, OpenAIOptions, PlannerOutput, SchemaOptions, Vocabulary.