Praecise Harness v1.1.0 Get started

Documentation · Reference

The public API

Everything exported from @praecise/harness is listed here. From 1.0 onwards this list is what semantic versioning covers: a name on this page will not be removed, and its shape will not change incompatibly, without a major release.

Anything not on this page is not part of the promise, even if you can reach it. In particular:

@praecise/harness/internal is unstable and unversioned. Every name behind that subpath may change, be renamed, or disappear in any release, including a patch release. There is no deprecation period. It exists so that needing one of the framework's own moving parts does not force you to fork the framework — not as a second API. If something you genuinely need is only reachable there, please open an issue; that is a gap in the surface below.

Deep imports (@praecise/harness/dist/...) are not reachable at all. The package's exports map has exactly five entries: ., ./internal, ./formats, ./testing, and ./package.json. @praecise/harness/formats and @praecise/harness/testing are public and are listed below.


Authoring — writing the app

A folder of these calls is the app. This is the only part most apps ever use.

Name What it is
agent Declare an agent: a role, what it knows, what it may act through.
workflow Declare a sequence or graph of steps, with a declared outcome.
tool Declare an external service the app may call.
fn Declare a local function an agent may call. http: "POST /webhook" also serves it at that method and path on the dev server.
prompt Declare a named, parameterised prompt.
resource Declare a readable resource addressed by URI.
store Declare a backing store (sql, vector, document, timeseries; graph needs a brought backend — see Storage).
guard Declare a check that runs before a call and may refuse it.
hooks Declare what happens after a tool runs, before an agent stops, before a transcript is summarised, and before a self is sent its record (hooks.ts).
middleware Wrap every call the app makes.
knowledge Declare a document the app knows, in code rather than in memory/.
blueprint Declare a set of files that scaffolds a whole app.
template Declare a set of files that scaffolds one part of one.
evaluation Declare an eval suite: an agent or workflow, cases, and what a right answer looks like.
defineConfig The contents of praecise.config.ts.
QUALITIES The ladder rungs, in order: fast, balanced, best. Frozen.

Narrowing a step. A Step is a union; these tell you which arm you have.

isAsk · isUse · isApprove · isWait · isPlan · isEach · isRepeat · isWhen

Each asks whether the step carries that discriminant as its OWN key with a value that is not undefined — so { ask: cond ? "x" : undefined, use: "svc.fallback" } is a use, and a key inherited from a prototype does not classify anything. STEP_KINDS is the same eight names in the order the runner dispatches them, and kindsOf(step) returns the ones a step carries. A step carrying more than one is refused when the workflow loads: nothing can tell which was meant, and guessing is how a nested body came to be validated, reported, and never run.

Types. One *Spec per kind (what the call returns) and one *Input per kind (what you pass it):

AgentSpec/AgentInput · WorkflowSpec/WorkflowInput · ToolSpec/ToolInput · FunctionSpec/FunctionInput · PromptSpec/PromptInput · ResourceSpec/ResourceInput · StoreSpec/StoreInput · GuardSpec/GuardInput · MiddlewareSpec/MiddlewareInput · KnowledgeSpec/KnowledgeInput · BlueprintSpec/BlueprintInput · TemplateSpec/TemplateInput · EvaluationSpec/EvaluationInput · HooksSpec/HooksInput

An authored skill (skills/<name>/SKILL.md) has no call of its own; in a code-defined app it is AuthoredSkillInput, and loaded it is AuthoredSkill.

Supporting types:

Type What it describes
Published What every published thing declares: access, effect, group.
Access Who may reach it: "open", "gated", "internal".
Effect What calling it does: "read", "write", "destructive".
Step The step union, and its arms AskStep, UseStep, ApproveStep, WaitStep, EachStep, WhenStep, RepeatStep, PlanStep. A WaitStep stops a run until a CloudEvent of the wait type arrives, narrowed by source and subject, with a timeout in seconds and onTimeout: "fail" | "continue".
Check What a repeat runs until, and what a workflow's outcome asserts.
Ref A reference into the run's scope, written as text.
Returns A declared output shape: field names to plain-English hints, a JSON Schema object, or a Standard Schema validator. DataOf<Declared> is what answer.data is for one.
Quality One rung of the ladder.
Limits Ceilings a run inherits: depth, concurrency, timeout, budget, calls (model calls one request may make), spend (a Money one run may spend, counted from declared prices), and how patient to be with an endpoint that is merely busy — retries (default 2) and retryDelay (default 200 ms, doubling with jitter).
Money, Prices, Rates An amount in a named currency; what an endpoint charges per rung (prices on a model endpoint); and what a million tokens cost on one model (input, output, cachedRead, cacheWrite, reasoning).
AgentMeta meta on an agent: version, tags, languages, inputModes, outputModes, examples, and anything else, for the surfaces that list the agent.
FunctionRunOptions, Publish The second argument of a function's run: idempotencyKey, run, step, fetch, approvals, signal, publish (a Publish, which puts an event on the app's bus), transcript, caller and context.
ToolOutcome, Stopping, Compacting, AfterTool, BeforeCompact What each hook is handed, and what afterTool and beforeCompact may answer.
OnlineEval, RecordedRun, RecordedTool online on an eval suite (sample, expect, threshold), and the recorded run a captured case carries (answer, data, tools).
ServiceOAuth oauth on a service: the client_credentials or id-jag grant its token is obtained with.
RecordOf, RecordInputOf, TypedStoreSpec The record a store's schema describes, what it accepts on the way in, and a store declared with one.
Recent One entry of Attempt.recent: something the person said, or a call the agent made.
MemorySpec How an agent remembers: store (all of its memory goes there; AppConfig.store is the default), recall, and reflect (a schedule on which its record is read back, started by praecise dev, serve() or app.tend()).
App.reflect, App.tend, App.pending, App.accept, App.reject, App.retire, App.learned, App.carried, App.recorded, App.jotted, App.jot, App.filed, App.page, App.redact, App.clearMemory, App.evaluateMemory An agent's memory from code: read its record back, decide on what is proposed, see and change what is kept, and measure what memory is worth on a suite. Reflection, MemoryGain, AlreadyReflecting.
AppConfig The praecise.config.ts shape: name, version, description, quality, preference, explore, port, models, limits, store, stateDir, strict (or PRAECISE_STRICT in the environment where the config says nothing), record, registries, plugins, ask, ingest, selves.
Provider, ModelProvider An endpoint the app may call: url, credential, and three fields for an endpoint with needs of its own — credentialHeader (the header the credential goes in, where a bearer is refused), headers (sent with every request, and applied last), and body (fields merged into the request that the protocol does not name; what the request itself asks for always wins).
Call, Reply, Attempt What middleware and guards are handed.
FileContents One file a blueprint or template writes.
StoreKind Which kind of store a store() declares.
StepKind One of STEP_KINDS.
Preference preference in the config: "cost", "balanced" (default) or "quality" — what the deployment values when cost and quality pull apart. Under "quality" the strongest rung answers and nothing is checked.
EvalCase, Grader, GraderKind, GRADER_KINDS One case of an eval (name, input, expect, budget in tokens or money, recorded), the graders it may expect (contains, excludes, matches, equals, fields, calls, avoids, judge, reference, check), and their names.
CodeModeSpec code on an agent: silo, language (typescript, javascript, python), ttl (seconds, default 1800) and allow. See Code mode.

