Praecise Harness v1.1.0 Get started

Documentation · Reference

Changelog

All notable changes to this project are documented here.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning from 1.0.0 onwards. Before 1.0.0, the shape of the public API was still being settled; that is what the entries before 1.0.0 are.

Unreleased

1.1.0 - 2026-11-22

Added

  • A plugin may bring skills (app.skills), checked as a SKILL.md is and merged under the app's own, so a plugin can be a whole environment for one platform: its skills, tools, an agent and a command.
  • skillsIn(folder) reads a folder of skills, with the text files beside each, into the shape a plugin or defineApp takes.

1.0.0 - 2026-11-22

Memory is rebuilt, the store drivers gain one verb, and nothing written by an earlier version is read or migrated. Apps that kept agent memory start with none.

Changed

  • Memory is four things, kept apart. An agent with memory has a record of exchanges, working notes it writes itself, subject pages, and a short list it carries. Only the last is placed in front of it, and only a person changes it.
  • All of an agent's memory is in one place. In files under <state>/memory/<agent>/, or, for an agent that names a store, in that store: the record and notes as rows, the pages and what it carries as documents. Nothing is split between a database and a machine's disk.
  • AppConfig.store is honoured. It is the store for every agent that asks for memory without naming one. It was declared and never read.
  • A store an agent remembers into is declared without a schema. One with a schema is refused at load.
  • What an agent carries accumulates. Accepting a proposal adds to what is carried instead of replacing it. A replaced or retired entry is closed with the time, not deleted, and which of two entries stands is decided by authority and then time. App.accept answers with { kept, closed, refused }. An agent carries at most 48 entries.
  • Facts and procedures are one list behind one gate. A procedure is a carried entry of kind: "procedure", proposed and accepted like a fact.
  • App.propose is App.reflect, and praecise memory --propose is --reflect. It also checks what is carried against the record and files what is new onto subject pages. One reading at a time per agent: a second is refused with AlreadyReflecting.
  • A driver's Connection has add. It keeps a row only if nothing is kept under its id, decided by the backend in one step. Every shipped driver implements it and conform checks it; a driver of your own must add it.
  • Development dependencies are at their latest releases: TypeScript 7.0, Vitest 5.1, oxlint 1.94, @types/node 26.6.

Removed

  • A memory backend of the app's own. AppOptions.memory takes a cipher and nothing else; memory is kept elsewhere by naming a store, and a backend the framework does not ship is a Driver. Recollection, Memory and StoredMemory are no longer exported.
  • SkillBook, usableProcedures, renderSkills, settle and their types.
  • MemorySpec.write, which was never read.

Added

  • Memory tools. An agent with memory is given search_memory, read_memory and write_note, and is told what its memory is for. What it writes is searched, never placed in front of it.
  • Subject pages. One page per subject, one writer per page: a write names the revision it read and is refused if the page has moved on, between processes and between machines (App.filed, App.page).
  • The record read back on a schedule. memory: { reflect: { cron } }, started by praecise dev, serve() or app.tend(). Where several processes serve one app, a tick is read back once.
  • Origin is set by the runtime. An exchange or note written after anything untrusted was read is kept as external, and reading external memory marks the request as tainted.
  • Recall in any script. Words are found the way each script separates them.
  • store.values.claim. Keeps a value only if the name is free; of several callers at once, one is told yes.
  • praecise eval <suite> --memory and App.evaluateMemory: one suite without memory and with it, and the difference.
  • App.retire, App.carried, App.jot, App.jotted, App.clearMemory.

Fixed

  • A memory file that could not be read as what was written is refused and left as it is; it was read as empty and overwritten by the next write.
  • Two writers to one memory file, in one process or in two, both keep what they wrote.

