harness-multitool

Invariants

What must hold at all times. Each invariant names how it is checked; an invariant without a check is a wish. A change to an invariant needs a decision record.

IdInvariantChecked by
INV-1The core touches no platform directly. The core crate and the interface crates use no std::fs, std::process, std::net, OS threads or async runtime I/O; every file, process, network, clock, storage and terminal access goes through a Platform interface.CI builds the core for wasm32-unknown-unknown; a lint denies the listed paths in core crates.
INV-2The loop holds no concrete implementation. Every component the loop uses is resolved from the registry by interface and the name given in the configuration.Test: a configuration that names a test double for every interface runs the loop with no default plugin linked.
INV-3A tool runs only within what it declared and was allowed. Before a tool executes, Policy has approved every capability it declares (paths read or written, commands, hosts); a use outside the declaration fails the call.Tests per built-in tool; a capability-escape test suite run against every tool plugin.
INV-4Done means proven. A task reaches done only when Verifier reports pass: its verification protocol ran in this session and the evidence is recorded. A model's claim alone never completes a task.Loop tests: a task whose verifier fails or did not run cannot reach done.
INV-5The session log is append-only. Every model turn, tool call, tool result, approval and state change is an event appended to the session log; nothing in it is rewritten. Session state is a fold over the events.Property test: replaying the log reproduces the state; rewind to event N equals the fold of the first N events.
INV-6Secrets never leave the auth boundary. API keys, tokens and credentials are never written to the session log, memory, telemetry, error messages or plugin events; they appear only inside Auth and the outgoing request.Redaction tests on every sink; a canary-secret test fails if the canary appears in any output.
INV-7Plugins meet only through interfaces and events. A plugin cannot read or change another plugin's state except through that plugin's interface or the event bus.Architecture test: plugin crates depend only on interface crates, never on each other.
INV-8Interfaces are versioned. Every interface crate follows semver; a breaking change is a major version, with a migration note.CI: semver check on interface crates.
INV-9A subscription login ships only where its vendor documents it for other apps. The project contains no Auth implementation that signs in with a vendor's consumer subscription, except on that ground (ADR 0019).Review rule; listed in the release checklist.
INV-10In the browser, keys go only to the provider. The WebAssembly build sends a user's key to the provider endpoint the user chose and to no other host, including the project's own.Test: the browser build's network layer refuses any host other than the configured provider for authenticated requests.
INV-11Specifications bind. Code that contradicts a specification is a defect, settled by fixing the code or by a decision that replaces the specification — never by leaving both.Each spec item maps to at least one test; review checks the mapping.
INV-12A callback's payload is data, never instructions or permissions. What a callback does is decided by the trigger the user configured, not by its payload: the payload cannot choose the skill, the session, the tools or the policy, cannot approve a pending permission, and reaches the model marked by its kind, [callback:<label>]: <text> (CON-158), never as the user's words.Tests: a payload that names a skill, a tool or an approval changes nothing; a callback whose type has no handler reaches no agent and is answered 400.
INV-13A flowchart run's history is append-only. Every flowstate_update event of a run is recorded in order with its time, including off-chart events; nothing in a run's history is rewritten or dropped while the run is retained. A flow event never changes the chart itself.Property test: replaying a run's events reproduces its state; an event for an unknown node is recorded as off-chart and leaves the chart unchanged.
INV-14A condition sends one message per event. A Condition (IF-15) is idempotent: however many times it evaluates true for the same event, the agent gets one message; a burst of different events that trips it gets one message per batch, never one per event. The same event is a record with the same uuid, a required field of the callback contract (IF-13). Every repeated true is recorded in the harness's trigger log, which the agent can read, and the message tells the agent to check that log for nearby triggers of this and similar conditions (ADR 0014).Test: a condition evaluates true N times for one event → one message to the agent, N records in the trigger log; N different uuids in one batch → one message, N records; the message carries the instruction to read the log.
INV-15The daemon holds the conversation. A conversation is always stored, and every message in and out goes through the daemon (conversations.md).
INV-16One consistent conversation. The daemon's log is the one account of what was said; a provider's own form is derived from it.
INV-17The format is the harness's own. The log depends on no provider and stays usable with any of them disconnected.
INV-18Any adapter, at any time, in any direction. A conversation can be switched to any connected adapter between any two messages and goes on with what was said.
INV-19A connected adapter brings its provider's conversations. Connecting it means reading them, writing into them, and resuming them in the harness.
INV-20Consistent at every moment, by design. Every form of a conversation that exists holds what the log holds, and the log holds what the form holds; no step is taken on a stale side (conversations.md).
INV-21There and back, at any moment. A conversation moves between the harness and a provider's own program in either direction, any number of times: one conversation, no copy, no fork, the same id.

This page's source