Running — loading a folder and driving it

Name What it does
App Load a folder into a running app. App.load({ root }).
AppOptions What App.load accepts: root, env, fetch, drivers, telemetry sink, prefer (one endpoint from models put first, whatever order they are declared in), askConcurrency (how many asks may be in flight at once, 8 by default), maxInput (the longest input one ask may carry, 200,000 characters by default), and the seams listed on this page — embedder, reranker, blobs, approvals, authority, journal, payer, botAuth, notify, runCipher, threads, memory, sandbox, tracer, recorder, selves, mcp, meter, WebSocket.
startRun Start a workflow run.
resumeRun Resume one that stopped at a human approval gate.
cancelRun Stop a run and record it as cancelled. App.cancelWorkflow(id, { reason, by }) is the same over a loaded app.
signalRun, timeoutRun, awaits Continue a run stopped at a wait step with the event it awaited, end a wait that ran out of time, and say whether a run is waiting for a given event. App.signal(event) and App.expire() are the same over a loaded app.
subscriptionsOf The CloudEvent types a workflow's on names. App.publish(event) starts a run of every workflow that declared the type and continues every run waiting for it.
clock, cronNext A Source that ticks every so many seconds or by a five-field cron expression in a time zone, for App.follow; and the next time an expression falls due. Types: ClockOptions, Schedule, Tick.
recoverRun Re-drive a run that was interrupted, refusing where exactly-once cannot be proven.
RunStore Where runs are persisted, and how they are listed and loaded.
serve Bring up the dev server: chat UI, REST, and an MCP endpoint.
serveStdio Serve the app over MCP on stdio, for an editor or another agent.
followRun Async-iterate a run's events, from the start and then as they arrive.
provenanceOf Build the graph of what a run derived from what.
createApp An app described in code (AppDefinition) rather than a folder, ready to run. Refuses a faulted definition.
defineApp The same definition checked into a Project without starting it, so warnings and faults can be read first.
mergeApps Compose definitions; later ones win, and every collision is reported in collisions.
cloudEvent, readCloudEvents, CLOUDEVENTS_JSON, CLOUDEVENTS_BATCH Mint a CloudEvents 1.0 event; read the events an HTTP request carries (structured, batched or binary), or a sentence saying why it carries none; and the two media types. App.deliver(workflow, event) continues the run of that workflow waiting for the event, or starts one, once per source + id.
App.replace, App.add, App.remove Replace an agent of a running app, add one, or remove one by name. Requests under way finish on the plan they started with.
App.askMany Many questions for one agent through the endpoint's batch API; a Batched ({ answer } or { error }) per question, in order.
App.open Open a live session with an agent (OpenOptions), returning a Session.
App.capture, App.settled Eval cases from an agent's recordings or a workflow's runs; and a promise for the recording and scoring already begun.
App.approvalOf Verify a person's decision on a StepUp, for AskOptions.approve to return.
App.onRunChange Hear each RunTransition in this process; returns the function that stops listening.
App.blobs, App.threads The app's BlobStore and its conversations.
runEvaluation, runEvaluations Run one eval suite, or several, against anything that can ask an agent and run a workflow. App.evaluate(suite?, options) is the same over a loaded app.
evaluationFaults What is wrong with an eval suite as written.
renderReport An EvalReport as the table praecise eval prints.
Recordings, casesFromRecordings, casesFromRuns, renderCapturedSuite Exchanges kept as they occurred (record: true in the config, or AppOptions.recorder), eval cases made from them or from a workflow's runs, and a suite file written from those cases. Types: Recorder, Recording, ReferenceMode.
recordingTape, replayTape, redacted A ToolTape that writes a request's tool calls down, one that answers them from a recording, and a recording with credentials taken out.
scoreAnswer, evaluationSpan, EVALUATION_EVENT Score one live answer with a suite's online graders (OnlineScore), the span that carries the score, and the name of its event, gen_ai.evaluation.result.
EVAL_EVENT_TYPES, evalEvent, EvalNotice The notification sent when a live score falls below its threshold (com.praecise.eval.below), as a CloudEvent.
DISCOVERY_SCHEMA, WELL_KNOWN_SKILLS, indexUrlOf, parseIndex, searchEntries Reading a registry: the discovery schema followed, the well-known path of an index, the index URL for a registry as configured, an index parsed into RegistryEntry rows, and a search over them.
skillsIn Read a folder of skills (one directory per skill, a SKILL.md and the text files beside it) into the record Plugin.app.skills and defineApp take.
fetchSkill, installSkill, installCommand, recordPlugin, readRecordedPlugins, readRegistries, PLUGINS_FILE Installing from a registry: fetch a skill and check its digest (FetchedSkill), write it to skills/<name>/, the install command for a plugin, record a plugin in praecise.plugins.json (RecordedPlugin), and read that file and the configured registries.
unpackArchive, safeRelativePath Unpack a skill archive within limits (ArchiveFile, ArchiveLimits), and refuse a path that would leave the folder it is written to.

