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 aSKILL.mdis 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 ordefineApptakes.
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
memoryhas 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.storeis 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.acceptanswers 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.proposeisApp.reflect, andpraecise memory --proposeis--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 withAlreadyReflecting.- A driver's
Connectionhasadd. It keeps a row only if nothing is kept under its id, decided by the backend in one step. Every shipped driver implements it andconformchecks 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/node26.6.
Removed
- A memory backend of the app's own.
AppOptions.memorytakes a cipher and nothing else; memory is kept elsewhere by naming a store, and a backend the framework does not ship is aDriver.Recollection,MemoryandStoredMemoryare no longer exported. SkillBook,usableProcedures,renderSkills,settleand their types.MemorySpec.write, which was never read.
Added
- Memory tools. An agent with memory is given
search_memory,read_memoryandwrite_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 bypraecise dev,serve()orapp.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> --memoryandApp.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 onresponses,reasoning_contentorreasoningonchat, and thought steps oninteractionsare 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
messageswire. 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: falseon an endpoint turns it off.Usage.cacheWriteTokensreports what was kept. -
Attachments.
AskOptions.attachments, andattachmentsonPOST /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
contentsandinteractions, and onchatwhere the endpoint'stakessays 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.registerReaderadds a reader. -
Tool results carry media. A function returns
attach(result, ...attachments), and an MCP tool's image, audio, embedded file orhttps: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 oncontents,interactionsandchatcome back with the answer. -
Values, facts and series on every store.
store.valueskeeps a value under a name in a namespace, with an optional lifetime.store.factsrecords 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.serieskeeps 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>andapp.deliver()start a run for a CloudEvent, once persourceandid. -
Plugins bring more than commands. A plugin in
pluginsmay carryapp(a piece of an app, merged under the app's own folder),drivers, andsetup.commandsis now optional. The type isPlugin;CliPluginremains as its alias. -
Depth words, output room and embeddings are the endpoint's to declare.
levels,outputandembedson a model endpoint. -
Longer work in one request.
turnson 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'sroom. A result too long for the transcript is kept whole and read withread_result. Calls in one turn that only read run together. -
An agent can ask another agent. An agent named in
toolsis a tool: it runs with its own context and only its answer comes back. Bounded bylimits.depth(default 3). -
advisor: true. Aconsulttool 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
roomare found withfind_toolsand called withuse_toolinstead of being listed. -
Authored skills.
skills/<name>/SKILL.mdin the Agent Skills format, listed in an agent's instructions and read throughread_skill.skillson an agent narrows or disables them. -
Evals.
evals/,evaluation(),app.evaluate()andpraecise eval, withpass@kandpass^kover 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
embedsmodel or the app passes anembedder, 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/getandtasks/cancelfollow it. As a client, a tool call that returns a task is followed to its end. -
Run notifications.
notifyinApp.loadis 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.
botAuthinApp.loadsigns every outbound request (RFC 9421, Ed25519) and serves the key directory.signingFetch,verifySignature. -
MCP server card and AI catalog.
GET /mcp/server-cardandGET /.well-known/ai-catalog.json. The catalog's shape is provisional. -
AG-UI interrupts. A workflow streamed with
?protocol=ag-uiends at an approval gate with an interrupt and is continued withresume. -
A2A 1.0. The
/a2aendpoint speaks 1.0 method names, card and error shapes, streamsSendStreamingMessageandSubscribeToTaskover SSE, paginatesListTasks, and reports a run waiting at an approval gate asTASK_STATE_INPUT_REQUIRED. A caller that speaks 0.3 is answered in 0.3. -
Client ID Metadata Documents.
OAuthClienttakesclientMetadataUrland uses it as the client id where the authorization server supports it;clientMetadataDocument()builds the document. -
Eval cases from recordings.
record: truein the config keeps each exchange under.praecise/recordings, with credentials redacted, andpraecise 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 newreferencegrader 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 thetraceras agen_ai.evaluation.resultevent and, below the threshold, tonotifyascom.praecise.eval.below.app.settled()waits for it. -
Registries.
registriesin the config lists Agent Skills discovery indexes.praecise searchlooks through them andpraecise add <name>installs a skill, digest checked, intoskills/<name>/, or records a plugin inpraecise.plugins.jsonwith the command that installs it. There is no default registry. -
Cancelling a run.
app.cancelWorkflow(),POST /api/runs/<id>/cancelandcancelRunstop a run and record it ascancelled, reported ascom.praecise.run.cancelled. A function hears it assignalin its second argument, andstartWorkflowtakes asignal. -
waitsteps. A workflow step that stops until a CloudEvent of a given type,sourceandsubjectarrives, withtimeoutandonTimeout.app.signal()continues the runs waiting for an event andapp.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 forapp.follow, withcatchUpfor ticks that fell due while nothing ran.cronNextis the arithmetic. -
An event bus, and AsyncAPI.
onon a workflow names the event types that start it.app.publish(),publishin a function's second argument andPOST /api/eventsput an event on the bus, once persourceandid. The bus is in-process and matches exact types.GET /asyncapi.jsondescribes the events an app receives and sends (AsyncAPI 3.1.0). -
A video decoder.
registerDecodertakes apart media an endpoint cannot be sent, andffmpegDecoderdoes it for video over anffmpegbinary 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).uploadson an endpoint sets the size or turns it off; it is on by default formessages,responses,contentsandinteractions.registerUploadercovers another shape. -
Batches.
app.askMany(agent, questions)hands many questions to the endpoint's batch API onmessages,responses,chatandcontents, and answers in order with an answer or an error each.batch: falseon an endpoint sends them one at a time.registerBatchcovers another shape. -
Live sessions.
app.open(agent)opens a conversation over one WebSocket where the endpoint declaresrealtime, with text, audio and the agent's tools through the same guard. Protocols ship for theresponses,chat,contentsandinteractionsshapes;registerSessionadds one. A session has no failover. -
Cost in money.
priceson an endpoint, per million tokens per rung, givesusage.costby currency,usage.unpricedTokens, and the span attributespraecise.usage.costandpraecise.usage.cost.currency.limits.spendcaps a run and stops one that reaches an unpriced model. An eval case'sbudgettakesspend. -
Hooks.
hooks.tsat the root, andhookson a plugin:afterToolrewrites or withholds a result,beforeStopsends an agent back to work up to three times,beforeCompactforbids or supplies a summary, andbeforeRecorddecides what a self is sent. -
Background agents.
background: trueon an agent lets it start the agents in itstoolswithout waiting, and check, steer, cancel and collect them. Four may run at once in a request.AskOptions.steersays 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, andbrowserScreen()is a browser to use as one.computeron an endpoint names its own computer tool, used on themessageswire. -
@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.db3bag is identified. -
Typed records.
schemaon a store takes any Standard Schema validator.rememberrefuses a batch with anything outside it (SchemaError), andRecordOfis the record's type. -
Blobs.
app.blobskeeps bytes under their SHA-256.detachmoves an attachment's bytes there (Attachment.blob), they are put back before a model is shown it, andsweepBlobsremoves what nothing names.blobsinApp.loador on a plugin replaces the folder on disk. -
A reranker.
rerankson an endpoint, orrerankerinApp.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_bucketwhere TimescaleDB is found, and PostgreSQL 18 makes ids withuuidv7().capabilities.fastersays which a backend does, andconformholds each to the in-process answer. -
PostgreSQL protocol 3.2, on request.
max_protocol_version=3.2(orlatest) on apostgres://url asks for it; the default stays 3.0, and a server older than 18 settles on 3.0.capabilities.detailnames the version a connection settled on. -
A Redis and Valkey driver.
redis://,rediss://,valkey://andvalkeys://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, andquery()takes a command. -
CAPABILITIES.md. Every capability is listed asbuiltordeclinedwith its reason, beside the seams a new one goes in through and what the tests do not cover. -
MCP elicitation.
mcp.elicitinApp.loadanswers 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: trueon a service lists its tools again when the server says they changed. A task is followed throughnotifications/taskswhere 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/getandskill://resources, andskillson a service offers that server's skills to agents throughread_service_skill, checked against the server's manifest. -
Machine grants.
oauthon a service gets its token byclient_credentialsor byid-jag, with nobody at a keyboard. -
MCP Apps.
uion a function, agent or workflow names aui://resource to show beside its result. As a host,mcp: { apps: true }hands a tool's view on asanswer.uiand over AG-UI, andPOST /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
botAuthis set, andfetchAgentCardandverifyAgentCardcheck 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_surfacetool, 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/responsesanswers in the shape of the Responses API, withmodelnaming an agent. -
callerandcontext.AskOptions.callercarries anything the app adds besideperson, andAskOptions.contextanything else. Both reach the guard and authority (Attempt.caller,Attempt.context), functions, the meter and delegated agents, and no model.startWorkflow,resumeWorkflowandcallTooltake both. -
allow.AskOptions.allownarrows the tools and knowledge an agent has for one request. -
A meter, and a call limit.
meterinApp.loadis asked before every model call and may refuse it (MeterRefused).AskOptions.maxCallsandlimits.callsbound the model calls of one request (CallLimitReached). -
Typed
returns.returnstakes a JSON Schema or a Standard Schema as well as fields and hints, andreadon 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 inShapeError.app.ask(agent, …)with the agent itself typesanswer.data. -
@praecise/harness/testing.scriptedModel,scriptedEndpointandsystemText, for testing an app without a model. -
Agent
meta.metaon an agent is read by the A2A card, the MCP tool's_meta["com.praecise/meta"],llms.txtand the JSON-LD. -
A say over what a self is sent.
self.recordon an agent and thebeforeRecordhook rewrite or withhold it. -
Sealed conversations and memory.
threadsandmemoryinApp.loadtake a cipher, or a backend of the app's own. -
Replacing agents in a running app.
app.replace(),app.add()andapp.remove(). -
Requests may lend tools and answer approvals.
AskOptions.toolsadds tools for one request, andAskOptions.approvewithapp.approvalOf()answers astepUpmid-turn.
Changed
-
MCP
tasks/canceland A2ACancelTaskstop the run. Before, they stopped the task being reported and the run carried on. -
app.deliver()andPOST /api/events/<workflow>continue a waiting run first. A run of the workflow stopped at awaitstep 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,callerandcontext. -
StoredMemory.recallasks by text and by vector and joins the two orders by reciprocal rank. -
GetExtendedAgentCardis answered with -32004 (unsupported operation). -
Mcp-Nameis required ontasks/get,tasks/updateandtasks/cancel. -
createAppnames 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.tagswhere it has any. -
On PostgreSQL 18 with
btree_gist, an overlapping fact is refused.facts.relatethrows where the new fact's validity overlaps one already recorded. -
A suite with
onlineand 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/readcarriesttlMsandcacheScope. -
capture,searchandacpare 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_MSbetween frames of a stream andPRAECISE_WIRE_TOTAL_MSon 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 wordrefusaldid. A reply that ran out of room is reported inanswer.notes. -
retry-afteris honoured, up to thirty seconds, and a 429 that is about a spend limit is not retried. -
On the
messageswire,inputTokensincludes what was read from and written to the cache, as it does on every other wire. A request that hit the cache reports a largerinputTokensthan it did before, with the same bill. -
A
messagesrequest that may think is given 16,384 tokens for the thought and the answer when the endpoint declares nooutput. It was 4,096. -
One tool result may take 8% of the endpoint's
roomin 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_RESULTwithmessageIdandcontent,ACTIVITY_SNAPSHOT). A failed run ends inRUN_ERRORalone, and a refused tool call is an activity, not an error that ends the run. -
evalis a built-in command name. A plugin command namedevalis 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
EPERMon 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 wasgen_ai.usage.cached_tokens. -
OAuthClientchecks 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 --versionprints the version. It printed the usage text; only-vgave the version.
0.6.0 - 2026-11-10
Added
- Praecise Cloud from the command line.
praecise login,deploy,releases,rollback,status,logsandwhoamideploy a project on Praecise Cloud, show what is live, and go back to an earlier release. The token comes frompraecise login(kept in~/.config/praecise/cloud.json, readable only by its owner) or fromPRAECISE_CLOUD_TOKEN; the project from the command line,PRAECISE_PROJECT, orpraecise.jsonin the folder.deploy --waitfollows 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 ownfetchand add no dependency.
Changed
- Seven command names are now built in. A plugin command named
login,deploy,releases,rollback,status,logsorwhoamiis 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.flooris the cheapest rung a request may start on, the mirror ofceiling. 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: trueon an agent replaces its per-operation tools with a singlecodetool. The agent's HTTP services are described to the model as a typed API (MCP tools as functions, OpenAPI services asrequest()with the document available asspecto 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 typesCodeModeSpecandBinding. -
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
actiona call takes, computed from its validated arguments, and an app can pass anauthoritythat 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'sdigest(ApprovalClaim.digest), and the call is asked again with the verified approver inAttempt.approvals. Each verified approval carries its signature (VerifiedApproval), and a local function receives the same list asopts.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 markedtainted(Answer.tainted,Run.tainted). -
A sealed journal.
journal: { sink, signer }seals every finishedaskandusestep as a hash-chained, optionally signed entry recorded on the run before it is delivered;verifyJournalchecks a chain. Wires may returnevidence, collected onAnswer.evidenceand carried into the journal. -
Payments on 402.
payerpays a 402 met by the app's fetch under a key derived from the step's idempotency key, checkingstatus(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 asopts.fetch. -
Sandbox snapshots, sealed runs, durable sources, CLI plugins.
sandboxsnapshots after each journalled step and restores before recovery;runCipherseals run files at rest;App.follow(source, workflow)starts one run per event and resumes after the stored cursor; configpluginsaddpraecise <name> <cmd>. -
A local function called by a workflow
usestep receives the callingrunandstepin its options, to key what it records. -
The package ships a
NOTICEfile, and the copyright holder is Praecise LTD.
Fixed
-
A workflow
usestep'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 underworkflowand could not be resumed or recovered by name. -
Endpoints that ignore
stream: true. Thechatwire parses a stream only when the response istext/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 initwrote apackage.jsondepending on@praecise/harness@^0.3.0, which on a 0.x version never installs anything newer than 0.3, andpraecise -vprinted0.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,workflowandpromptinfer from what they declare.run's arguments come frominput,afteronly 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 asundefined, a mistypedafterproduced 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.ceilingcaps how expensive a request may get, trimming an agent's ladder so escalation still works below it.
Fixed
App.loadcrashed with a rawTypeErrorwhen an agent had norole— the loader recorded the fault and then the planner destroyed the report describing it.clientForandcollectToolsboth 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 initwrote a.tsapp that the runtime could not load.- Store errors, resource reads, and protocol refusals now carry
causeor 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/internalsubpath (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 typesImporter,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.jsmodule generated bybuildPackagenow importscallPublishedfrom@praecise/harness/internalrather 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/internaldoes and does not promise. -
CHANGELOG.md(this file). -
Types that exported types already referred to but which could not be imported.
AgentSpec.accessis anAccess,WorkflowSpec.outcomeis aCheck, and every published spec extendsPublished, yet none of the three were exported; their siblingEffectwas, which is what makes it an oversight rather than a decision. Now exported:Access,Check,Published. -
ProviderError. The documentedChatAdaptercontract says an adapter should throw it, and an adapter author outside this repository could not reach it. -
ApprovalClaimandApprovalDecision, for the same reason:WorkflowDepsasks forsign(claim: ApprovalClaim)andverify, and neither type was importable. -
WireandwireOptionsFrom, with their typesWireOptions,WireResultandHeld. They were exported from the stores barrel but omitted from the root, so a driver author could not reuse the Postgres wire framing. -
ProjectandDocare now documented as public rather than incidental: they are the type ofApp.project. -
LocalToolandResolvedServicejoinAgentPlanandRungat the root, so anAgentPlan— which a customWorkflowDeps.planForhas to return — can be written down without unnameable fields.