Skip to content
Lowkey Docs

Compatibility policy

The frozen vocabulary below is the public stability promise. Once a seam is observable, it is depended on (Hyrum’s Law), so Lowkey treats every exposed seam as a permanent maintenance contract. The discipline: expose the smallest vocabulary whose composition covers visible demand, plus opaque escape hatches for the rest, and add to the set only under demonstrated demand.

The frozen vocabulary

Section titled “The frozen vocabulary”

What Lowkey commits to keep stable. The host-run capability vocabulary (below) and the declarative seams (items 2–8) are both part of the contract.

  1. Host-run capabilities + entry contract — the closed capability set (net.egress, fs.project(+:write), events.turn, mount.focus/mount.side-panel, cards.emit, session.read, session.fork, token; run.agent reserved) a main.ts uses in the Deno jail, plus the @lowkey/plugin-sdk handler signatures. See Sandboxed packages.
  2. Manifest — the declaration format: id, version, requested scopes, capabilities, and the seam blocks used.
  3. Agent contribution — AgentDef with systemPrompt, platformPromptMode: full | minimal, translator: none, and a runtime reference.
  4. MCP tool registration — the plugin’s MCP server, injected per project. A borrowed protocol Lowkey does not version.
  5. Trigger registration — an inbound webhook source that spawns a scoped run.
  6. Card emission — a small, closed/enumerated card schema (text / link / status / prompt), widened only deliberately. Not open HTML.
  7. Surface mount — a sandboxed iframe in a host-owned named slot (focus, side-panel). The manifest declares which slot; the host draws the chrome. (media capability is designed-for but deferred — first-party-only when it lands.)
  8. Two escape hatches — the external runtime (over a versioned turn protocol) and the driven app (iframe + MCP).
  9. Scoped per-installation token — the capability gate over all of the above.

What stays sealed

Section titled “What stays sealed”

Never exposed; you get events, scoped APIs, and tokens instead:

  • the prompt-assembly mechanism (you get the resulting mode, not how it’s built);
  • the internal AgentEvent type (wrapped by the versioned external protocol);
  • the session JSONL format, resume, and cross-agent injection mechanics;
  • the credential store, run supervision, worktree/isolation, and auth stack;
  • in-process code execution in the daemon — the seal that makes every exposure safe.

Two opinionated calls

Section titled “Two opinionated calls”
  • Cards are a closed schema, not open HTML. Surfaces that want freedom use a sandboxed iframe slot, not the card hatch (cards land in the shared multi-user feed).
  • The translator exposes only none in v1, not bring-your-own-translator. Off is an outcome; a custom voice engine is a mechanism — deferred.

Versioning

Section titled “Versioning”
  • The manifest evolves additively. New optional fields and new scopes may be added; existing fields keep their meaning. Validate against the published JSON Schema for the version you target.
  • The external turn protocol is versioned independently (protocolVersion, currently 1). It is decoupled from Lowkey’s internal types on purpose, so internal refactors do not break plugins. Pin to the version you implement; new versions are additive and announced.
  • Deferred scopes (media, storage) and signing enforcement are designed-for and will arrive as additive capabilities, not breaking changes.

If a change to the frozen vocabulary is ever required, it is an explicit, announced deprecation — not a silent break.