Module client_tools 

Client-performed tool declarations: what the operator says about a tool the CLIENT runs in its own process, and the registry a host loads them into.

Declared by the operator, implemented by the client

A ClientToolDecl is a tool with no code behind it on this server. The operator declares its name, its Effect, the shape of its input, the shape of its completion, and whether the client’s word is good enough to close the call. The client is the one that actually performs the work, in its own process, with its own secrets. That is the whole point: a tool whose credential must never reach salvor can still be recorded in a salvor run.

Why declarations are never registered over HTTP

They are loaded by salvor serve --client-tool <FILE> and by an embedding host through AppState::with_client_tools, and there is deliberately no endpoint that accepts one.

The reason is the effect class. The server-performed tool_step already refuses to take the effect from the request body, so a caller cannot up- or down-grade a Write into a freely retried Read. A declaration carries an effect too. If a client could POST its own declaration it would be choosing its own effect class by the back door: declare the charge as a Read, and the write-ahead rule that makes an unsettled write surface for a human stops applying to it. Keeping declarations operator-side keeps the effect an operator’s word in both surfaces, which is the invariant, not an implementation detail.

The format

One TOML file per declaration, mirroring how --agent takes one agent file:

name = "charge_card"
effect = "write"
trust_completion = false

[input_schema]
type = "object"
required = ["amount_cents"]

[input_schema.properties.amount_cents]
type = "integer"

[output_schema]
type = "object"
required = ["charge_id"]

[output_schema.properties.charge_id]
type = "string"

The struct carries the Deserialize derive, so it defines the format; the CLI reads the bytes off disk and hands them to toml, exactly as it owns file reading for agent definitions. Nothing here touches the filesystem.

Structs

ClientToolDecl

One operator-written declaration of a tool the CLIENT performs.

ClientToolRegistry

The client-performed tool declarations a server was started with.

Functions

list

GET /v1/client-tools: every client-performed tool declaration this server was started with.