@mcsherrylabs/pi-evolver

A Pi agent extension: chain-generic tools over an Evolver node. Read the chain, sign a transfer, administer what you own, write to a channel, submit a signed transaction.

It wraps @mcsherrylabs/evolver-client and implements no wire format or signing encoding of its own. It knows about no particular channel, ledger or service — a tool that names a channel belongs in that channel's own repository.

Specs: 161-pi-evolver-tools, 162-agent-write-coverage, 164-sign-channel-write.

Running the checks

Every check runs with one command (Constitution Quality Gate 10), from this directory:

⚠️ These now run in CI. ci/npm-test.sh is the last step of the test job and the root npm test includes this package, so a red pipeline is this package's problem. (That is a change from what this file said while issue #77 was open; a stale "CI does not run this" is how a gate stops being read.)

⚠️ npm test builds @mcsherrylabs/evolver-client first on purpose. The checks import it by package name, which resolves to its built output — without the build they would pass against stale bytes.

⚠️ The ownership report is a tripwire, not decoration

evolver_status reports what the configured identity owns. It should say none.

⚠️ AND THE AGENT CAN NOW END THAT ITSELF. Before 162 the only way this identity came to administer anything was somebody else adding it to a group. It can now create groups, admit members and hand groups over — so "owns nothing" stops being true by the agent's own action, and the no-confirmation decision that rests on it (161 FR-012a) has to be re-made rather than re-weighed when it does.

Nothing enforces that. Ownership is reported, never a precondition for signing: the chain is the authority — a non-owner's membership change is FINED and a transfer spends only the sender's balance — and a gate here would add nothing while coupling every signature to a paged walk of every channel owner on the chain. The status tool is the tripwire, and a human reading it is what notices. It is re-asked after any submission that can change the answer, so it will not keep reporting a state the agent has already left.

This package spends without asking for confirmation, and that decision is sound because the consequence of a mistake — or of an instruction injected through chain content the agent reads — is bounded by this identity's own balance. That bound holds only while the identity owns nothing.

"Owns nothing" is a state a stranger can end. A group owner may add any identity to their group without that identity's consent or knowledge, and membership of a group that owns a channel confers administration of it — changing its toll, its write policy, its availability policy, or releasing it. The likeliest route is not an attack but a favour: adding the agent to the group is the only way to let it write to that group's channel.

So if owns ever reports anything but none, the premise behind spending-without-confirmation has expired and that decision has to be made again rather than weighed again. Signing refuses outright if ownership cannot be determined at all — an authority question with no answer is not a yes.

Signing in to an off-chain service: evolver_signed_request

The transaction verbs sign for the chain; this one proves who we are to anything that verifies evolver 157 login proofs. The model fetches a challenge itself and passes it with the service's audience and the request to send, marking where the answer goes in the body or a header with {answer} or {answer.<field>}, so any request shape works. The SDK's signedRequest shows the human that request as it will be sent, escaped, with the host repeated last and warnings for plain http or an audience that does not name the host. The choice defaults to No. Only on yes does it sign, with target.signer, send the request itself (following no redirects), and return the response.

⚠️ The tool sends because a returned answer could be relayed. Anyone holding a 157 answer can redeem it at its audience, so a tool that handed one to the model would let text the model read route a genuine-looking login to whoever asked for it. The answer leaves the process only inside the one request the human approved, to the origin they saw. So nothing rendered comes back: the answer may not be placed in the URL (URLs are echoed in errors, Location and logs), a failure after signing reports the template and a fixed error class, and the signature is scrubbed from any Location or response body that echoes it.

⚠️ What is accepted, and recorded (openstar/evolver-meerkat#1):

• The response goes to the model, and for a login it may be a session credential. A service that mints a token on sign-in hands it back, and the model then holds it. The prompt says so. A service that re-proves every call returns nothing redeemable.
• The audience is the model's to choose, and it decides where a proof is valid. It is bound to the destination only by the human reading the prompt and a label-aligned audience/host warning. Binding audience to origin in configuration would close relay whatever the human does; it is the follow-up.
• Plain http is warned, not refused, because the first relying party is served over http. An on-path party can read the answer and use it first.
• It signs AND sends, against 161 FR-006 ("signing must not submit"). Returning the answer instead is the relay. check:surface 5c records the exemption by name.
• The body is not signed, which is why the prompt shows it in full.

⚠️ In RPC mode the RPC client is the human. pi reports a UI there, and every yes/no is answered by whatever drives the RPC connection, which may be a program. Driving an agent over RPC makes that program responsible for every approval.

Configuration

.pi/agent/evolver.json in a project, or ~/.pi/agent/evolver.json globally.

⚠️ A project-level file may override the chain URL and nothing else. The identity, the key and how the endpoint is trusted come from the home-level file or the environment only — otherwise a repository you open could name a different signing key, and the only gate is a prompt about trusting a project.

What this package will not do

• Name a channel, ledger or service in any tool.
• Claim an identity. It is given one.
• Accept a transaction body, ledger, kind or sender in a signing tool — a signing tool composes what it signs from named fields and pins the ledger itself. ⚠️ With exactly one exception, granted by name and paid for: evolver_sign_channel_write takes both, because a channel write HAS no named fields — the body IS the payload and the ledger IS the channel. What it buys the exemption with is a refusal: it will not sign for any ledger the node would INTERPRET (the six core ledgers and the whole reserved ce.evolver. namespace), because writing "opaque bytes" to the identity ledger is signing whatever that ledger'''s handler reads — a transfer, or a key registration.

Identity key lookup requires evolver-node v0.24.1 or later. The SDK getIdentityKeys(name) and pi evolver_keys read one principal directly; an absent principal is distinct from an empty key set, an unsupported route, or a failed read. Chain-wide explorer scans are no longer used for this lookup.