Also in this release

  • Reasoning is handed back with tool results on every wire. Signed thinking blocks on messages, output items with encrypted reasoning on responses, reasoning_content or reasoning on chat, and thought steps on interactions are returned to the endpoint unchanged on the next turn of a tool loop (ChatResponse.replay, Message.replay). They never leave the rung they came from.

  • Prompt caching on the messages wire. The part of the instructions that is the same on every request, and the end of a tool loop's transcript, are marked for the endpoint to keep. cache: false on an endpoint turns it off. Usage.cacheWriteTokens reports what was kept.

  • Attachments. AskOptions.attachments, and attachments on POST /api/agents/<name>, send images and documents with a question on all five wires.

  • One rule for anything sent that is not text. An attachment the endpoint reads is sent as it is: audio and video on contents and interactions, and on chat where the endpoint's takes says so. Data no model reads is rendered by a reader chosen by media type: SenML sensor measurements, Open Inference Protocol tensors, CSV and TSV tables, glTF scenes, text and JSON. Anything else is left out with a note. registerReader adds a reader.

  • Tool results carry media. A function returns attach(result, ...attachments), and an MCP tool's image, audio, embedded file or https: resource link is handed to the model on every wire. Before, such a block was written into the transcript as base64.

  • answer.attachments. Images and audio a model returns on contents, interactions and chat come back with the answer.

  • Values, facts and series on every store. store.values keeps a value under a name in a namespace, with an optional lifetime. store.facts records how two things are related, with the time it was true and the time it was recorded, closes a fact rather than deleting it, and walks relationships up to three steps. store.series keeps readings in order of time and answers a span as points or as windowed aggregates. All three are written over the operations a driver already implements, so a brought backend has them too.

  • Events over HTTP. POST /api/events/<workflow> and app.deliver() start a run for a CloudEvent, once per source and id.

  • Plugins bring more than commands. A plugin in plugins may carry app (a piece of an app, merged under the app's own folder), drivers, and setup. commands is now optional. The type is Plugin; CliPlugin remains as its alias.

  • Depth words, output room and embeddings are the endpoint's to declare. levels, output and embeds on a model endpoint.

  • Longer work in one request. turns on an agent (default 16, was a fixed 6). Old tool results are cleared, and then the earlier work is summarised, when the transcript passes half the endpoint's room. A result too long for the transcript is kept whole and read with read_result. Calls in one turn that only read run together.

  • An agent can ask another agent. An agent named in tools is a tool: it runs with its own context and only its answer comes back. Bounded by limits.depth (default 3).

  • advisor: true. A consult tool asks the strongest model on the agent's ladder for advice while a cheaper one does the work.

  • Tool search. More than a dozen service tools whose definitions pass a tenth of the endpoint's room are found with find_tools and called with use_tool instead of being listed.

  • Authored skills. skills/<name>/SKILL.md in the Agent Skills format, listed in an agent's instructions and read through read_skill. skills on an agent narrows or disables them.

  • Evals. evals/, evaluation(), app.evaluate() and praecise eval, with pass@k and pass^k over repeated trials and an exit code for CI.

  • Recall by meaning. An agent that remembers into a vector store has each exchange embedded when an endpoint names an embeds model or the app passes an embedder, and falls back to text when the embedding cannot be had.

  • MCP Tasks. A workflow called by an MCP client that declares the Tasks extension returns a task; tasks/get and tasks/cancel follow it. As a client, a tool call that returns a task is followed to its end.

  • Run notifications. notify in App.load is told when a run starts, waits at a gate, finishes or fails, as CloudEvents, to a function or as a signed webhook (Standard Webhooks). signWebhook, verifyWebhook, deliverWebhook.

  • Web Bot Auth. botAuth in App.load signs every outbound request (RFC 9421, Ed25519) and serves the key directory. signingFetch, verifySignature.

  • MCP server card and AI catalog. GET /mcp/server-card and GET /.well-known/ai-catalog.json. The catalog's shape is provisional.

  • AG-UI interrupts. A workflow streamed with ?protocol=ag-ui ends at an approval gate with an interrupt and is continued with resume.

  • A2A 1.0. The /a2a endpoint speaks 1.0 method names, card and error shapes, streams SendStreamingMessage and SubscribeToTask over SSE, paginates ListTasks, and reports a run waiting at an approval gate as TASK_STATE_INPUT_REQUIRED. A caller that speaks 0.3 is answered in 0.3.

  • Client ID Metadata Documents. OAuthClient takes clientMetadataUrl and uses it as the client id where the authorization server supports it; clientMetadataDocument() builds the document.

  • Eval cases from recordings. record: true in the config keeps each exchange under .praecise/recordings, with credentials redacted, and praecise capture <agent|workflow> (app.capture()) writes a suite from them or from a workflow's runs. An agent case replays its tool calls from the recording (AskOptions.tape); a call the recording does not hold is an error. The new reference grader compares an answer with the recorded one, by a judge or exactly. A workflow's steps run for real.

  • Online evals. online: { sample, expect, threshold } on a suite scores a sample of an agent's live answers after they are returned. The score goes to the tracer as a gen_ai.evaluation.result event and, below the threshold, to notify as com.praecise.eval.below. app.settled() waits for it.

  • Registries. registries in the config lists Agent Skills discovery indexes. praecise search looks through them and praecise add <name> installs a skill, digest checked, into skills/<name>/, or records a plugin in praecise.plugins.json with the command that installs it. There is no default registry.

  • Cancelling a run. app.cancelWorkflow(), POST /api/runs/<id>/cancel and cancelRun stop a run and record it as cancelled, reported as com.praecise.run.cancelled. A function hears it as signal in its second argument, and startWorkflow takes a signal.

  • wait steps. A workflow step that stops until a CloudEvent of a given type, source and subject arrives, with timeout and onTimeout. app.signal() continues the runs waiting for an event and app.expire() times out the ones whose time is up. A timeout fires only while a process holds the app.

  • Clocks. clock(name, { cron, zone }) or { every } is a source for app.follow, with catchUp for ticks that fell due while nothing ran. cronNext is the arithmetic.

  • An event bus, and AsyncAPI. on on a workflow names the event types that start it. app.publish(), publish in a function's second argument and POST /api/events put an event on the bus, once per source and id. The bus is in-process and matches exact types. GET /asyncapi.json describes the events an app receives and sends (AsyncAPI 3.1.0).

  • A video decoder. registerDecoder takes apart media an endpoint cannot be sent, and ffmpegDecoder does it for video over an ffmpeg binary the app names: stills as images, and the sound as audio or as a transcript.

  • Uploads. An attachment past a size is uploaded once through the endpoint's files API and named after (Attachment.fileId). uploads on an endpoint sets the size or turns it off; it is on by default for messages, responses, contents and interactions. registerUploader covers another shape.

  • Batches. app.askMany(agent, questions) hands many questions to the endpoint's batch API on messages, responses, chat and contents, and answers in order with an answer or an error each. batch: false on an endpoint sends them one at a time. registerBatch covers another shape.

  • Live sessions. app.open(agent) opens a conversation over one WebSocket where the endpoint declares realtime, with text, audio and the agent's tools through the same guard. Protocols ship for the responses, chat, contents and interactions shapes; registerSession adds one. A session has no failover.

  • Cost in money. prices on an endpoint, per million tokens per rung, gives usage.cost by currency, usage.unpricedTokens, and the span attributes praecise.usage.cost and praecise.usage.cost.currency. limits.spend caps a run and stops one that reaches an unpriced model. An eval case's budget takes spend.

  • Hooks. hooks.ts at the root, and hooks on a plugin: afterTool rewrites or withholds a result, beforeStop sends an agent back to work up to three times, beforeCompact forbids or supplies a summary, and beforeRecord decides what a self is sent.

  • Background agents. background: true on an agent lets it start the agents in its tools without waiting, and check, steer, cancel and collect them. Four may run at once in a request. AskOptions.steer says more to a request under way.

  • A permission classifier. permissionClassifier({ policy, models }) is an authority that reads a policy in prose against each call by asking a model. It sees what the person said and the calls made (Attempt.recent), never a tool's output, and refuses when it cannot decide.

  • Computer use. computer(screen) is a screen as a function, and browserScreen() is a browser to use as one. computer on an endpoint names its own computer tool, used on the messages wire.

  • @praecise/harness/formats. A plugin of readers for MCAP, ROS 1 bags, LeRobot metadata, Parquet footers, Arrow IPC schemas, PCD, PLY, Gaussian splats, USD and .npy/.npz; a ROS 2 .db3 bag is identified.

  • Typed records. schema on a store takes any Standard Schema validator. remember refuses a batch with anything outside it (SchemaError), and RecordOf is the record's type.

  • Blobs. app.blobs keeps bytes under their SHA-256. detach moves an attachment's bytes there (Attachment.blob), they are put back before a model is shown it, and sweepBlobs removes what nothing names. blobs in App.load or on a plugin replaces the folder on disk.

  • A reranker. reranks on an endpoint, or reranker in App.load, scores what a store recalled a second time; { rerank: false } leaves it out of one question.

  • Faster paths in the SQL backends. Fact walks and series aggregates run in the database on SQLite and Postgres, with time_bucket where TimescaleDB is found, and PostgreSQL 18 makes ids with uuidv7(). capabilities.faster says which a backend does, and conform holds each to the in-process answer.

  • PostgreSQL protocol 3.2, on request. max_protocol_version=3.2 (or latest) on a postgres:// url asks for it; the default stays 3.0, and a server older than 18 settles on 3.0. capabilities.detail names the version a connection settled on.

  • A Redis and Valkey driver. redis://, rediss://, valkey:// and valkeys:// urls open a store over RESP3, falling back to RESP2, using vector sets, time series and JSON where the server has them. There is no text index, and query() takes a command.

  • CAPABILITIES.md. Every capability is listed as built or declined with its reason, beside the seams a new one goes in through and what the tests do not cover.

  • MCP elicitation. mcp.elicit in App.load answers a server that asks a person for a value (form) or sends them to a page (url). Each mode is declared only when its handler is there.

  • MCP subscriptions and task notifications. watch: true on a service lists its tools again when the server says they changed. A task is followed through notifications/tasks where the server sends them, and the server sends them for its own tasks. app.onRunChange() hears run changes in process.

  • Skills over MCP. An app's authored skills are served as skills/list, skills/get and skill:// resources, and skills on a service offers that server's skills to agents through read_service_skill, checked against the server's manifest.

  • Machine grants. oauth on a service gets its token by client_credentials or by id-jag, with nobody at a keyboard.

  • MCP Apps. ui on a function, agent or workflow names a ui:// resource to show beside its result. As a host, mcp: { apps: true } hands a tool's view on as answer.ui and over AG-UI, and POST /api/ui/<service> serves what the view asks for, through the guard.

  • A2A push notifications, signed cards and HTTP+JSON. A 1.0 peer may register a webhook for a task. The agent card is signed when botAuth is set, and fetchAgentCard and verifyAgentCard check a peer's. The HTTP+JSON binding is served under /a2a. gRPC is not offered.

  • A2UI 1.0. When a turn names the catalogs its renderer draws, the agent gets a show_surface tool, and the surface is returned over A2A, AG-UI and HTTP. No renderer is included.

  • Agent Client Protocol. praecise acp (serveAcp) serves an agent to an editor over stdio.

  • A Responses endpoint. POST /v1/responses answers in the shape of the Responses API, with model naming an agent.

  • caller and context. AskOptions.caller carries anything the app adds beside person, and AskOptions.context anything else. Both reach the guard and authority (Attempt.caller, Attempt.context), functions, the meter and delegated agents, and no model. startWorkflow, resumeWorkflow and callTool take both.

  • allow. AskOptions.allow narrows the tools and knowledge an agent has for one request.

  • A meter, and a call limit. meter in App.load is asked before every model call and may refuse it (MeterRefused). AskOptions.maxCalls and limits.calls bound the model calls of one request (CallLimitReached).

  • Typed returns. returns takes a JSON Schema or a Standard Schema as well as fields and hints, and read on an agent is a check of the app's own. An answer outside either is asked for again, then from a stronger model, then ends in ShapeError. app.ask(agent, …) with the agent itself types answer.data.

  • @praecise/harness/testing. scriptedModel, scriptedEndpoint and systemText, for testing an app without a model.

  • Agent meta. meta on an agent is read by the A2A card, the MCP tool's _meta["com.praecise/meta"], llms.txt and the JSON-LD.

  • A say over what a self is sent. self.record on an agent and the beforeRecord hook rewrite or withhold it.

  • Sealed conversations and memory. threads and memory in App.load take a cipher, or a backend of the app's own.

  • Replacing agents in a running app. app.replace(), app.add() and app.remove().

  • Requests may lend tools and answer approvals. AskOptions.tools adds tools for one request, and AskOptions.approve with app.approvalOf() answers a stepUp mid-turn.

Changed

  • MCP tasks/cancel and A2A CancelTask stop the run. Before, they stopped the task being reported and the run carried on.

  • app.deliver() and POST /api/events/<workflow> continue a waiting run first. A run of the workflow stopped at a wait step the event matches is continued; a run is started only when none is waiting.

  • A function called from a tool loop receives a second argument, as one called from a workflow step does: signal, publish, transcript, caller and context.

  • StoredMemory.recall asks by text and by vector and joins the two orders by reciprocal rank.

  • GetExtendedAgentCard is answered with -32004 (unsupported operation).

  • Mcp-Name is required on tasks/get, tasks/update and tasks/cancel.

  • createApp names agents from their keys, as it does workflows.

  • An A2A skill's tags are the group it is published in, or the agent's meta.tags where it has any.

  • On PostgreSQL 18 with btree_gist, an overlapping fact is refused. facts.relate throws where the new fact's validity overlaps one already recorded.

  • A suite with online and no cases is valid.

  • app.close() waits for recordings and scores already begun.

  • An attachment weighs 1,500 tokens in the transcript, and a tool result that is cleared loses its attachments with it.

  • resources/read carries ttlMs and cacheScope.

  • capture, search and acp are built-in command names. A plugin command of one of those names is no longer reached.

  • Every wire runs under a clock, not only chat: PRAECISE_WIRE_IDLE_MS between frames of a stream and PRAECISE_WIRE_TOTAL_MS on a buffered reply.

  • Why a reply ended is one vocabulary (ChatResponse.stop). A refusal or a content filter on any wire now crosses to the next model; before, only a reply whose native reason was the word refusal did. A reply that ran out of room is reported in answer.notes.

  • retry-after is honoured, up to thirty seconds, and a 429 that is about a spend limit is not retried.

  • On the messages wire, inputTokens includes what was read from and written to the cache, as it does on every other wire. A request that hit the cache reports a larger inputTokens than it did before, with the same bill.

  • A messages request that may think is given 16,384 tokens for the thought and the answer when the endpoint declares no output. It was 4,096.

  • One tool result may take 8% of the endpoint's room in the transcript, down from 20%, because the whole result is now kept and readable.

  • AG-UI events use the standard's names and fields (RUN_STARTED, TEXT_MESSAGE_CONTENT, TOOL_CALL_RESULT with messageId and content, ACTIVITY_SNAPSHOT). A failed run ends in RUN_ERROR alone, and a refused tool call is an activity, not an error that ends the run.

  • eval is a built-in command name. A plugin command named eval is no longer reached.

  • Paths in load errors and knowledge names use forward slashes on Windows.

Fixed

  • Replacing a run file retries the rename, which failed with EPERM on Windows while another reader held the file.

  • A span's cached-token attribute is gen_ai.usage.cache_read.input_tokens, the name in the convention. It was gen_ai.usage.cached_tokens.

  • OAuthClient checks that a registration belongs to the issuer it is presented to when completing a flow and when refreshing, not only when beginning one.

0.6.1 - 2026-11-10

Fixed

  • praecise --version prints the version. It printed the usage text; only -v gave the version.

0.6.0 - 2026-11-10

Added

  • Praecise Cloud from the command line. praecise login, deploy, releases, rollback, status, logs and whoami deploy a project on Praecise Cloud, show what is live, and go back to an earlier release. The token comes from praecise login (kept in ~/.config/praecise/cloud.json, readable only by its owner) or from PRAECISE_CLOUD_TOKEN; the project from the command line, PRAECISE_PROJECT, or praecise.json in the folder. deploy --wait follows the deploy to its end and prints its log. Every command takes --json, and exits 0 when done, 1 when a deploy or rollback failed, 2 for a command that was not valid, 3 when not signed in or not allowed, 4 when there is no such project or release, and 5 when a deploy is already running. They use the runtime's own fetch and add no dependency.

Changed

  • Seven command names are now built in. A plugin command named login, deploy, releases, rollback, status, logs or whoami is no longer reached, because the built-in command answers first. Give such a plugin command another name.

0.5.0 - 2026-10-27

The first release published since 0.3.2. Versions 0.4.0 and 0.4.1 were tagged in the repository but never published, so everything they contained is listed here.

Added

  • A floor for one request. AskOptions.floor is the cheapest rung a request may start on, the mirror of ceiling. It exists for re-asking after a cheap answer was rejected: lifting a ceiling does not move a request up, because the router still enters cheapest-first, so the same small model was asked again. A floor can only remove rungs the agent declared, never add one, and with both set it is clamped to the ceiling: a floor above the ceiling gets the ceiling, never an empty ladder.

  • Code mode. code: true on an agent replaces its per-operation tools with a single code tool. The agent's HTTP services are described to the model as a typed API (MCP tools as functions, OpenAPI services as request() with the document available as spec to search), and the model's program runs in a Praecise Silo with the services bound in and their credentials kept outside it. Services launched as local programs remain ordinary tools. Exported for use outside agents: CODE_TOOL, SiloExecutor, bindingsFor, typesFor, codeTool, tsType, and the types CodeModeSpec and Binding.

  • Code mode allow rules. code: { allow: { <service>: [...] } } narrows what a program may call: tool names for MCP servers, "METHOD /path" patterns for OpenAPI services. The silo enforces them and logs every call.

  • Actions and an authority. A function can declare the action a call takes, computed from its validated arguments, and an app can pass an authority that is asked after the guard on every path to a tool. It allows, refuses with a reason, or asks for a person: on a workflow step that becomes a gate whose signed claim binds the action's digest (ApprovalClaim.digest), and the call is asked again with the verified approver in Attempt.approvals. Each verified approval carries its signature (VerifiedApproval), and a local function receives the same list as opts.approvals, so an action can present the approval to whoever checks it next.

  • Integrity labels. Functions and services carry trust; services default to untrusted. Once untrusted output has been read, every later action in the same conversation or run is marked tainted (Answer.tainted, Run.tainted).

  • A sealed journal. journal: { sink, signer } seals every finished ask and use step as a hash-chained, optionally signed entry recorded on the run before it is delivered; verifyJournal checks a chain. Wires may return evidence, collected on Answer.evidence and carried into the journal.

  • Payments on 402. payer pays a 402 met by the app's fetch under a key derived from the step's idempotency key, checking status(key, required) first so a retried step reuses a settled payment, presented in the form the server asked for. Local functions receive the app's fetch as opts.fetch.

  • Sandbox snapshots, sealed runs, durable sources, CLI plugins. sandbox snapshots after each journalled step and restores before recovery; runCipher seals run files at rest; App.follow(source, workflow) starts one run per event and resumes after the stored cursor; config plugins add praecise <name> <cmd>.

  • A local function called by a workflow use step receives the calling run and step in its options, to key what it records.

  • The package ships a NOTICE file, and the copyright holder is Praecise LTD.

Fixed

  • A workflow use step's idempotency key is SHA-256 over the workflow, the run, the step and the step's arguments. It was a 32-bit hash of the run, step and arguments, so two runs could present the same key and a deduplicating tool would skip the second one's effect.

  • A workflow defined in code (createApp, defineApp) is named by its key, as a folder names one by its file. It was left unnamed, so its runs were recorded under workflow and could not be resumed or recovered by name.

  • Endpoints that ignore stream: true. The chat wire parses a stream only when the response is text/event-stream. An endpoint that answered with one buffered completion was read as a stream with no frames, which returned an empty answer with zero usage; it is now read as the completion it is, and a streaming caller receives its whole text at once.

  • praecise init wrote a package.json depending on @praecise/harness@^0.3.0, which on a 0.x version never installs anything newer than 0.3, and praecise -v printed 0.3.0. Both now come from the package's own version.

0.3.2

Added

What a request is about, when the input carries more than the question. An app that grounds a request sends the grounding as the input, because that is what the model reads — and a self was then looking up its memory by the wrapper and recording the wrapper as the work. AskOptions.task says what was actually asked, over HTTP as task and over MCP as _meta["com.praecise/task"]. It defaults to the input, so nothing changes for an app that sends only a question.

0.3.1

Fixed

A request to the chat shape now has a clock on it. It passed only the caller's signal, so an endpoint that accepted the connection and then stopped writing held the request until something else gave up — and on an endpoint that serves one request at a time, held the slot with it. A streamed answer is now watched between frames, with the clock starting again at every frame so that a long answer arriving steadily is never cut off for being long (PRAECISE_WIRE_IDLE_MS, default 45000). One that arrives in one piece is watched as a whole (PRAECISE_WIRE_TOTAL_MS, default 240000). A timeout arrives as a ProviderError with status 0 — the shape a dead endpoint already produced — so the ladder crosses to the next model rather than asking the silent one again. The caller's own signal is composed with the clock, never replaced, so cancelling still cancels and is not reported as a provider failure.

Text that arrived is no longer thrown away with the stream that carried it. A stream that died after some of the answer had been sent lost the answer too, which had already been shown to whoever asked and already been paid for. What comes back now is the partial text, with finishReason: "timeout" and the reason in ChatResponse.notes. A stream that said nothing at all is still a rung that failed.

reasoning_effort is sent only to an endpoint that declared it takes effort. It went to every endpoint asked for any depth at all, and planModels asks for depth on the balanced and best rungs whatever the provider said — so an endpoint that takes depth as a token budget, or takes none, was sent a field it rejects outright. thinking: "effort" is now the whole of what turns it on; anything else, including saying nothing, leaves it off.

Every request to the chat shape now carries a completion ceiling. The messages shape has always defaulted one and this shape sent none, so a reply decoded without bound. It defaults to 4096 the same way. A request that asks for depth is also floored at 512: the budget covers the reasoning and the reply out of one pool, and one too small to hold both is spent entirely on the first and returns an empty answer that still bills.

Added

Provider.credentialHeader, Provider.headers and Provider.body. Three lines in a config for an endpoint with needs of its own, in place of three patches to a fork. credentialHeader names the header the credential is sent in, for an endpoint that reads a bearer as an anonymous caller and refuses it — the credential still comes from credential, so nothing in the app has to handle the secret. headers are sent with every request and applied last, so one of them wins over anything the wire would otherwise send. body is merged into the request beneath what the wire built, for the fields a runtime names and the protocol does not; what the request asks for wins, and model and the conversation are never replaceable from a config.

Limits.retries and Limits.retryDelay. How many times a rung that failed for a passing reason is asked again, and how long to wait before the first of them. The previous fixed values — 2 and 200 ms, doubling with jitter — are the defaults. Worth raising where one endpoint serves one request at a time: it refuses everything queued behind the one in flight, and crossing to another model on that is paying more precisely because the cheap one was busy.

0.3.0

Renamed

The package is now @praecise/harness; the command is still praecise. Install with npm i @praecise/harness and import from "@praecise/harness" (and "@praecise/harness/internal"). The package was previously published as praecise; that package name is deprecated and receives no further releases. praecise init writes a package.json that depends on @praecise/harness, and praecise package writes a launcher and module that import it. Everything an existing app is written against keeps its name: the praecise.config.ts config file, the .praecise/ state directory, the com.praecise/* _meta keys, every environment variable (PRAECISE_API_KEY, SELVES_URL and the rest) and the praecise-person header.

Added

Selves. An agent can declare the self it is (self: "design") and the harness reads that self's context before every request and records the work after it, through a self provider configured as selves in praecise.config.ts or passed as AppOptions.selves. {person} in a handle gives each person their own self, created from a template on first use. Answers carry answer.self with a ticket, bound to the person when SELVES_TICKET_SECRET is set, and ratings come back through App.rate or POST /api/selves/outcome. The self travels on every surface: ask, watch (a self progress event), HTTP, AG-UI, and MCP (_meta["com.praecise/self"], with the person in _meta["com.praecise/person"]). An agent that is a self keeps no second memory: self and memory together are a fault. selvesOverHttp speaks the HTTP self protocol.

A caller can name the surface it asks from (surface over HTTP, _meta["com.praecise/surface"] on an MCP tools/call), so a self answers in that surface's persona wherever the agent is reached. A verdict on a self's answer can carry a check, something the app measured about what came of it, through App.rate, POST /api/selves/outcome and the HTTP self protocol.

Protocols. The current MCP revision, 2026-07-28, on both the client and the server, with no dual-era fallback — it is a stateless protocol, so the initialize handshake, session header, standalone GET stream, ping, logging/setLevel and SSE resumability are gone, and every request carries its own version, capabilities and identity. A2A 1.0 publishes the app as an agent a peer can delegate to, with an agent card at /.well-known/agent-card.json. AG-UI streams to whoever is watching: ?protocol=ag-ui on any agent endpoint, with ?stream= selecting messages, tools, updates, custom or values.

OAuth 2.1 for MCP servers that are protected resources, with the parts that exist because of an attack rather than a feature: resource indicators (RFC 8707) on both the authorization and token request, byte-exact issuer validation (RFC 9207), PKCE, and registrations keyed by issuer so one is never presented to a server that did not mint it.

OpenAPI descriptions become tools. tool({ openapi }) is a third kind of service alongside url and command; operations are flattened into the single object a model produces, and the location of each value is remembered rather than guessed at call time.

An SDK door. createApp takes an app as a value rather than reading a folder, for shipping agents in a package, running where there is no filesystem to scan, or assembling an app from parts. mergeApps composes definitions and reports collisions instead of letting one silently disappear. Both doors build the same project and run the same checks.

A TypeScript build step. Every .ts file is compiled into .praecise/build before anything is imported, using the compiler in your own project, so a TypeScript app runs on a Node that cannot read TypeScript. One broken file costs you that file rather than the whole app.

Discovery, for machines. /llms.txt, JSON-LD at /ai.json, a robots.txt inverted for an app where there is little to index and much that costs a model call, and /ask — an NLWeb-shaped endpoint that answers a natural-language question from the app's own store, at a rung the operator caps.

An ingestion pipeline. praecise ingest <dir> --store <name> reads PDFs, Word, Excel, PowerPoint, CSV, images and source into a store; --fields asks a model to pull named values out of each chunk. Idempotent on content, so running it twice does not double the catalogue.

Tracing, forking, and a page to look at them. OpenTelemetry GenAI spans, with no OpenTelemetry dependency — the convention is in the data and the transport is yours. Trace context crosses into MCP via traceparent. forkRun branches a run from a past step, optionally patching an earlier output, recording who did it. praecise dev serves /traces, a timeline of what the last few requests did.

praecise doctor says everything wrong with an app in one pass, ranked by whether it stops the app running, and exits non-zero only on the blocking kind.

Changed

  • fn, workflow and prompt infer from what they declare. run's arguments come from input, after only accepts step ids that exist, and a prompt's {{placeholders}} must name declared fields. Each of these was previously a silent runtime failure: an undeclared field arrived as undefined, a mistyped after produced a step that was never ready, and a mistyped placeholder interpolated to nothing and sent the model a sentence with a hole in it.
  • AskOptions.ceiling caps how expensive a request may get, trimming an agent's ladder so escalation still works below it.

Fixed

  • App.load crashed with a raw TypeError when an agent had no role — the loader recorded the fault and then the planner destroyed the report describing it.
  • clientFor and collectTools both tested for an API key alone, making stdio MCP servers unreachable by construction.
  • The interactions wire computed a warning about silently-dropped sampling parameters and put it on a type nobody holds.
  • praecise init wrote a .ts app that the runtime could not load.
  • Store errors, resource reads, and protocol refusals now carry cause or a named error rather than a flattened string.

Changed

  • Breaking (shape of the public API), ahead of 1.0. The package root now exports the public API and nothing else. It previously exported 98 values and 122 types, most of which were the framework's own moving parts — a planner, a loader, provider wire formats, MCP request handlers, the packager, the CLI entry point. Tagging 1.0 would have semver-locked every one of them, which would either be a promise the project could not keep or a freeze on its own insides.

    Nothing was deleted. 38 values and 16 types moved to the new @praecise/harness/internal subpath (see Added), so every current import keeps working after a one-line change to the specifier, and nobody has to fork the framework to reach something they genuinely need.

    Moved to @praecise/harness/internal: findCycle, loadProject, resolveKnows, canConvert, ingestFile, converterFor, planAgent, planProject, planWorkflowAgent, schemaFor, adapterFor, chatWire, contentsWire, messagesWire, stateDirFor, stream, trim, asObjects, urlFor, checkSteps, provisioner, runCommand, splitCommand, openChannel, callPublished, groupsOf, handleMcp, noticesOf, promptsOf, resourcesOf, toolsOf, apiModule, apiTypes, faultsIn, hintsIn, buildPackage, manifestFor, cli; and the types Importer, LoadOptions, Converted, Converter, ConvertRequest, IngestOptions, PlanOptions, Manifest, ProvisionerDeps, Channel, Caller, McpTool, Describable, PackageManifest, PackageOptions, PackageResult.

    The authoring surface, the running surface, the harness contract, the store and driver surface, and the dialect codec and latent transport are all unchanged and stay at the root.

  • The api.js module generated by buildPackage now imports callPublished from @praecise/harness/internal rather than from the root. It is regenerated on every build, so it tracks whichever version of praecise built it.

Added

  • @praecise/harness/internal, a second entry point holding everything demoted above. It is explicitly not covered by semantic versioning: names there may change, be renamed, or disappear in any release, patch releases included, with no deprecation period. It exists so that necessity does not force a fork, not as a second API.

  • API.md, the written-down public API, grouped by task — authoring, running, the harness, storage and driver extension, dialect and latent transport, observability — with one line per name and a plain statement of what @praecise/harness/internal does and does not promise.

  • CHANGELOG.md (this file).

  • Types that exported types already referred to but which could not be imported. AgentSpec.access is an Access, WorkflowSpec.outcome is a Check, and every published spec extends Published, yet none of the three were exported; their sibling Effect was, which is what makes it an oversight rather than a decision. Now exported: Access, Check, Published.

  • ProviderError. The documented ChatAdapter contract says an adapter should throw it, and an adapter author outside this repository could not reach it.

  • ApprovalClaim and ApprovalDecision, for the same reason: WorkflowDeps asks for sign(claim: ApprovalClaim) and verify, and neither type was importable.

  • Wire and wireOptionsFrom, with their types WireOptions, WireResult and Held. They were exported from the stores barrel but omitted from the root, so a driver author could not reuse the Postgres wire framing.

  • Project and Doc are now documented as public rather than incidental: they are the type of App.project.

  • LocalTool and ResolvedService join AgentPlan and Rung at the root, so an AgentPlan — which a custom WorkflowDeps.planFor has to return — can be written down without unnameable fields.

Edit this page on GitHub · Read it as Markdown

    Type to search. Arrow keys move, Enter opens.