Types: Run, RunStatus, RunEvent, PlanVersion, Outcome, ProvGraph, WorkflowDeps, GenAiSpan, ProvisionRequest, ProvisionResult, ApprovalClaim, ApprovalDecision, VerifyResult, DevServer, ServeOptions, StdioServer, StdioOptions, Project, Doc, AgentPlan, LocalTool, ResolvedService, Rung, AppDefinition, Approvals (the shape of AppOptions.approvals: the signer and verifier for gates), EvalOptions, EvalReport, SuiteReport, CaseReport, TrialReport, EvalTarget, EvalJudge, CloudEvent, Plugin (what plugins in the config takes: name, commands, app, hooks, drivers, blobs, setup; CliPlugin is its earlier name), ToolContext (what a LocalTool's run is handed besides its arguments: the transcript so far and the request's signal), AwaitedEvent (what a run stopped at a wait step is waiting for).

RunStatus includes cancelled. Span carries events (SpanEvent).

An AgentPlan also carries delegates (other agents named in tools), turns and advisor. A Rung carries levels, output and cache where the provider declared them.

Project and Doc are what App.project is. AgentPlan is what an agent was compiled into — the composed instructions, the rungs to try, the tools it may call — and is what a custom WorkflowDeps.planFor must return.

ApprovalClaim is exactly what an approval signature covers; implement WorkflowDeps.sign/verify against it. With no signer, nothing is synthesised — the ledger records the approval as unsigned rather than inventing a signature.

Acting under rules — actions, authority, payments, journal

What an app needs when its agents act for someone under rules it does not write itself. Every piece is optional and off until passed to App.load.

Name What it does
Action A side effect in checkable terms: operation, counterparty, amount, asset, network, model, detail; tainted is set by the runtime. A function declares one with action(args).
Trust "trusted" or "untrusted" on a function (trust) or a service (ToolSpec.trust, default untrusted). Reading untrusted output taints every later action in that conversation or run.
Authority, Verdict AppOptions.authority: check(attempt) answers a Verdict — allow, refuse or stepUp with a digest. Asked after the guard on every path to a tool.
StepUpRequired What a direct call throws on stepUp. A workflow use step turns it into a gate named <step>:approve whose signed ApprovalClaim carries the digest; the call is asked again with the verified approval (subject, digest, signature) in Attempt.approvals, and a local function receives the same list as opts.approvals (FunctionRunOptions, each a VerifiedApproval) to present onward. In a conversation it is a refusal the model reads.
Journal, Signer, JournalSink AppOptions.journal: every finished ask and use step is sealed as a JournalEntry (input and output digests, action, approvals, payments, evidence, sandbox snapshot), hash-chained, signed when a signer is given, recorded on the run, then delivered to the sink, which may return an anchor. A sink failure fails the run; recovery re-delivers.
verifyJournal Check sealed entries: numbering, chain, hashes, and signatures when given a verifier.
seal, SealedEntry Hash a JournalEntry and sign the hash when there is a signer.
canonicalJson, digestOf JSON with keys sorted at every depth, and the digest over it, so equal values hash equally.
Payer, payingFetch, withPaymentKey AppOptions.payer: a 402 met by the app's fetch is paid under a key derived from the step's idempotency key, asking status(key, required) first so a retried step reuses a settled payment, presented the way that server asked for it. Local functions receive the app's fetch as opts.fetch. Types: PaymentRequired, Paid, PaymentStatus, PaymentRecord.
Sandbox AppOptions.sandbox: snapshot after each journalled step (named on the entry), restore of the latest before recoverRun drives a crashed run.
RunCipher AppOptions.runCipher: run files sealed at rest; plaintext files are refused rather than read.
StateCipher, isCipher The same two operations, for AppOptions.threads and AppOptions.memory: conversations, and what agents remember into files, sealed at rest.
Conversations, Threads, Folder Where conversations are kept: the interface a backend implements (load, append, list, forget), the app's own, and the one that keeps them as files. Types: Thread, ThreadSummary, Turn.
permissionClassifier An Authority that reads a policy written in prose against each call by asking a model: allow, deny, or ask a person. Refuses when it cannot decide. Types: ClassifierOptions, Classified, Decision.
Meter, MeterRefused, CallLimitReached, estimateOf AppOptions.meter: reserve(call) is asked before every model call and refuses with a sentence; settle(call, usage) is told what it took. MeterRefused is what a refused request ends in, CallLimitReached what one past maxCalls ends in. Types: MeteredCall, MeteredUsage, CallPurpose.
AskCaller Who a request is for: person, and anything else the app adds. Carried with context to the guard, the authority, functions and the meter, and to no model.
StepUp What AskOptions.approve is asked: the call the authority allows only with approval, and its digest.
outboundFault, privateAddress Whether an address a caller supplied is one this process should request: https, and not private or loopback unless its host is allowed (OutboundOptions).
postWithRetries The retrying POST webhooks are delivered with.
Source, SourceEvent, App.follow Durable triggers: one run per event, the cursor stored after each (CursorFile keeps it between runs of the process), a re-delivered event finding the run it already started (runIdFor).
CliPlugin plugins in the config: commands reached as praecise <plugin> <command>.
ChatResponse.evidence A wire may return proof of what it ran; it is collected on Answer.evidence and carried into the journal. A wire that requires it refuses a reply without it.

The harness — models, memory, and adapters

