WRENCH

Plugin authoring · Wrench 0.9.0

Start a provider plugin inert, then prove one operation.

A Wrench portable plugin begins as a private, network-inert capture-required reservation. It becomes executable only after its exact provider contract and secret-free fixtures are reviewed, the package passes static and runtime verification, and the operator explicitly trusts that content-addressed bundle.

This guide describes v0.9.0 and was checked against the public plugin protocol and authoring guide for that immutable release.

Two plugin forms share one semantic catalog

A source plugin ships with Wrench, loads in process, and may implement a reviewed provider transport. It is trusted application code. A portable plugin is independently authored, content-addressed, installed into local state after an explicit code-trust decision, and run through a versioned, denied-by-default child-process protocol.

Neither plugin form can redefine Wrench's custody rules. The kernel owns input resolution, auth selection, risk, preview and confirmation, dispatch journals, recovery, receipts, bounds, redaction, activation, and lifecycle serialization. A plugin owns the exact provider identity, operation descriptors, request and response contracts, account probes, execution, and reconciliation logic.

1. Create a network-inert reservation

wrench plugin init example-web \
  --display-name "Example" \
  --surface example \
  --origin https://www.example.com \
  --operation feeds.read \
  --output /absolute/private/example-web

The initializer writes a strict wrench-plugin.json, one self-contained runtime, inert operation metadata, secret-free fixtures, and package-local guidance. capture-required means the operation cannot plan or execute. That is the correct state until authorized evidence proves the full contract.

2. Prove the whole operation contract

Before marking an operation observed, establish one semantic operation and bounded input schema; the exact transport, HTTPS origin, route, method, and request shape; a current-account probe; stable subject identity; response, target, side-effect, and completion projections; credential names and allowed sinks; risk and uncertainty behavior; fail-closed drift; and secret-free fixtures for success and every relevant rejection or unsettled outcome.

A UI label, route name, or one captured traffic shape is not enough. Wrench does not treat DOM automation as an execution or recovery fallback.

3. Check, test, pack, and install as separate decisions

wrench plugin check /absolute/private/example-web --json
wrench plugin test /absolute/private/example-web --trust-code --json
wrench plugin pack /absolute/private/example-web \
  --output /absolute/private/example-web.wrenchplugin --json
wrench plugin install /absolute/private/example-web.wrenchplugin \
  --trust-code --json
  1. check parses and validates the package without executing plugin code.
  2. test --trust-code is the first execution boundary. It binds trust to the verified plugin identity and runs declared secret-free fixtures.
  3. pack verifies the fixed file set and produces reproducible, content-addressed package bytes.
  4. install --trust-code records a separate decision to let that exact package run and activates it only after catalog conflict checks.

An update changes package identity and requires a new trust decision. Disable, update, and removal serialize with invocation leases, confirmations, run journals, recovery capsules, and linked-device lifecycles; Wrench refuses a transition while the old bundle owns live or unknown work.

Portable host capabilities are declared and bounded

  • Exact-origin HTTPS with bounded request and response bodies.
  • Opaque cookie material bound only to its cookie jar and OAuth material bound only to the Authorization header.
  • Content-bound file handles with bounded reads and namespaced JSON state.
  • Bounded diagnostics plus explicit mutation dispatch-begin and verification steps.
  • Declared session-material handles.

The host does not expose a shell, package manager, ambient environment, raw auth locator, unrestricted filesystem, arbitrary redirect, automatic retry, or caller-chosen network primitive. Native code and undeclared module imports are rejected.

This protocol contains ordinary failures but is not a hostile-code sandbox. Plugin code runs with the current account's ambient operating-system authority. Review it before trust and read the security guide for the exact boundary.

Use the public types without triggering runtime state

The package root exports bounded identifier and version validators plus the types used to describe source plugins and portable protocol messages. It is intentionally side-effect-free. Use wrench plugin check as the authoritative validation of a complete authoring directory and wrench plugin test --trust-code as the explicit runtime boundary.

The complete source guide lives at docs/plugins.md for v0.9.0. Pinning the tag keeps the prose and protocol tied to the release described here.