# Changelog

All notable changes to this project are documented here.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
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.