Name What it is
BuiltinHarness The harness that ships with the framework.
resolveHarness Pick a harness from config and credentials.
Harness The interface a harness satisfies. Implement it to replace ours.
ChatAdapter (request: ChatRequest) => Promise<ChatResponse> — one provider.
ProviderError What an adapter throws when a provider refuses or fails. Throwing this rather than a bare Error is what lets the ladder tell a retryable failure from a fatal one.
Episode, Jotting, Page, PageSummary, Note, Candidate, ProposedNote, Retirement, Accepted, Filed What an agent keeps and carries, as App hands it back: an exchange, a working note, a subject page, a carried fact or procedure, a proposal and its parts, and what accepting or filing came to.
Origin, authorityOf Where something kept came from (user, tool, agent, external), and the authority of something drawn from several sources: the lowest of them.
Ledger The record of routing decisions, and what they cost. Every row carries the propensity of the choice it records; without that the log answers "was this escalation worth it" and nothing else.
route, difficultyOf Where a request starts and how hard it looked. Difficulty counts the conversation, the choice of tools, and how much has to be read — not the length of the question.
riskOf How likely a request is to be got WRONG, which is a different axis from how hard it is. Question length lives here: it predicts failure after difficulty is controlled for, so it widens the margin at which an answer is checked instead of moving which model answers.
verifyMarginFor How much band-headroom is close enough to be worth checking: VERIFY_MARGIN at rest, widening with risk and stakes.
ladderFrom The depths to ask one rung for, in order, before crossing to another model. At most three, because that is how many an endpoint can tell apart.
attach Return something other than text from a function: attach(result, ...attachments).
registerReader, knownReaders Teach the framework to show a kind of data to a model, by media type, and list the readers registered. A Reader is handed the attachment and its text, and returns what the model should read. Later registrations are asked first.
embedderFor The Embedder for the first reachable endpoint in models that names an embeds model, or nothing. AppOptions.embedder takes your own.
rerankerFor The Reranker for the first reachable endpoint that names a reranks model, or nothing. AppOptions.reranker takes your own.
registerDecoder, knownDecoders, show Teach the framework to take apart media an endpoint cannot be sent (a Decoder answers a Decoded: stills and sound), list the decoders registered, and work out what a model is shown for a set of attachments (Showing).
ffmpegDecoder The decoder that ships, for video, over an ffmpeg binary the app names. Types: FfmpegOptions, FfmpegRun.
Uploads, registerUploader, knownUploaders, send, bearer The cache that uploads a large attachment once through an endpoint's files API, the registry of how each shape stores a file (Uploader), and the transport an uploader is written over. Types: Endpoint, UploadSetting, Uploaded, Uploading, UploadsOptions.
Batcher, Seat, registerBatch, knownBatches, requestOf, replyOf What hands many requests to an endpoint's batch API, the registry of how each shape takes a batch (BatchDriver), and the request and reply of one item. Types: Asking, Batch, Batched, BatchItem, BatchOptions, BatchResult.
LiveSession, registerSession, knownSessions, sessionFor, realtimeSession, liveSession A live session as App.open returns it, the registry of session protocols by name (SessionOpener), and the two that ship. connect, Events, frameText and socketBase are what an opener is written over. Types: Session, SessionEvent, SessionInput, SessionAudio, SessionRequest, SessionFaculties, OpenOptions, WireSession, Line, Socket, SocketConstructor.
amountOf, priceFor Arithmetic over the prices an endpoint declared: what some usage cost, and the price of one model. Types: Cost, Price.
composeHooks, SENT_BACK Several sets of hooks as one, and how many times beforeStop may send an agent back in one conversation.
computer, computerTool, browserScreen A screen as a function an agent calls, the tool underneath it, and the screen that ships: a browser. Types: Screen, BrowserScreen, BrowserScreenOptions, ComputerOptions, Button, ScreenPoint, ScreenRegion, NativeTool.
ToolTape AskOptions.tape: hears a request's tool calls, or answers them in place of the tools.
EXPLORATION The share of routing decisions worth randomising (2%) so the record can be read back. Set it as explore in praecise.config.ts; off unless you do.

Types: ChatRequest, ChatResponse, Message, ToolCall, ToolSchema, Answer, AskOptions, Progress, Usage, Routing, Episode, Attachment, Stop, Embedder, Delegate, Kind, Reader, UiView.

