Harness contract

The seam everything third-party builds against. spt-core contains zero harness-specific logic; a harness (or a driven surface) interfaces through exactly two things:

1. The runtime manifest — a declarative TOML file stating what varies for this harness: how to spawn sessions, which hook events fire which commands, how history is read, how the adapter updates. Command templates are opaque strings; spt-core fills {key} placeholders and runs them.
2. The spt api surface — the imperative entry points the harness’s hooks fire to keep spt-core’s state honest: session started, went idle, hit a context boundary, ended.

That’s the whole integration surface. An adapter is a manifest plus the harness’s own native extension points — there is no SDK to link, no daemon to embed, no protocol to speak beyond running spt.

  your harness                         spt-core
 ┌────────────────────┐             ┌──────────────────────────┐
 │ hooks ─────────────┼── api … ───►│ perches · spools ·       │
 │ (SessionStart,     │             │ lifecycle · registry     │
 │  Idle, End, …)     │             │                          │
 │                    │◄────────────┼─ spawns [session.*]      │
 │ sessions           │  templates  │  templates, keys filled  │
 └────────────────────┘             └──────────────────────────┘
          ▲                                      ▲
          └────────── manifest.toml declares both seams

Where to go

• Start: the adapter quickstart — take the reference mock adapter apart and drive the contract in minutes.
• Build it all: the integration checklist — every surface by necessity, mapped to the interaction lifecycle.
• Reference: manifest · spt api · manifest.schema.json.
• Ship it: install-on-demand bootstrap — how an adapter brings spt-core with it.
• Driven surfaces: Shells — the kind = "shell" flavor of the same contract.

Building adapters, shells, or integrations against this contract is unrestricted and royalty-free — see the license split.