Praecise Harness v1.1.0 Get started

Documentation · Trust

Deciding what leaves the building

Anything published can say who may reach it and what calling it does:

ts
export default agent({
  role: "Review the ledger and flag anything unusual.",
  description: "Audits transactions for a named account.",
  access: "gated",   // open (default) · gated · internal
  effect: "read",    // read · write (default) · destructive
});

internal is the useful one. The agent still exists and your other agents still use it, it simply never leaves — it is absent from the published list and cannot be called even by a caller who knows the name, because refusing is not the same as admitting it is there.

This is worth doing for a reason beyond privacy. A caller shown twenty tools starts acting where it should have declined, so the smallest honest surface is also the most accurate one. effect feeds the same judgement: it tells a caller what a call would cost before it makes it, and an undeclared tool is assumed to change something.

Both mcp and package will narrow further on request, and packaging says so when the surface has grown past what a caller can weigh:

sh
praecise mcp --groups workflows       # one part of the app, not all of it
praecise package ./dist --read-only   # only what changes nothing

The same two narrow the dev server: POST /mcp?groups=workflows&read.

An agent can also say what a catalogue should show about it:

ts
export default agent({
  role: "Review the ledger and flag anything unusual.",
  description: "Audits transactions for a named account.",
  meta: { version: "2.1.0", tags: ["finance", "ledger"], languages: ["en", "pt-BR"], examples: ["Review account 4021 for March."] },
});

meta is read by every surface that lists the agent: its skill on the A2A agent card (where tags replace the group it is published in, and inputModes and outputModes are stated), its MCP tool's _meta["com.praecise/meta"], llms.txt and the JSON-LD. It is never shown to a model.

Nothing published can be undescribed. praecise package refuses an app whose tools say only their own name back, because a caller reads the description and nothing else before deciding — describe it, or mark it internal if it was never meant to leave.

Deciding call by call

access and effect settle what an agent may reach for. What it may do with a particular call is a different question, and a guard.ts at the root answers it:

ts
import { guard } from "@praecise/harness";

export default guard(({ tool, args }) => {
  if (tool === "refund" && Number(args.amount) > 500) {
    return "A refund over 500 needs a person to approve it.";
  }
});

Say nothing and the call goes ahead. Say a sentence and it does not — and the sentence goes back to the model as that tool's own result.

That last part is the point. A model told a refund needs approval can say so to the customer and offer to raise it; a model handed an exception can only stop, and the run ends somewhere nobody chose. So write the reason for the model to read, because it will read it. A guard that throws is treated as a refusal too, for the same reason: the app was asked and did not manage to say yes.

A refusal is not counted against the model that asked for it. It says nothing about whether that model was good enough — a stronger one would have been refused in the same place.

After a tool, and before stopping

A guard speaks before a call. hooks.ts at the root speaks at the moments after:

ts
import { hooks } from "@praecise/harness";

export default hooks({
  afterTool: ({ tool, result }) => (tool === "lookup" ? { result: withoutCardNumbers(result) } : undefined),
  beforeStop: ({ transcript }) => (ranTheTests(transcript) ? undefined : "Run the tests before answering."),
  beforeCompact: () => ({ keep: true }),
});

Each answers as a guard does: say nothing and what was going to happen happens. afterTool sees every result before the model does, and may replace it ({ result }) or withhold it with a sentence the model reads instead ({ reject }). beforeStop is asked when an agent answers instead of calling a tool; a sentence back sends it to work again with that as the reason, three times in one conversation and no more. beforeCompact is asked before earlier work is replaced by a summary: { keep: true } forbids the summary and { summary } supplies one. beforeRecord decides what a self is sent.

Edit this page on GitHub · Read it as Markdown

    Type to search. Arrow keys move, Enter opens.