@kaiba-cloud/orbital 0.0.0-stage → 0.0.2

package/skills/orbital-plugin-builder/references/ports.md

@@ -0,0 +1,1132 @@
+# Ports: each port of `PluginPorts`
+
+Each section has the same parts:
+
+- **For**: what the port does for the node.
+- **When**: when the node calls each method.
+- **Config**: how `orbital.yaml` chooses the plugin for the port.
+- **Interface**: the TypeScript interface, as `ports.ts` in `@kaiba-cloud/orbital` declares it.
+- **Remote methods**: the JSON-RPC methods for a plugin out of process, with their named params. The SDK maps them to your object. You need them only when you write a plugin without the SDK.
+- **Example**: a minimal port that passes `orbital plugin check`.
+
+Every type comes from `@kaiba-cloud/orbital-sdk`. Each argument and each answer
+is plain JSON. A method that the interface marks with `?` is optional. Leave it
+out, and the manifest says that the plugin does not provide it.
+
+The order of plugins: first the plugins of `orbital.yaml`, in the order of
+`plugins:`, then the built-in plugins `orbital`, `local`, `static`, `git` and
+`folder`. "In plugin order" below means this order. So your plugin answers a
+hook such as `sessions.create` before a built-in plugin does.
+
+## `directory`
+
+**For.** Give the node agents and blueprints that are not files of a harness
+folder. Examples: a registry of agents, or the agents of other machines.
+
+**When.**
+
+- `agents(workspaceDir)`: the node lists its agents, for `agent list`, for the
+  catalog and for `agentPeers`. An agent file with the same name hides a
+  directory agent.
+- `lookup(ref)`: a run names an agent that no harness folder has. The
+  node asks each directory in order. The first answer that is not null wins.
+- `agent(id, session)`: a session of an agent from this directory starts. The
+  answer gives its harness, egress and bootstrap. The node reads these
+  `bootstrap` keys: `systemPrompt`, `agentModel`, `provider`, `harness` and
+  `skills` (a list of `ResolvedSkill`).
+- `blueprint(id, session)` and `blueprintFile(id, path, session)`: a session of
+  an agent from this directory calls `GET /orbital/blueprints/<id>` or
+  `GET /orbital/blueprints/<id>/file?path=<path>` on the node.
+- `announce(catalog)`: once, after the node serves and its channels listen. The
+  catalog holds the teams, the agents, the live sessions and the started teams
+  of the node. A directory that other machines read uses it to publish this
+  node.
+
+**Config.** `directory: <plugin>` or `directory: [<plugin>, ...]`. Without the
+key, the node uses each plugin that provides a directory, in plugin order.
+
+**Interface.**
+
+```ts
+interface Directory {
+  agents(workspaceDir: string): Promise<DirectoryAgentSummary[]>;
+  lookup(ref: string): Promise<DirectoryAgentRef | null>;
+  agent(id: string, session: SessionInfo): Promise<ResolvedAgent | null>;
+  blueprint?(id: string, session: SessionInfo): Promise<BlueprintContent | null>;
+  blueprintFile?(id: string, path: string, session: SessionInfo): Promise<BlueprintFile | null>;
+  announce?(catalog: MachineCatalog): Promise<void>;
+}
+interface DirectoryAgentSummary { name: string; id: string | null; description: string | null }
+interface DirectoryAgentRef { id: string; name: string }
+interface ResolvedAgent { id: string; name: string; harness: Harness | null; bootstrap: Record<string, unknown>; egress: string[] }
+interface ResolvedSkill { slug: string; name: string; description: string | null; loadMode?: string; contentBase64: string; files: Array<{ path: string; contentBase64: string }> }
+interface BlueprintContent { id: string; contentBase64: string; files: Array<{ path: string; size: number; hash: string | null }> }
+interface BlueprintFile { path: string; mimeType: string | null; size: number; contentBase64: string }
+```
+
+**Remote methods.** `directory.agents {workspaceDir}`, `directory.lookup {ref}`,
+`directory.agent {id, session}`,
+`directory.blueprint {id, session}`, `directory.blueprintFile {id, path, session}`,
+`directory.announce {catalog}`.
+
+**Example.**
+
+```ts
+const agents = [{ id: 'rev-1', name: 'reviewer', description: 'Reviews a pull request.', prompt: 'You review code.' }];
+
+ports: {
+  directory: {
+    agents: async () => agents.map(({ id, name, description }) => ({ id, name, description })),
+    lookup: async (ref) => agents.find((one) => one.name === ref || one.id === ref) ?? null,
+    agent: async (id) => {
+      const found = agents.find((one) => one.id === id);
+      return found ? { id: found.id, name: found.name, harness: null, egress: [], bootstrap: { systemPrompt: found.prompt } } : null;
+    },
+  },
+},
+```
+
+The check: `agents()` answers `{ name, id, description }` items, and `lookup()`
+of an unknown name answers null.
+
+## `placements`
+
+**For.** Run a session somewhere other than this node: another machine, a
+cloud service, or a node behind a channel. The key of the record is the
+placement kind. A placement is `<kind>` or `<kind>:<name>`, such as
+`lan:build-box`.
+
+**When.** A new session gets a placement other than `local` from one of these:
+
+- the member entry in `teams/<team>/CHARTER.md`: `members: [{ name: coder, placement: lan:build-box }]`;
+- the `placement` parameter of `agentDispatch`;
+- a `sessions.create` answer `{ kind: 'placement', placement }` (see `sessions`).
+
+Then the node calls `endpoint(placement)`. It sends the A2A `SendMessage` of
+the turn to the answer, and follows the task until it ends. A later turn of the
+same session goes to the same placement.
+
+- An `A2aEndpoint` answer: the node posts JSON-RPC to `url` with `headers`. A
+  node of orbital serves A2A at `<node url>/a2a` and takes its own secret as
+  `authorization: Bearer <token>`.
+- A `ChannelRoute` answer: the node sends the turn on that channel to `to`.
+- `decides: true`: the endpoint chooses the target itself. The node does not
+  put the placement in the message metadata (`orbital/placement`). With
+  `decides: false`, the node puts it there, so the far side can place the
+  session.
+
+**Config.** `placement: { <kind>: <plugin> }`. Without an entry for a kind, the
+node uses the first plugin that serves the kind. A placement kind that no
+plugin serves refuses the session start.
+
+**Interface.**
+
+```ts
+interface Placement {
+  endpoint(placement: string): Promise<PlacementTarget>;
+  readonly decides?: boolean;
+}
+type PlacementTarget = A2aEndpoint | ChannelRoute;
+interface A2aEndpoint { url: string; headers: Record<string, string> }
+interface ChannelRoute { channel: string; config: Record<string, unknown>; to: Address }
+```
+
+**Remote methods.** `placement.endpoint {placement}`. The SDK sends the call to
+the placement whose key is the part before `:`.
+
+**Example.**
+
+```ts
+ports: {
+  placements: {
+    lan: {
+      decides: true,
+      endpoint: async (placement) => {
+        const name = placement.slice('lan:'.length);
+        const peer = peers.get(name);
+        if (!peer) throw new Error(`No peer ${name} on this network.`);
+        return { url: `${peer.url}/a2a`, headers: { authorization: `Bearer ${peer.token}` } };
+      },
+    },
+  },
+},
+```
+
+The check needs a fixture: `{"placements":{"lan":"lan:build-box"}}`. Without
+it, the check skips.
+
+## `policy`
+
+**For.** Allow, deny or ask before the node does an action.
+
+**When.** Before each action of these kinds:
+
+| `kind` | When | Fields |
+|---|---|---|
+| `tool.call` | A tool call of a session | `sessionId`, `tool`, `target`, `name`, `input` |
+| `session.start` | A session starts | `agent`, `placement`, `harness`, `parentSessionId`, `workspaceDir` |
+| `session.contribution` | A `sessions.open` hook asks for egress | `sessionId`, `plugin`, `egress` |
+| `message.send` | One agent sends a message to another | `fromSessionId`, `toSessionId`, `rootSessionId`, `hops`, `at` |
+| `model.use` | A model call, also `host.completeModel` | `sessionId`, `model`, `plugin` |
+| `plugin.load` | A plugin starts (see the note below) | `plugin`, `network`, `secrets`, `models` |
+| `channel.receive` | A message reaches the node from a channel or over the network (see the section below) | `channel`, `from`, `to`, `human`, `text`, `origin` |
+| `action.submit` | An agent submits an action type | `sessionId`, `actionType`, `actor` |
+| `mission.start` | A mission starts | `team`, `mission`, `plugin`, `event`, `key` |
+
+Note: the node checks `plugin.load` while it starts the plugins, before any
+policy engine runs. In this version no engine sees that action from a node.
+
+### `channel.receive`
+
+The action gives an engine the text of a message and where it came from, so an
+engine can govern each message that reaches the node over the network.
+
+```ts
+type ChannelTrust = 'verified' | 'unverified';
+type ChannelOrigin =
+  | { kind: 'local' }
+  | { kind: 'network'; peer: string; address: Address; trust: ChannelTrust };
+type ChannelReceive = {
+  kind: 'channel.receive';
+  channel: string;
+  from: Address;
+  to: Address;
+  human: boolean;
+  text: string;
+  origin: ChannelOrigin;
+};
+```
+
+- `text` is the text of the message. A call with no text, such as a cancel or a
+  pause, gives a short phrase that names the operation, for example
+  `cancel the task t1`.
+- `human` is true when the sender is a person.
+- `origin.peer` is the name of the sending node when the sender address has an
+  `ade`. Else it is the name of the sender, or the name that the carrying
+  plugin gives.
+- `origin.address` is the address of the sender.
+- `origin.trust` is `verified` only when the channel declares
+  `authenticated: true`. Every other path gives `unverified`.
+- `origin.kind` is `local` only for a message on a channel that declares
+  `authenticated: true` when the sender address names this node in `ade`. The
+  address of a message that an unauthenticated channel delivers is the word of
+  the sender, so the node never trusts it as local.
+- A session of the node, a holder of the node secret and the CLI on the same
+  machine never reach this action. A request over HTTP reaches it when its
+  socket address is not a loopback address.
+
+The node checks `channel.receive` on these paths, and each refusal gives the
+reason to the sender:
+
+| Path | The sender gets |
+|---|---|
+| `host.deliver`: work, a cancel, the answer of a person to a question | `DeliveryAnswer` with `accepted: false` and the `reason`. For refused work, the node also sends a reply over the same channel (see below) |
+| `host.joinMission`, `replyMission`, `sayMission`, `pauseMission`, `resumeMission`, `askGiver` | an error with the reason |
+| `host.a2a`, and a request to `/a2a` from a non-loopback address | a JSON-RPC error with the reason |
+
+The answer of a remote node to a request of this node is not checked: this
+node made the request.
+
+When the node refuses work that a channel delivered, it also sends the sender a
+reply envelope over the same channel. The reply is in the same thread, from the
+receiver to the sender. Its message answers the request (`orbital/inReplyTo`)
+with a status update of the state `TASK_STATE_REJECTED`. The text of the status
+message is `refused: <reason>`. The node of the sender turns the reply into the
+status of the task that its session reads, so the sender sees the request end
+as rejected with the reason as its result. A refused cancel and a refused
+answer of a person get no reply.
+
+The node asks each engine in order. One `deny` refuses the action. An `ask`
+waits for a person on the team's channel. An engine with
+`deterministic: false`, such as a model, can only deny or ask: the node reads
+its `allow` as no answer.
+
+**Config.** `policy: [orbital, <plugin>, ...]`, in the order to ask. Each entry
+is a plugin name or `{ plugin: <name>, ...settings }`. Without the key, the node
+asks each plugin that provides a policy, in plugin order. `orbital` is the
+built-in engine. It limits the messages between agents.
+
+**Interface.**
+
+```ts
+interface PolicyEngine {
+  readonly deterministic: boolean;
+  decide(action: PolicyAction): Promise<PolicyDecision>;
+}
+type PolicyDecision =
+  | { verdict: 'allow' }
+  | { verdict: 'deny'; reason: string; policy: string }
+  | { verdict: 'ask'; question: string; policy: string };
+```
+
+**Remote methods.** `policy.decide {action}`.
+
+**Example.**
+
+```ts
+ports: {
+  policy: {
+    deterministic: true,
+    decide: async (action) => {
+      if (action.kind === 'tool.call' && action.tool === 'shell' && action.target.includes('git push')) {
+        return { verdict: 'deny', reason: 'Pushes go through review.', policy: 'push-guard' };
+      }
+      if (action.kind === 'session.start' && action.placement !== 'local') {
+        return { verdict: 'ask', question: `Start ${action.agent} on ${action.placement}?`, policy: 'push-guard' };
+      }
+      return { verdict: 'allow' };
+    },
+  },
+},
+```
+
+The check: each answer is `allow`, `deny` with a reason, or `ask` with a
+question. For a model as the judge, see the policy recipe in
+[recipes.md](recipes.md).
+
+## `telemetry`
+
+**For.** Send the usage of each turn, spans and the events of the node to a
+dashboard or a metrics system.
+
+**When.**
+
+- `usage(session, report)`: after each turn, with the tokens of each model. The
+  session gives `node`, `team`, `mission`, `agent` and `parentSessionId`.
+- `span(span)`: for each span the node records, such as an action call.
+- `event(event)`: for each event of the node, in order: `node.up`, `node.down`,
+  `session.started`, `session.ended`, `job.dispatched`, `job.ended`,
+  `mission.state`, `turn.started`, `turn.ended`. A `turn.ended` holds the usage
+  of the turn. A sub-agent of a lead whose type names a team member is a job of
+  that member, with `via` the lead.
+
+Each event has `v` (`orbital.telemetry/v1`), `seq`, `id`, `at` and `node`.
+`seq` goes up by one for each event of the node. The node never waits for a
+sink. It keeps at most 1000 calls for each sink, drops the oldest past that,
+and warns with the count. A call that takes more than 10 seconds counts as
+failed.
+
+To hold a live graph, take `host.snapshot()` once when the service starts. Then
+apply only the events with a `seq` above its `sequence`. A gap in `seq` means
+that the sink dropped events: take a new snapshot. See
+[host-api.md](host-api.md#snapshot) and the dashboard recipe in
+[recipes.md](recipes.md).
+
+**Config.** `telemetry: <plugin>` or a list. Without the key, the node sends to
+each plugin that provides telemetry.
+
+**Interface.**
+
+```ts
+interface TelemetrySink {
+  usage?(session: SessionInfo, report: UsageReport): Promise<void>;
+  span?(span: TelemetrySpan): Promise<void>;
+  event?(event: OrbitalEvent): Promise<void>;
+}
+interface UsageReport { harness: Harness; models: ModelUsage[] }
+interface TelemetrySpan { name: string; start: number; end: number; attributes: Record<string, string | number | boolean>; status: 'ok' | 'error' }
+```
+
+**Remote methods.** `telemetry.usage {session, report}`, `telemetry.span {span}`,
+`telemetry.event {event}`.
+
+**Example.**
+
+```ts
+ports: {
+  telemetry: {
+    usage: async (session, report) => send({ node: session.node, team: session.team, mission: session.mission, models: report.models }),
+    event: async (event) => send(event),
+  },
+},
+```
+
+`orbital plugin new <name> --port telemetry` writes a sink that keeps the
+graph. The JSON Schema of an event and of a snapshot are in the `schemas`
+folder of `@kaiba-cloud/orbital`. `orbital telemetry watch` prints the
+same events, and `orbital telemetry snapshot` prints the same snapshot.
+
+## `sessions`
+
+**For.** Take part in the life of each session: choose where a new session
+runs, give a session environment, commands, egress and prompt text, and receive
+its events.
+
+**When.**
+
+- `create(start)`: a new session is about to start on this node, with no
+  placement chosen. Answer `{ kind: 'id', sessionId }` to give the session its
+  id: the plugin then owns the session. Answer `{ kind: 'placement', placement }`
+  to start it on a placement (see `placements`). Answer null to pass. The node
+  asks each plugin in plugin order. The first answer that is not null wins.
+- `open(session)`: a turn of the session starts on this node. The answer adds to
+  the turn:
+  - `env`: variables for the harness. The first plugin that sets a name wins.
+  - `shims`: `name: command`. The node writes an executable `name` on the
+    turn's PATH that runs `command`.
+  - `egress`: hosts the sandbox lets the turn reach. A `session.contribution`
+    policy action decides it first.
+  - `promptBlock`: text the node adds to the system prompt.
+  - `sinks`: names of event sinks. The node then calls `deliver` for each one.
+- `close(session)`: the turn ends, or `open` of a later plugin failed. The node
+  closes the plugins in reverse order.
+- `deliver(sink, sessionId, events)`: after the node writes new events to the
+  log of a session that has the sink. `events` holds the events after the last
+  one the sink took. Answer the `sequence` of the last event you took. The node
+  sends the rest again on the next call.
+
+**Config.** None. The node calls the hooks of every enabled plugin.
+
+**Interface.**
+
+```ts
+interface SessionHooks {
+  create?(start: SessionStartRequest): Promise<SessionStartAnswer | null>;
+  open?(session: SessionInfo): Promise<SessionContribution | null>;
+  close?(session: SessionInfo): Promise<void>;
+  deliver?(sink: string, sessionId: string, events: readonly SessionEvent[]): Promise<number>;
+}
+interface SessionStartRequest { agent: string; parentSessionId: string | null; team: string | null; definitionAgent: boolean; declaration: Record<string, unknown> | null; register: boolean }
+type SessionStartAnswer = { kind: 'id'; sessionId: string } | { kind: 'placement'; placement: string };
+interface SessionContribution { env?: Record<string, string>; shims?: Record<string, string>; egress?: string[]; promptBlock?: string; sinks?: string[] }
+interface SessionInfo {
+  sessionId: string; node: string; agent: string; agentId: string | null; agentSource: string | null;
+  declaration: Record<string, unknown> | null; parentSessionId: string | null; workspaceDir: string;
+  harness: Harness; team: string | null; mission: string | null;
+  scratchpad: string | null; memory: string | null; missionScratchpad: string | null;
+}
+```
+
+**Remote methods.** `sessions.create {start}`, `sessions.open {session}`,
+`sessions.close {session}`, `sessions.deliver {sink, sessionId, events}`.
+
+**Example.**
+
+```ts
+ports: {
+  sessions: {
+    open: async (session) => ({
+      env: { TICKET_SESSION: session.sessionId },
+      promptBlock: `You work for the team ${session.team ?? 'none'}.`,
+      sinks: ['audit'],
+    }),
+    deliver: async (_sink, sessionId, events) => {
+      await appendAudit(sessionId, events);
+      return events.at(-1)?.sequence ?? 0;
+    },
+  },
+},
+```
+
+The check opens a session and requires `env` values to be strings and
+`egress` to be a list of hosts.
+
+## `tools`
+
+**For.** Host tools that sessions of the node call, such as a search in a
+company system.
+
+**When.** A session of the node calls `POST <node url>/orbital/tools/<name>`
+with its session token. The node first asks the `actions` port. Then it asks
+each `tools` port in plugin order. The first answer that is not null wins. A
+null answer means "not my tool".
+
+The agent tools server of the node lists only the action tools. To make a
+hosted tool known to an agent, tell the agent in a `sessions.open`
+`promptBlock`, or give it a command through `shims`.
+
+**Config.** None. The node uses the tools of every enabled plugin. The names in
+`names` must not clash with an action tool: a clash refuses the call.
+
+**Interface.**
+
+```ts
+interface ToolGateway {
+  readonly names: readonly string[];
+  call(name: string, input: Record<string, unknown>, session: SessionInfo): Promise<HostedToolResult | null>;
+}
+interface HostedToolResult { text: string; isError: boolean; structuredContent?: JsonObject }
+```
+
+**Remote methods.** `tools.call {name, input, session}`.
+
+**Example.**
+
+```ts
+ports: {
+  tools: {
+    names: ['ticket-get'],
+    call: async (name, input) => {
+      if (name !== 'ticket-get') return null;
+      const ticket = await fetchTicket(String(input.id));
+      return { text: JSON.stringify(ticket), isError: false, structuredContent: ticket };
+    },
+  },
+},
+```
+
+The check: `call()` of an unknown tool answers null.
+
+## `channels`
+
+**For.** Carry A2A messages between people, teams and nodes: Slack, Discord,
+email, a file. The key of the record is the channel id.
+
+**When.**
+
+- `listen(bindings)`: when the node starts serving, with the bindings of the
+  started teams and of `channels:` in `orbital.yaml`. A later call replaces the
+  bindings. After a restart of the plugin, the node calls it again.
+- `send(envelope, binding)`: the node sends a message on the binding, such as an
+  answer or a question that waits for a person.
+
+A message that arrives on the service goes to `host.deliver(inbound)`.
+
+**Config.** A team names the channel in `teams/<team>/channels.yaml` as
+`type: <id>`. The other keys of the entry are the binding's `config`. A node
+names its own channels under `channels:` in `orbital.yaml`. The node uses the
+first plugin that provides the id.
+
+**Interface.**
+
+```ts
+interface Channel {
+  readonly capabilities: ChannelCapabilities;
+  send(envelope: ChannelEnvelope, binding: ChannelBinding): Promise<{ ref: string; thread: string | null }>;
+  listen(bindings: readonly ChannelBinding[]): Promise<void>;
+}
+interface ChannelCapabilities { live: boolean; human: boolean; threads: boolean; durable: boolean; offline: boolean; authenticated: boolean }
+interface ChannelBinding { id: string; channel: string; config: Record<string, unknown>; team: string | null; ade: string }
+interface ChannelEnvelope { message: Message; from: Address; to: Address; thread: string | null }
+interface Address { kind: 'agent' | 'team' | 'session' | 'person' | 'node'; name: string; ade?: string }
+interface InboundDelivery { channel: string; bindingId: string; envelope: ChannelEnvelope }
+```
+
+**Remote methods.** `channel.send {channel, envelope, binding}`,
+`channel.listen {channel, bindings}`. `channel` is the channel id.
+
+**Example.**
+
+```ts
+const sent = new Map<string, { ref: string; thread: string | null }>();
+let bindings: ChannelBinding[] = [];
+
+ports: {
+  channels: {
+    discord: {
+      capabilities: { live: true, human: true, threads: true, durable: true, offline: false, authenticated: true },
+      send: async (envelope, binding) => {
+        const known = sent.get(envelope.message.messageId);
+        if (known) return known;
+        const ref = await post(binding.config.channel, envelope);
+        const answer = { ref, thread: envelope.thread ?? ref };
+        sent.set(envelope.message.messageId, answer);
+        return answer;
+      },
+      listen: async (given) => { bindings = [...given]; },
+    },
+  },
+},
+```
+
+- `capabilities`: `live` (it pushes), `human` (a person reads and writes),
+  `threads`, `durable`, `offline` (it works with no network outside the LAN),
+  `authenticated` (the channel proves who sent each message, so the node marks
+  its messages `verified`). Set `authenticated: false` when the channel only
+  carries the word of the sender, such as a shared folder.
+- A second send of the same message id must answer the first ref and send
+  nothing.
+- A message id must be stable: the node drops a second delivery of the same id.
+- Put an answer in the thread of its question.
+- Fixture for the send check:
+  `{"channels":{"discord":{"id":"node:0","channel":"discord","config":{},"team":null,"ade":"conformance"}}}`.
+
+The Slack recipe in [recipes.md](recipes.md) adds the service that listens.
+
+## `store`
+
+**For.** Keep session state off this machine, such as in R2 or S3.
+
+**When.** The node reads a unit when a session resumes or a scratchpad is
+restored. It writes the unit after the session changes. With `lease`, one ADE
+at a time holds a unit.
+
+- `history`: the run state of a session: the transcript, the event log and the
+  harness state. A resume on another machine reads it.
+- `session` and `mission`: the scratchpads, as text files only. A transcript
+  never goes there.
+- `temporary`: short-lived files.
+
+**Config.** Only an explicit choice: `store: { history: [{ plugin: r2, bucket: orbital }] }`.
+`settings` is the choice without `plugin`: here `{ bucket: 'orbital' }`. A store
+whose `kinds` do not hold the kind refuses the start.
+
+**Interface.**
+
+```ts
+interface StateStore {
+  readonly kinds: readonly StateKind[];
+  list(ref: StoreRef): Promise<StoredEntry[] | null>;
+  read(ref: StoreRef, path: string): Promise<StoredFile | null>;
+  write(ref: StoreRef, files: readonly StoredFile[], removed: readonly string[]): Promise<void>;
+  lease?(ref: StoreRef, holder: string, ttlMs: number): Promise<StoreLease>;
+  release?(ref: StoreRef, holder: string): Promise<void>;
+}
+type StateKind = 'history' | 'session' | 'mission' | 'temporary';
+interface StoreRef { kind: StateKind; id: string; unit: string; settings: Record<string, unknown> }
+interface StoredEntry { path: string; hash: string; size: number }
+interface StoredFile { path: string; contentBase64: string }
+interface StoreLease { granted: boolean; holder: string; expiresAt: string }
+```
+
+**Remote methods.** `store.list {ref}`, `store.read {ref, path}`,
+`store.write {ref, files, removed}`, `store.lease {ref, holder, ttlMs}`,
+`store.release {ref, holder}`.
+
+**Example.**
+
+```ts
+ports: {
+  store: {
+    kinds: ['history'],
+    list: async (ref) => /* [{ path, hash: SHA-256 hex, size }], or null when it holds no unit */,
+    read: async (ref, path) => /* { path, contentBase64 } or null */,
+    write: async (ref, files, removed) => { /* write files, delete the removed paths */ },
+  },
+},
+```
+
+- `unit` is the place of the unit, the same on every ADE: `sessions/<id>` for
+  history, `agents/<agent>/sessions/<id>` for a session scratchpad. Use it as
+  the key prefix.
+- Paths use `/` between folders. Refuse a path that leaves the unit.
+- Fixture: `{"store": <settings>}`. `orbital plugin new <name> --port store`
+  writes a store in a folder that passes every check.
+
+## `workspace`
+
+**For.** Keep the working folder of a team or an agent off this machine. A
+session's own (`ephemeral`) workspace is never saved.
+
+**When.** `load(ref, dir)` when the node makes the workspace on a machine that
+has none of it. `save(ref, dir, ignore)` after each turn.
+
+**Config.** Only an explicit choice: `store: { workspace: [{ plugin: r2, bucket: orbital }] }`.
+
+**Interface.**
+
+```ts
+interface WorkspaceStore {
+  load(ref: WorkspaceRef, dir: string): Promise<boolean>;
+  save(ref: WorkspaceRef, dir: string, ignore: readonly string[]): Promise<void>;
+}
+type WorkspaceOwner = 'team' | 'agent' | 'session';
+interface WorkspaceRef { project: string; owner: WorkspaceOwner; name: string; settings: Record<string, unknown> }
+```
+
+**Remote methods.** `workspace.load {ref, dir}`, `workspace.save {ref, dir, ignore}`.
+
+**Example.**
+
+```ts
+ports: {
+  workspace: {
+    load: async (ref, dir) => /* fill dir; answer false when the store holds none */,
+    save: async (ref, dir, ignore) => { /* store dir, except the paths in ignore, such as .git */ },
+  },
+},
+```
+
+- The plugin runs on the node's machine, so it reads and writes `dir` itself.
+- `project` is `<folder>-<hash>`, the same on every machine with the same
+  remote. `name` is the team (`<team>.<mission>` for mission work), the agent
+  or the session id. Use `<project>/<owner>/<name>` as the key prefix.
+- A save is the whole workspace: a file removed from the workspace goes from the
+  store too.
+- Fixture: `{"workspace": <settings>}`.
+
+## `harnesses`
+
+**For.** Bring a harness to orbital: run turns on another agent program, such
+as a CLI agent, and own the folder of that harness in a project (its agent
+files, its `orbital.yaml`, and how it connects to orbital). One port does both:
+it is the adapter of the harness. `claude` is the only harness built in;
+every other harness, `pi` among them, is a plugin on this port.
+
+**When.** A session's harness is one of the ids. For each turn, the node calls
+`command(spec)`, writes the spec to a file, sets `ORBITAL_HARNESS_TURN` to its
+path, and runs the command in the sandbox.
+
+**Config.** None. An agent or a team member names the harness id. The node uses
+the first plugin that brings the id. A harness with a `folder` is set up in a
+project with `orbital install <id> --plugin <npm package|path>`.
+
+**Interface.**
+
+```ts
+interface HarnessProvider {
+  readonly harnesses: ReadonlyArray<{ id: string; description: string; callsModel?: boolean; browser?: boolean; folder?: HarnessFolder | null }>;
+  command(spec: HarnessTurnSpec): Promise<HarnessCommand>;
+  install?(request: HarnessInstallRequest): Promise<{ written: string[]; notes: string[] }>;
+  agents?(request: HarnessAgentsRequest): Promise<HarnessAgentFile[]>;
+}
+interface HarnessFolder {
+  folder: string;                       // '.foo': a dot and the name, at the root of the project
+  instructions?: string | null;         // the harness's instructions file, such as FOO.md
+  agents?: string;                      // the folder of the agent files, default 'agents'
+  skills?: string | null;               // the folder of the skills
+  agentFiles?: 'markdown' | 'plugin';   // markdown with frontmatter (default), or agents() reads them
+  agentHarness?: 'adapter' | 'node';    // an agent file that names no harness runs on this one (default), or on the node's default
+}
+interface HarnessInstallRequest { harness: string; workspaceDir: string; folder: string; program: string[]; force: boolean }
+interface HarnessAgentsRequest { harness: string; workspaceDir: string; folder: string; dir: string }
+interface HarnessAgentFile { name: string; description?: string | null; systemPrompt: string; model?: string | null; harness?: string | null }
+interface HarnessCommand { command: string[]; env?: Record<string, string>; egress?: string[] }
+interface HarnessTurnSpec {
+  harness: string; sessionId: string; prompt: string; systemPrompt: string; model: string | null;
+  workspaceDir: string; sessionDir: string; resume: boolean; env: Record<string, string>;
+  credentials: Array<{ provider: string; authType: string; payload: string }>;
+  tools: { command: string[]; env: Record<string, string> };
+  browser: { url: string; headers: Record<string, string> } | null;
+  scratchpad: string | null; memory: string | null; missionScratchpad: string | null;
+}
+```
+
+**Remote methods.** `harness.command {spec}`, `harness.install {request}`, `harness.agents {request}`.
+
+**Example.**
+
+```ts
+ports: {
+  harnesses: {
+    harnesses: [{ id: 'my-agent', description: 'My agent CLI.', callsModel: false, folder: { folder: '.my-agent', instructions: 'MY-AGENT.md' } }],
+    command: async () => ({
+      command: [process.execPath, fileURLToPath(new URL('turn.js', import.meta.url))],
+      env: {},
+      egress: ['api.openai.com'],
+    }),
+    install: async (request) => registerMcpServer(request),
+  },
+},
+```
+
+An id is `a-z`, `0-9` and `-`, at most 32. `callsModel` is true by default:
+the node then needs a provider key for the agent's model and gives it in
+`credentials`. Set `callsModel: false` for a program that uses its own login or
+calls no model.
+
+**The shared browser.** `browser` is false by default. A harness that sets
+`browser: true` gets `spec.browser` in each turn: the URL of the shared browser
+of the node, an MCP server over streamable HTTP, and the headers that name the
+node token and the session. The harness then sends the browser calls of the
+agent there, in place of the chrome-devtools server of its own config. A
+harness that sets no `browser` gets `spec.browser: null` and has no browser
+tools.
+
+**The folder.** A harness with a `folder` owns that folder in a project, as
+`claude` owns `.claude`: `orbital.yaml`, `teams/`, `missions/`, `policies/`,
+`orbital/plugins/` and its agent files. `orbital-plugin.json` declares the same
+folder under `harnesses`, so a project finds the adapter before the plugin
+runs; the node refuses a plugin whose two declarations differ:
+
+```json
+{ "name": "my-agent", "command": ["node", "dist/plugin.js"],
+  "harnesses": [{ "id": "my-agent", "folder": ".my-agent", "instructions": "MY-AGENT.md" }] }
+```
+
+`orbital install my-agent --plugin <npm package|path>` loads the adapter,
+writes `.my-agent/orbital.yaml` with the plugin under `plugins:` (so a clone
+finds it), and calls `install`. `install` connects the harness to orbital, for
+example it registers the orbital MCP server in the harness's own config:
+`request.program` is the command that runs orbital, and the server is
+`[...program, 'mcp', '--attach', '--harness', <id>, '--agent', <id>]`. A second
+`install` writes nothing. The orbital files of every harness folder that
+an adapter knows load together; a team runs where its folder is.
+
+The harnesses a node runs are `claude` and the ids of its harness plugins. A node refuses to start when a charter member or an agent names
+a harness outside them, and names the ones it runs. A member runs on the
+harness its charter names, also when its lead dispatches it.
+
+The turn program writes one JSON object a line on stdout. Each `message` shows
+live in `orbital up`, in the pane of the Claude Code mod and in the transcript
+of the session; build its parts with `textPart`, `thinkingPart`,
+`toolCallPart` and `toolResultPart` from `@kaiba-cloud/orbital-sdk`:
+
+```ts
+const say = (role: 'ROLE_AGENT' | 'ROLE_USER', parts: Part[]) => line({ type: 'message', message: { messageId: randomUUID(), role, parts } });
+say('ROLE_AGENT', [thinkingPart('I look at the workspace first.')]);
+say('ROLE_AGENT', [toolCallPart({ id: 'c1', name: 'ls', input: { path: spec.workspaceDir } })]);
+say('ROLE_USER', [toolResultPart({ callId: 'c1', name: 'ls', text: listing, isError: false })]);
+say('ROLE_AGENT', [textPart(answer)]);
+line({ type: 'usage', models: [{ provider: 'example', model: spec.harness, inputTokens: 12, outputTokens: 33 }] });
+line({ type: 'result', text: answer });
+```
+
+A turn with no `result` failed. `{"type":"error","message":"…"}` says why. A
+line that is not JSON is the program's own log. `usage` reaches the telemetry
+of the node as the tokens of the turn. `spec.resume` is true when the session
+has turns already. A stop or a mission pause ends the process with SIGTERM.
+`orbital plugin new <name> --port harness` writes a harness that does all of
+this; recipe 5 runs it in a team.
+
+The spec gives three folders, or null when the run has none: `scratchpad` (the
+session's working documents), `memory` (the agent's memory, which outlives the
+session) and `missionScratchpad` (the shared folder of the mission). Mapping
+them is optional. The environment also has `$ORBITAL_SCRATCHPAD`,
+`$ORBITAL_MEMORY` and `$ORBITAL_MISSION`. The sandbox lets the turn write them.
+
+## `panels`
+
+**For.** Rows that a surface shows: `orbital panel`, `orbital up` and the TUI.
+The key of the record is the panel id.
+
+**When.** `read()` each time a surface shows the panel.
+
+Two panel ids have a meaning to the node:
+
+- `missions`: rows of missions of other nodes. The node merges them into its
+  mission list and uses them for claims. See the missions recipe in
+  [recipes.md](recipes.md).
+- `peers`: rows with `node`, `address` and `trust`. `orbital up` prints a line
+  for each new peer.
+
+**Config.** None. Every enabled plugin's panels show.
+
+**Interface.**
+
+```ts
+interface Panel {
+  readonly title: string;
+  readonly kind: PanelKind;
+  read(): Promise<PanelData>;
+}
+type PanelKind = 'list' | 'tree' | 'transcript' | 'form';
+interface PanelData { columns: string[]; rows: Array<Record<string, string | number | boolean | null>>; note?: string }
+```
+
+**Remote methods.** `panel.read {id}`.
+
+**Example.**
+
+```ts
+ports: {
+  panels: {
+    queue: {
+      title: 'discord queue',
+      kind: 'list',
+      read: async () => ({ columns: ['channel', 'waiting'], rows: [{ channel: '#bugs', waiting: 2 }], note: 'Counts refresh each read.' }),
+    },
+  },
+},
+```
+
+Each row key must be a column. Each value is a string, a number, a boolean or
+null. `orbital panel <plugin>/<id>` shows it.
+
+## `actions`
+
+**For.** Run the action types of the ontology. The action gateway of the node
+lists them to agents as tools, and sends each call to this port.
+
+**When.**
+
+- `catalog(session)`: the agent tools server of a session lists its tools.
+- `evaluate(request, session)`: a call of a tool with `readOnlyHint: true`. It
+  reads and changes nothing.
+- `submit(request, session)`: a call of any other tool, after the
+  `action.submit` policy action. Answer `applied` with the edits, or `refused`
+  with findings.
+
+The node checks the input against `inputSchema` before it calls the port.
+
+**Config.** None. The node uses the first plugin that provides actions.
+
+**Interface.**
+
+```ts
+interface ActionsPort {
+  catalog(session: SessionInfo): Promise<ActionTool[]>;
+  submit(request: ActionRequest, session: SessionInfo): Promise<ActionResult>;
+  evaluate(request: ActionRequest, session: SessionInfo): Promise<FunctionResult>;
+}
+interface ActionTool { name: string; title: string; description: string; inputSchema: JsonObject; outputSchema: JsonObject; annotations: ActionToolAnnotations }
+interface ActionToolAnnotations { title: string; readOnlyHint: boolean; destructiveHint?: boolean; idempotentHint?: boolean; openWorldHint: boolean }
+interface ActionRequest { name: string; input: JsonObject; actor: ActionActor | null }
+interface ActionActor { agent: string; skills: readonly { slug: string; name: string }[]; relations: readonly { type: string; uid: string }[] }
+interface ActionResult { verdict: 'applied' | 'refused'; edits: AppliedEdit[]; findings: ActionFinding[] }
+interface AppliedEdit { edit: string; op: string; uid: string; path: string }
+interface ActionFinding { rule: string; finding: string; path: string; message: string }
+interface FunctionResult { result: Json }
+```
+
+**Remote methods.** `actions.catalog {session}`, `actions.submit {request, session}`,
+`actions.evaluate {request, session}`.
+
+**Example.**
+
+```ts
+ports: {
+  actions: {
+    catalog: async () => [],
+    submit: async (request) => ({
+      verdict: 'refused',
+      edits: [],
+      findings: [{ rule: 'action', finding: 'violation', path: '', message: `No action type ${request.name}.` }],
+    }),
+    evaluate: async (request) => { throw new Error(`No function ${request.name}.`); },
+  },
+},
+```
+
+The checks: each tool has a name, an object `inputSchema` and a boolean
+`readOnlyHint`, and `submit()` of an unknown type answers `refused` with a
+finding and no edit. `orbital plugin new <name> --port actions` writes this
+port.
+
+## `workflows`
+
+**For.** Run workflow files on an engine, such as BPMN or Serverless Workflow.
+
+**When.** The node binds a workflow file to an engine by its suffix. The port
+starts a run, sends it a signal, reads its state and cancels it. The node uses
+the first plugin whose `engines` holds the engine.
+
+**Config.** `workflowBindings:` in `orbital.yaml` binds a file suffix to an
+engine name: `- { engine: <name>, suffix: .bpmn }`. The defaults bind
+`.sw.yaml`, `.sw.json`, `.bpmn` and `.arazzo.yaml`.
+
+**Interface.**
+
+```ts
+interface WorkflowsPort {
+  readonly engines: readonly string[];
+  start(binding: WorkflowStart, input: JsonObject): Promise<WorkflowRun>;
+  signal(runId: string, name: string, payload: Json): Promise<void>;
+  status(runId: string): Promise<WorkflowRun | null>;
+  cancel(runId: string): Promise<WorkflowRun | null>;
+}
+interface WorkflowStart { engine: string; path: string; name: string }
+type WorkflowRunState = 'running' | 'completed' | 'failed' | 'cancelled';
+interface WorkflowRun { runId: string; engine: string; state: WorkflowRunState; output: Json }
+```
+
+**Remote methods.** `workflows.start {binding, input}`,
+`workflows.signal {runId, name, payload}`, `workflows.status {runId}`,
+`workflows.cancel {runId}`.
+
+**Example.**
+
+```ts
+const runs = new Map<string, WorkflowRun>();
+
+ports: {
+  workflows: {
+    engines: ['flow'],
+    start: async (binding, input) => {
+      const run: WorkflowRun = { runId: `flow-${runs.size + 1}`, engine: binding.engine, state: 'completed', output: input };
+      runs.set(run.runId, run);
+      return run;
+    },
+    signal: async () => undefined,
+    status: async (runId) => runs.get(runId) ?? null,
+    cancel: async (runId) => runs.get(runId) ?? null,
+  },
+},
+```
+
+The check: `engines` is a list of names, and `status()` and `cancel()` of an
+unknown run answer null.
+
+## `reasoner`
+
+**For.** Reason over an OWL ontology in Turtle: extract a module, classify,
+align two ontologies, and check consistency.
+
+**When.** A caller of the node's port registry asks the first plugin that
+provides a reasoner. Each answer is three-valued: `true`, `false` or
+`'unknown'`. `unchecked` lists what the reasoner did not check. A method the
+plugin cannot run answers `'unknown'` with an `unsupported` message.
+
+**Config.** None. The node uses the first plugin that provides a reasoner.
+
+**Interface.**
+
+```ts
+interface ReasonerPort {
+  extractModule(request: ExtractModuleRequest): Promise<ExtractModuleAnswer>;
+  classify(request: ClassifyRequest): Promise<ClassifyAnswer>;
+  align(request: AlignRequest): Promise<AlignAnswer>;
+  checkConsistency(request: ConsistencyRequest): Promise<ConsistencyAnswer>;
+}
+interface ReasonerAnswer { answer: true | false | 'unknown'; unchecked: string[]; unsupported?: string }
+interface ExtractModuleRequest { ontology: string; signature: string[]; method: 'star' | 'bot' | 'top' }
+interface ExtractModuleAnswer extends ReasonerAnswer { module: string }
+interface ClassifyRequest { ontology: string }
+interface ClassifyAnswer extends ReasonerAnswer { subclasses: [string, string][] }
+interface AlignRequest { source: string; target: string }
+interface AlignAnswer extends ReasonerAnswer { candidates: Array<{ subject: string; predicate: AlignmentPredicate; object: string; confidence: number }> }
+interface ConsistencyRequest { ontology: string }
+interface ConsistencyAnswer extends ReasonerAnswer { unsatisfiable: string[] }
+```
+
+**Remote methods.** `reasoner.extractModule {request}`, `reasoner.classify {request}`,
+`reasoner.align {request}`, `reasoner.checkConsistency {request}`.
+
+**Example.**
+
+```ts
+const unsupported = { answer: 'unknown' as const, unchecked: [], unsupported: 'This reasoner only checks consistency.' };
+
+ports: {
+  reasoner: {
+    extractModule: async () => ({ ...unsupported, module: '' }),
+    classify: async () => ({ ...unsupported, subclasses: [] }),
+    align: async () => ({ ...unsupported, candidates: [] }),
+    checkConsistency: async ({ ontology }) => ({ answer: true, unchecked: [], unsatisfiable: [] }),
+  },
+},
+```
+
+The check calls each method on a small ontology. See
+`plugins/reasoner-open-ontologies` in the source repository.
+
+## `missions`
+
+**For.** Carry the work on a mission between nodes. One node runs the lead of
+the mission. A person or an agent on another node gives the mission, answers
+its questions, talks to its lead, pauses it or resumes it. This is the port a
+LAN or cross-machine plugin implements.
+
+**When.** The node calls the port only for a mission that it does not hold
+itself. It asks each plugin with the port, in plugin order. The first answer
+that is not null (or true) wins.
+
+- `join(request)`: an attached session on this node joins a mission as its
+  giver (`missionJoin`). `request.giver` is `{ node, sessionId }` of this node.
+- `say(request)`: a person or a session talks to the lead of a mission
+  (`mission say`, `missionSay`). The far node gives the words to the lead: in
+  its running turn, as its next turn, or as the answer to its question. When
+  no plugin answers, the node tries `reply` next.
+- `reply(request)`: a person or a session answers the question of a waiting
+  mission (`mission reply`, `missionReply`).
+- `pause(request)`, `resume(request)`: `mission pause`, `mission resume`.
+- `ask(question)`: the lead of a mission on this node waits with a question,
+  and the giver is a session of another node. Answer true when you carried the
+  question to that node. When no plugin answers true, the node warns.
+
+Answer null (or false) when you do not know the mission or the node. Else
+answer what the far node gave back: a `MissionRecord`, or a `Said` for `say`.
+
+**The far side.** The plugin on the far node takes the request on its own
+transport, then calls the host API of its node:
+
+| Near node calls the port | The plugin on the far node calls |
+|---|---|
+| `join(request)` | `host.joinMission(request)` |
+| `say(request)` | `host.sayMission(request)` |
+| `reply(request)` | `host.replyMission(request)` |
+| `pause(request)` | `host.pauseMission(request)` |
+| `resume(request)` | `host.resumeMission(request)` |
+| `ask(question)` | `host.askGiver(question)` (true when delivered) |
+
+The far node does not relay a request again. To find which node holds a
+mission, read `host.missions()` on each node: it gives the missions of that
+node only. To show the missions of other nodes in the mission list, and for
+claims, also give a `missions` panel (see the recipe).
+
+**Config.** None. The node uses every enabled plugin with the port.
+
+**Interface.**
+
+```ts
+interface MissionRelayPort {
+  join(request: RelayJoin): Promise<MissionRecord | null>;
+  reply(request: RelayReply): Promise<MissionRecord | null>;
+  pause(request: RelayControl): Promise<MissionRecord | null>;
+  resume(request: RelayControl): Promise<MissionRecord | null>;
+  ask(question: MissionQuestion): Promise<boolean>;
+  say(request: RelayMessage): Promise<Said | null>;
+}
+interface RemoteGiver { node: string; sessionId: string }
+interface RelayJoin { missionId: string; giver: RemoteGiver }
+interface RelayReply { missionId: string; text: string; by: string }
+interface RelayControl { missionId: string; by: string }
+interface RelayMessage { missionId: string; text: string; by: string }
+interface Said { sessionId: string; missionId: string | null; delivery: 'reply' | 'steer' | 'turn' }
+interface MissionQuestion { missionId: string; node: string; lead: string | null; leadSessionId: string; question: string; giver: RemoteGiver }
+interface MissionRecord {
+  missionId: string; team: string | null; node: string; file: string | null;
+  state: 'open' | 'active' | 'waiting' | 'paused' | 'done' | 'failed';
+  declared: boolean; givenBy: string | null; brief: string | null; sessionId: string | null; taskId: string | null;
+  source: string | null; result: string | null; question: string | null; giver: string | null; lead: string | null;
+  lastActivity: string | null; claim: string | null; claimedAt: string | null; stale: boolean; updatedAt: string | null;
+  history: Array<{ state: MissionState; at: string; by: string; note: string | null }>;
+}
+```
+
+A mission id is lowercase letters, digits and hyphens, at most 63.
+
+**Remote methods.** `missions.join {request}`, `missions.reply {request}`,
+`missions.pause {request}`, `missions.resume {request}`, `missions.ask {question}`,
+`missions.say {request}`.
+
+**Example.** `peer` is your transport to the same plugin on the other nodes.
+
+```ts
+ports: {
+  missions: {
+    join: async (request) => peer.ask('join', request),
+    reply: async (request) => peer.ask('reply', request),
+    pause: async (request) => peer.ask('pause', request),
+    resume: async (request) => peer.ask('resume', request),
+    ask: async (question) => (await peer.send(question.giver.node, 'ask', question)) === true,
+    say: async (request) => peer.ask('say', request),
+  },
+},
+```
+
+`peer.ask` sends to each known node and answers the first answer, or null.
+The full plugin, with the far side, is the first recipe in
+[recipes.md](recipes.md). No conformance check exists for this port yet, so
+test it with two nodes.
+
+## `commands`
+
+`commands` sits beside `ports`, not in it. A person runs a command with
+`orbital plugin run <plugin> <command> -- <args>`. The node prints the answer.
+
+```ts
+commands: {
+  whoami: {
+    summary: 'Name the account this plugin posts as.',
+    run: async (args) => `bot in ${args[0] ?? 'the default guild'}`,
+  },
+},
+```
+
+**Remote method.** `command.run {name, args}`, answered with `{ output }`.
+
+## `service`
+
+`service` sits beside `ports`, not in it. It is background work while the node
+serves: a socket that listens, a poll, a timer.
+
+```ts
+service: {
+  ends: false,
+  start: async ({ host, signal }) => {
+    const timer = setInterval(() => void poll(host), 5000);
+    signal.addEventListener('abort', () => clearInterval(timer));
+    return { stop: async () => clearInterval(timer) };
+  },
+},
+```
+
+- The node starts the service after every plugin is ready and the node serves,
+  so `host` is ready.
+- With `ends: true`, return `done`, a promise that resolves when the work ends,
+  such as a queue served once. The node stops when every `done` resolves.
+- After a restart of the plugin, the node starts the service again.
+
+**Remote methods.** `service.start`, `service.stop`; the plugin sends
+`service.done {ok, error?}` when `done` settles.