An Attachment may carry fileId (the name an endpoint gave bytes uploaded to it) and blob (where the bytes are kept in the app's blob store). Usage reports cost, by currency, where the endpoints that answered declared prices, and unpricedTokens where some did not. Answer is generic in its data, and carries ui (the UiViews tools brought with their results). A ModelProvider may also declare reranks, uploads, batch, realtime, computer and prices.

A Message of any role may carry attachments: what was sent with a question, or what a tool returned with its result. ChatResponse.attachments and Answer.attachments are what a model made that is not text. A model endpoint's takes says which of image, audio, video, document it can be sent. McpCallOptions.media is where an MCP tool result's images, audio and files are handed over.

Usage reports cacheWriteTokens and reasoningTokens where an endpoint reported them. ChatResponse.stop is why a reply ended in one vocabulary on every wire (end, tools, length, refusal, filter, paused, error); finishReason keeps the endpoint's own word. ChatResponse.replay and Message.replay carry what an endpoint wants handed back with tool results (its reasoning), opaque to everything but the wire that wrote it. ChatRequest gains levels, stable (how much of the start of system is the same on every request) and cache. ProviderError.retryAfter is how long the endpoint asked to be left alone, in milliseconds.

AskOptions, what App.ask(agent, input, options) and Harness.ask take:

Field What it does
task What the request is about when the input carries more than the question (grounding, retrieved passages). A self looks up its memory by it and records it as the work. Defaults to the input.
history Prior turns, oldest first, when the caller keeps its own.
thread The conversation this belongs to; naming one reads back what was said and adds what is said now.
signal Cancels the request.
onProgress Called with each Progress event as the work happens, which also lets the answer arrive in fragments where it can.
ceiling The most expensive rung (Quality) this request may reach. It trims the agent's declared ladder and never raises it, so the router still escalates below it. Where it would leave nothing, the cheapest declared rung is kept.
floor The cheapest rung this request may start on: for re-asking after a cheap answer was rejected, so that model is not asked again. It can only remove rungs the agent declared, never add one, and is clamped to the ceiling: a floor above the ceiling gets the ceiling, never an empty ladder. Where it would remove every remaining rung, the dearest one left is kept.
trace The trace this request is already part of, so its spans join it.
tainted Start the request already tainted: something untrusted was read before it began.
caller, surface, background Who the request is for (caller.person), where it comes from, and whether nobody is waiting on it. Read by selves. caller is an AskCaller and may carry anything else the app wants its guard, authority, functions and meter to see.
context Whatever else the app sends with the request. Never read by the framework, shown to a model, or written to a trace or a recording; handed on with caller.
allow { tools?, knows? }: narrow what the agent may call and what stays in its instructions, for this request. It only takes away, and a name the agent does not have is an error.
maxCalls The most model calls the request may make, counting every one. Reaching it ends the request with CallLimitReached. Defaults to limits.calls.
steer Called before each step the agent takes; what it returns is put to the agent as further turns of the caller's.
tools LocalTools that exist for this request only, beside the agent's own.
approve Asked when the authority says a call needs a person's approval; answers with a VerifiedApproval or the sentence the model should read.
tape A ToolTape that hears, or answers, this request's tool calls.
attachments Images and documents sent with the question: { mime, data? , url?, name? }. They belong to this request and are not kept with a named conversation.
depth How many agents deep the request already is. Set by the runtime when one agent asks another.

Provider wires. An endpoint's speaks names a request shape, and each shape is a ChatAdapter:

Name What it is
chatWire, messagesWire, contentsWire, responsesWire, interactionsWire The shapes that ship.
adapterFor The adapter registered for a shape.
registerWire, knownWires Teach the framework a new shape (replacing a built-in is refused), and list what is registered.

A chat endpoint that ignores stream: true and answers with one buffered JSON completion is read as such: the stream is parsed only when the response is text/event-stream, and a streaming caller then receives the whole text at once.

Clocks on every wire. A streamed answer is watched between frames — the clock starts again at every frame, so a long answer arriving steadily is never cut off (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, so the ladder crosses to the next model rather than asking the silent endpoint again, and a caller's own signal still cancels. On the chat wire a stream that stops after some text has arrived keeps that text, with finishReason: "timeout" and the reason in notes.

Selves

Name What it is
self on agent() The self an agent is: a handle, or { handle, surface?, template?, record? }; {person} in a handle makes a self per person. record decides what the self is sent after an answer.
selves in defineConfig Where selves live: url, credential, adminCredential, ticketCredential, surface, required, timeoutMs.
selvesOverHttp The provider for the HTTP self protocol.
SelfProvider The interface a provider satisfies: context, record, outcome. Pass one as selves in AppOptions.
signTicket, openTicket Bind a ticket to a person, and check that binding.
App.rate A verdict on an answer a self gave, with the ticket the answer carried, and optionally a mechanical check.

Types: SelfDeclaration, SelfTemplate, SelfContext, SelfVerdict, SelfCheck, AnswerSelf, HttpSelvesOptions, RecordSelf, SelfWork, SelfRecording. AskOptions gains caller, surface and background; Answer gains self; Progress gains self.

PROTOCOL_VERSION is the MCP protocol revision this framework speaks.

Services: MCP, OpenAPI and code mode

Name What it is
McpClient, mcpRequest, mcpHeaders A client for an MCP server, and the builders for a conforming request.
collectResources Read the resources an agent's services were told to attach, rendered as knowledge.
Unauthorized Thrown when a server will not answer without a token; it carries the challenge the OAuth flow starts from.
ApiClient An OpenAPI-described HTTP API presented with the same shape as an MCP client.
ToolSource What the harness needs from a service, whichever protocol it speaks.
operationsFrom, toolsFrom, requestFor, callOperation Read a document into operations, turn them into tool schemas, build the request for one (to inspect or approve before it leaves), and call it.
operationName, baseUrlOf, resolveRefs A stable tool name for an operation, a document's base URL (OpenAPI 3 and Swagger 2), and local $ref resolution. Remote refs are not fetched.
McpHost, Elicit, clientCapabilities AppOptions.mcp: elicit.form and elicit.url answer a server that asks a person for something mid-call, and apps says a front end renders the views tools bring. clientCapabilities is what is declared to a server as a result. Types: FormElicitation, UrlElicitation, ElicitResult, ElicitedValue.
InputRequired, elicitedFault What a call ends in when a server asks for input nothing can give, and what is wrong with an answer to a form.
McpSubscription, McpSubscriptionFilter, McpNotification A subscriptions/listen stream: what watch: true on a service holds open, and how a task's changes arrive.
collectSkills, serviceSkillTool, READ_SERVICE_SKILL The skills a service serves (skills on a service), and the read_service_skill tool an agent reads them with. Types: McpSkill, McpSkillFile, OfferedSkill.
uiOf, UI_MIME, McpToolUi, McpToolResult The interactive view a tool declares, the media type of its page (text/html;profile=mcp-app), and a tool result as a service returned it.
SKILLS_EXTENSION, UI_EXTENSION, CLIENT_CREDENTIALS_EXTENSION, ENTERPRISE_AUTH_EXTENSION The names of the MCP extensions spoken.

Types: McpResource, McpResourceContents, McpPrompt, McpPromptResult, McpProgress, McpRequestOptions, McpCallOptions, McpCompletion, Operation, Where, CollectOptions.

Code mode

code: true (or a CodeModeSpec) on an agent replaces its per-operation tools with one code tool. The agent's HTTP services are described to the model as a typed API — an MCP server as tools.<service>.<tool>(args), an OpenAPI service as tools.<service>.request({ method, path, query, body }) with its document in spec.<service> — and the program runs in a Praecise Silo with the services bound in and their credentials kept outside it. A service launched as a local program stays an ordinary tool.

Name What it is
CODE_TOOL The name of that tool: "code".
SiloExecutor The code tool's runner: one silo per agent, created on first use, kept for its ttl, created again once it expires.
bindingsFor Which services can be bound into a silo, and how (Binding).
typesFor, tsType The declarations the model reads, one namespace per bound service, and a TypeScript type for a JSON Schema.
codeTool The code tool's schema, with those declarations in its description.

allow narrows what a program may call, per service: tool names for an MCP server, "METHOD /path" patterns (with *) for an OpenAPI service. A service not named may be called for anything it offers. The silo enforces the rules and logs every call. The silo is addressed by silo, else PRAECISE_SILO, else its local socket; an https:// address is reached with the token in PRAECISE_SILO_TOKEN.

Storage, and extending it

Using a store:

Name What it does
Stores Every store the app declared, opened on demand.
openStore Open one store from a URL.
Kept A store's write side, as handed to app code.

Writing a new backend:

Name What it does
memoryDriver The in-process driver. Useful as the reference implementation.
sqliteDriver The SQLite driver. Loads node:sqlite lazily, on first use.
postgresDriver The Postgres driver.
redisDriver, Resp, RespError, respOptionsFrom The Redis and Valkey driver (redis://, rediss://, valkey://, valkeys://), and the RESP client it is written over, reusable by a driver that speaks it. Types: RespOptions, RespReply.
fuse Several orders of the same rows made one by reciprocal rank, which is how recall joins what the words found to what the vector found.
SchemaError What remember throws when a store with a schema is given a record outside it; issues (SchemaIssue) name each row, path and message.
diskBlobs, memoryBlobs, detach, inline, sweepBlobs, addressOf, isBlobAddress, blobsIn Blobs: a BlobStore on disk or in memory, an attachment's bytes moved into one and put back, the sweep that removes what nothing names (SweepOptions, Swept), the address of some bytes (sha256: and the digest), the test for one, and every address a value mentions. Types: BlobStore, BlobInfo.
Values, Facts, Series What store.values, store.facts and store.series are: a value under a name with an optional lifetime, and claim, which keeps one only if the name is free (Connection.add, the one verb a driver must decide in a single step); how two things are related and when that was true, with a walk of up to three steps; and readings in order of time, with windows and aggregates. Each is written over a Connection's existing operations, so every backend has all three.
conform Run the conformance suite against a driver you wrote.
conformanceReport The same, rendered for a human.
Wire The Postgres wire framing, reusable by a driver that speaks it.
wireOptionsFrom Turn a connection URL into wire options, including sslmode (disable, prefer, require, verify-full) and max_protocol_version (3.0, 3.2, latest).

Types: Driver, Store, Connection, ConnectOptions, Capabilities, Item, Keep, Found, Query, Window, Ranked, ResultSet, Promised, Conformance, StoresOptions, WireOptions, WireResult, Held, Asked, RecallQuery, Reranker, Meta, Extras, Faster, Walk, WalkStep, Bucket, Buckets, Entry, Namespace, Fact, FactOptions, FactQuery, Neighbour, Point, RangeOptions, Aggregate.

Store.recall takes text, a vector, or both (Asked), and RecallQuery.rerank set false leaves the store's reranker out of one question. Capabilities.faster lists what a backend does itself instead of leaving it to this process: walk, buckets, ids, validity.

A driver only has to implement the capabilities it actually has; conform checks what it claims, not a fixed list.

Which family a store actually gets

of declares one of five families. What ships serves four — sql, document, timeseries and vector — over one table of text, json, a time and an optional vector. graph is not served by anything here and is refused when the store is opened, naming what is served. That refusal is the honest half of a declaration that used to be accepted and then quietly ignored.

Capabilities carries three fields for reading the choice back:

Name What it says
serves The families this backend will answer for. Absent means the driver makes no claim, and a driver that makes none is held to none — a backend written before this existed is not refused for having no opinion.
vectorSearch "index" where the database orders by distance, "scan" where every vector is read and compared in this process. vectors still means can it hold them; this is what asking costs.
detail What was settled at connect, phrased as the thing to do about it.

ConnectOptions carries two more: of, so a driver can shape itself to what it is holding, and extension, a native extension path an operator named. The SQLite driver reads the second from PRAECISE_SQLITE_EXTENSION and loads nothing without it.

Extensions, and what each costs

Extension To install What it buys
pgvector CREATE EXTENSION vector — one statement, no restart A real vector(n) column, an HNSW index, and <=> doing the ordering. Needs dimensions.
TimescaleDB shared_preload_libraries plus a restart A timeseries store becomes a hypertable in weekly chunks. Only create_hypertable is used — the Apache-2.0 subset. Compression, continuous aggregates, retention and the job scheduler are source-available and are not touched.
sqlite-vec A build on disk, named in PRAECISE_SQLITE_EXTENSION vec0 answers nearest-vector queries over an unnarrowed window. Never loaded unless asked for.
Apache AGE CREATE EXTENSION age, plus LOAD 'age' and a search_path per session Nothing here uses it. Reachable through query().

Whatever is installed is reachable through Store.query() regardless — the author's door, not the agent's. An existing table is never migrated underneath an adopter: a bytea vector column keeps the in-process comparison and says so in detail.

Dialect and latent transport

Two halves of one idea: the framework ships the mechanism, and each app declares its own vocabulary on top. A vocabulary is a property of your domain, so hard-coding one here would make every app speak the same language whether or not it meant the same things.

The codec. A versioned, field-typed wire format built from a table of message specs.

Name What it is
defineDialect Build a dialect from a version string and a table of message specs.
str, num, bool, list, fixed2 Field codecs. fixed2 fixes a number to two decimal places, so a value round-trips identically.
Dialect, MessageSpec, Field, FieldCodec The types involved.

The transport. An intermediate representation passed between steps without being rendered back to text.

Name What it is
latent Wrap a vector as a payload, with its source and dimensions.
isLatent Type guard for one.
latentRef Name a payload without carrying it.
createRefs A ref table, so a payload travels once and is referred to after.
latentChannel Move payloads between steps.
probe Read a named scalar off a payload.
LatentPayload, LatentRef, LatentChannel, Refs, Probe The types involved.

probe is not optional decoration. An opaque vector nobody can measure is not something to put in a pipeline; probes are what keep latent traffic auditable after the fact.

Observability

There is no telemetry dependency and no exporter. The framework produces the standard shape and the app wires the sink.

AppOptions.tracer takes (span: Span) => void and is the one to use. Span is an OpenTelemetry span: traceId, spanId, parentSpanId, startTime, endTime, status, and attributes in the GenAI semantic convention (gen_ai.operation.name, gen_ai.provider.name, gen_ai.request.model, gen_ai.usage.input_tokens, gen_ai.usage.output_tokens, error.type). Model calls and tool calls are instrumented, a call that threw still produces a span, and trace context crosses into MCP as traceparent so a tool server's work joins the same trace.

AppOptions.emit and WorkflowDeps.emit take (span: GenAiSpan) => void and predate the above. GenAiSpan is a flat event — operation, name, step, durationMs, at — describing what a WORKFLOW did (plan, invoke_agent, invoke_workflow, execute_tool). It carries no trace ids, so nothing emitted through it can be joined to anything else.

Both are live and they are bridged: when a tracer is wired, workflow events reach it as conformant spans keyed on the run, so a workflow and the model calls its steps made appear as one trace rather than two unrelated records of the same work. Prefer tracer in new code; emit remains for anything already using it.

  • Tracer is the type of AppOptions.tracer, and GenAiOperation the operations a span can name (chat, execute_tool, embeddings). traced(...) times one call and hands the span over, including when the call throws.
  • TraceContext is where in a trace a call sits; traceparentOf and parseTraceparent write and read a W3C traceparent header, traceMeta gives the _meta keys MCP reserves for it, and newTraceId/newSpanId mint ids.
  • TraceLog is a bounded in-memory collector — what praecise dev installs to render /traces. laneOf(span, trace) places a span in its trace's timeline; Trace is one trace assembled from its spans.
  • COST_ATTRIBUTE and COST_CURRENCY_ATTRIBUTE are the span attributes a priced call carries: praecise.usage.cost and praecise.usage.cost.currency.
  • Ledger records routing decisions and spend.
  • provenanceOf(run) answers what a run derived from what.
  • followRun(runs, id, signal) streams RunEvents live.
  • forkRun(id, spec, deps, { after, patch, by }) branches a run from a past step, optionally editing an earlier output. The original is untouched and every patch is recorded as a patched event naming who made it.

Protocols

Everything an app publishes is reachable four ways, from one declaration.

  • MCP 2026-07-28 — handleMcp(app, message, caller) serves it and toolsOf(app, caller) lists the tools that caller may see; McpClient consumes it. Stateless: every request carries its own version, capabilities and identity in _meta. mcpRequest(method, params) and mcpHeaders(...) build a conforming request, which is worth using rather than assembling by hand.
  • A2A 1.0 — agentCard(app, caller, baseUrl) and handleA2A(app, message, caller, tasks). TaskStore holds what SendMessage created so GetTask can find it. streamsA2A(message) says whether a request is one of the two that answer as a stream (SendStreamingMessage, SubscribeToTask), and streamA2A(...) yields its events. A2A_VERSION is the revision spoken ("1.0", the form the header and the card use) and AGENT_CARD_PATH where the card is served. A caller that sends A2A-Version: 0.3, or uses a 0.3 method name, is answered in the 0.3 shapes. restA2A(...) serves the HTTP+JSON binding under the same address (A2ARestRequest, A2ARestAnswer), and tasksOf is the task store an app's A2A endpoint uses, made on first use. A2AOptions.push (ServeOptions.a2a) says which hosts a push notification may be sent to (PushConfig). Types: Task, TaskState, TaskStatus, A2AMessage, Part, A2AVersion, TaskEvent.
  • Signed agent cards — signAgentCard, cardSignerFor, cardPayload and jcs sign a card over its canonical JSON form; verifyAgentCard(card, jwks) checks one and fetchAgentCard(address, { keys, trust, unsigned }) fetches a peer's and says whether it verified. Types: AgentCardSignature, CardSigner, CardVerification, FetchAgentCardOptions, FetchedAgentCard.
  • MCP Tasks — the server answers a workflow call from a client that declares io.modelcontextprotocol/tasks with a task, serves tasks/get and tasks/cancel (which stops the run), and sends notifications/tasks to a client that names the task in subscriptions/listen; McpClient.call follows a task it is handed to its end. McpStream is what a streamed MCP answer is.
  • Skills over MCP — listSkills, getSkill, readSkillDirectory, readSkillFile and renderSkillFile serve the app's authored skills (skills/list, skills/get, skill:// resources). Type: ServedSkill.
  • MCP Apps — ui on a function, agent or workflow names a ui:// resource to show beside its result; handleView(...) answers what a view asks of the service that brought it, which is what POST /api/ui/<service> serves. MCP_APPS_ACTIVITY is the AG-UI activity type a view is sent as.
  • A2UI 1.0 — surfaceTool (SURFACE_TOOL, show_surface) is the tool an agent sends a surface with; validateA2ui and validateA2uiEvents check an envelope and a renderer's events (A2uiFault); rendererCatalogs reads the catalogs a turn's renderer named; a2uiTurn reads what a turn carried from a renderer and eventsText puts its events into words for the agent. A2UI_VERSION, A2UI_MEDIA_TYPE, A2UI_EXTENSION_URI and A2UI_ACTIVITY are the constants. Types: A2uiMessage, A2uiComponent, A2uiEvent, A2uiFunctionCall, A2uiFunctionResponse.
  • Agent Client Protocol — serveAcp({ app, agent }) serves one agent over stdio for an editor; ACP_PROTOCOL_VERSION is the version spoken. Types: AcpOptions, AcpServer.
  • Responses API — handleResponses(...) answers POST /v1/responses (RESPONSES_PATH), where model names an agent, and responsesFrame writes one stream event. Types: ResponsesOptions, ResponsesAnswer, ResponsesError, ResponseResource, ResponseItem, ResponseEvent.
  • AsyncAPI — asyncApi(app, caller, baseUrl) describes the events the app receives and sends, served at ASYNCAPI_PATH (ASYNCAPI_VERSION).
  • Catalogue listings — listingOf works out what a published capability says about itself (Listing) from an agent's meta, and META_KEY is the _meta key it is carried under on an MCP tool.
  • Discovery — mcpServerCard(...) at MCP_SERVER_CARD_PATH and aiCatalog(...) at AI_CATALOG_PATH (AI_CATALOG_VERSION marks the catalog's shape as provisional: the standard it follows is a draft).
  • Web Bot Auth — signingFetch(fetch, signer) signs every request per RFC 9421 with the web-bot-auth tag (WEB_BOT_AUTH_TAG); keyDirectory(keys) is the body served at KEY_DIRECTORY_PATH (KEY_DIRECTORY_TYPE); verifySignature(request, jwks) checks one; thumbprint(jwk) and signatureBase(...) are the pieces. AppOptions.botAuth applies it to the app's outbound requests. Types: BotSigner, Ed25519PublicJwk, SignatureParams, SignedRequest, Verification.
  • Run notifications and webhooks — AppOptions.notify (Notify) is told what runs do as CloudEvents (RUN_EVENT_TYPES, runEvent, RunNotice, RunEventType, RunTransition). signWebhook, verifyWebhook and deliverWebhook implement Standard Webhooks (WebhookTarget, WebhookDelivery, DeliverWebhookOptions).
  • AG-UI interrupts — interruptOf, answerInterrupts, followWork, AguiInterrupt, AguiResume: a workflow stream that stops at a gate ends with an interrupt outcome and is resumed through the existing approval path.
  • AG-UI — AguiStream translates praecise's Progress events into AG-UI's, keeping message boundaries. modesFrom(...) reads a ?stream= selector, modeOf(event) says which StreamMode an event belongs to, ALL_MODES lists them, and sseFrame(event) writes one AguiEvent (of an AguiType) as an SSE frame.
  • OAuth 2.1 — OAuthClient for servers that are protected resources, plus parseChallenge, canonicalResource, metadataUrls, stepUpScopes, challengeFor (the S256 PKCE challenge), randomString, and expiryOf/expired for deciding when to refresh. OAuthOptions.clientMetadataUrl names a Client ID Metadata Document to use as the client id where the authorization server supports one, and clientMetadataDocument(...) builds that document. authorizerFor turns a MachineGrant (client credentials, or an identity assertion exchanged at an identity provider) into a function that finds a token, and clientAssertion signs the assertion a key-holding client presents. Types: OAuthOptions, Challenge, Tokens, ClientRegistration, MachineGrant, PendingAuthorization, DiscoveryResult, ProtectedResourceMetadata, AuthorizationServerMetadata, ClientMetadataDocument.

llmsTxt(app, caller, baseUrl) (served at LLMS_TXT_PATH), jsonLd(...), jsonLdScript(...) (the same, ready for a page's <head>) and robotsTxt(...) are the discovery documents; ask(app, request, caller, policy) answers a natural-language question from the app's own store, and compact(results, budget) is the layer between a database and a prompt — supersede, deduplicate, fit, and reorder for where a model actually reads. Around them: fromStore reads store rows as schema.org objects, rank and termsOf rank what the app publishes against a question, edgeFirst puts the best matches where a model reads, and qualityFor and modeFor cap what was asked for at what the AskPolicy allows. Types: AskAnswer, AskMode, AskPolicy, AskResult, Compacted.


Ingestion

ingestInto(dir, store, options) reads a folder of documents into a store. chunk(text, size, overlap) splits at the document's own paragraph boundaries, chunkId(source, text) derives a stable id so re-running does not duplicate, and readFields(said, fields) reads a model's extraction or refuses it, from the prompt extractionPrompt(text, fields) builds. ingestible(dir) lists the files the pipeline can read. canConvert, isTextFormat and ingestFile (with Converted and Converter) are the conversion layer underneath. Types: IngestPipelineOptions, IngestReport.


Structured results

A declared returns is fields and hints, a JSON Schema, or a Standard Schema validator.

  • returnsKind(returns) says which (ReturnsKind); isJsonSchema and isStandardSchema are the tests.
  • validateJson(schema, value) checks a value against a JSON Schema and answers with what is wrong. CHECKED_KEYWORDS are the keywords it checks, UNCHECKED_KEYWORDS the ones it does not, and uncheckedIn(schema) the unchecked ones a schema uses.
  • ShapeError is what a request ends in when the strongest model's answer is still outside the shape; it carries issues and the text.
  • Types: StandardSchemaV1, StandardResult, StandardIssue, StandardOutput, DataOf.

@praecise/harness/formats

Readers for robotics, scene and array data, as a plugin. Public, and covered by the same promise as the root.

Name What it is
formats The plugin: plugins: [formats()]. formats({ only }) and formats({ except }) choose among the formats (FormatsOptions).
registerFormats Register the same readers without a plugin.
describeAttachment The rendering of one attachment, or nothing where no format here reads it.
formatNames, FormatName The names only and except take.
mcap, rosbag, rosbag2, lerobot, parquet, arrow, pcd, ply, splat, splatPly, usd, npy Each format on its own (Format).

@praecise/harness/testing

A model that says what a test tells it to. Public, and covered by the same promise as the root.

Name What it is
scriptedModel A model endpoint that answers from a list of replies. models goes in the config, requests is every request the app made, push adds replies, and remaining counts what is left. Types: ScriptedModel, ScriptedModelOptions, Scripted, ScriptedReply, ScriptedCall, ScriptedRequest.
scriptedEndpoint The same one level down: a fetch that answers with the bodies it is given. Types: ScriptedEndpoint, EndpointReply.
systemText The instructions of a request, as text.

@praecise/harness/internal

Unstable. Unversioned. May change or vanish in any release, patch releases included. Documented here only so you know what it holds and why you should not reach for it:

  • Loading — loadProject, resolveKnows, findCycle, Importer, LoadOptions
  • Ingest — converterFor, ConvertRequest, IngestOptions, ConverterOptions
  • Compiling — planProject, planAgent, planWorkflowAgent, schemaFor, PlanOptions
  • Harness internals — stateDirFor, stream, trim
  • Store internals — urlFor, asObjects
  • Workflow internals — checkSteps, provisioner, runCommand, splitCommand, Manifest, ProvisionerDeps
  • Server internals — callPublished, promptsOf, resourcesOf, groupsOf, noticesOf, openChannel, Caller, McpTool, Channel
  • Packaging — buildPackage, manifestFor, apiModule, apiTypes, faultsIn, hintsIn, PackageManifest, PackageOptions, PackageResult, Describable
  • CLI — cli. The supported way to run this is the praecise binary.

adapterFor, chatWire, contentsWire, messagesWire, handleMcp, toolsOf, canConvert, ingestFile, Converted and Converter are also reachable here, and are public: they are exported from the root and documented above.

Edit this page on GitHub · Read it as Markdown

    Type to search. Arrow keys move, Enter opens.