@kaiba-cloud/orbital 0.0.0-stage → 0.0.1

package/skills/orbital-plugin-builder/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: orbital-plugin-builder
+description: Use when building, changing or debugging any orbital plugin or port for the `orbital` CLI (also `atom orbital`) — a channel (Slack, Discord, email), a store or workspace store, a harness, a panel, a policy engine, a telemetry sink or live dashboard (snapshot and events), a directory of agents, placements on other machines, session hooks, hosted tools, actions, workflows, a reasoner, a missions relay for cross-machine or LAN work, a plugin command or a background service — or when a plugin uses the host API, writes orbital-plugin.json or permissions, fails `orbital plugin check`, is refused at start, or must be built, added, tested or published to npm or a marketplace.
+---
+
+# Build an orbital plugin
+
+A plugin gives a node one or more ports. It runs in its own process and speaks
+JSON-RPC on stdio. `@kaiba-cloud/orbital-sdk` does the protocol: you write one
+plain object for each port.
+
+## References
+
+| File | Read it for |
+|---|---|
+| [references/ports.md](references/ports.md) | Each port: what it is for, when the node calls it, the config, the interface, the remote methods, an example. |
+| [references/host-api.md](references/host-api.md) | Each method of the host API: `submit`, `deliver`, `completeModel`, `missions`, `snapshot` and the others. |
+| [references/manifest.md](references/manifest.md) | `orbital-plugin.json`, the `config.yaml` entry, the manifest, permissions, secrets, `context.init`. |
+| [references/recipes.md](references/recipes.md) | Whole plugins: a cross-machine missions relay with a directory and placements, a telemetry dashboard, a Slack channel, a policy engine. |
+
+## Ports
+
+| Port | Key | Use | Section |
+|---|---|---|---|
+| directory | `ports.directory` | agents, skills and blueprints that are not definition files | [directory](references/ports.md#directory) |
+| placements | `ports.placements: { <kind>: Placement }` | run a session on another machine or service | [placements](references/ports.md#placements) |
+| policy | `ports.policy` | allow, deny or ask before an action | [policy](references/ports.md#policy) |
+| telemetry | `ports.telemetry` | usage, spans and node events, for a live dashboard | [telemetry](references/ports.md#telemetry) |
+| sessions | `ports.sessions` | choose where a session runs; add env, commands, egress, prompt text; receive its events | [sessions](references/ports.md#sessions) |
+| tools | `ports.tools` | tools that sessions call on the node | [tools](references/ports.md#tools) |
+| channels | `ports.channels: { <id>: Channel }` | send messages and listen for them | [channels](references/ports.md#channels) |
+| store | `ports.store` | session history and scratchpads off this machine | [store](references/ports.md#store) |
+| workspace | `ports.workspace` | the workspace of a team or an agent off this machine | [workspace](references/ports.md#workspace) |
+| harnesses | `ports.harnesses` | run turns on another agent program | [harnesses](references/ports.md#harnesses) |
+| panels | `ports.panels: { <id>: Panel }` | rows a surface shows, and the `missions` and `peers` panels | [panels](references/ports.md#panels) |
+| actions | `ports.actions` | run the action types of the ontology | [actions](references/ports.md#actions) |
+| workflows | `ports.workflows` | run workflow files on an engine | [workflows](references/ports.md#workflows) |
+| reasoner | `ports.reasoner` | reason over an OWL ontology | [reasoner](references/ports.md#reasoner) |
+| missions | `ports.missions` | join, say, reply, pause, resume and ask on a mission of another node | [missions](references/ports.md#missions) |
+| commands | `commands` (beside `ports`) | `orbital plugin run <plugin> <command>` | [commands](references/ports.md#commands) |
+| service | `service` (beside `ports`) | background work while the node serves | [service](references/ports.md#service) |
+
+## Workflow
+
+### 1. New
+
+```bash
+orbital plugin new <name> --port <port>
+```
+
+`--port` takes `channel`, `store`, `workspace`, `harness`, `panel`, `policy`,
+`telemetry`, `actions`, `workflows` or `command`. For a port with no template
+(`directory`, `placements`, `sessions`, `tools`, `reasoner`, `missions`), start
+with `--port panel`, then replace the ports in `src/plugin.ts`. One plugin can
+give many ports.
+
+The folder:
+
+```
+orbital-plugin.json            how the node starts it: {"name","command":["node","dist/plugin.js"]}
+package.json                the SDK and esbuild, as dev dependencies only
+scripts/build.mjs           src/main.ts to dist/plugin.js, one bundled file
+src/plugin.ts               the plugin: name, version, permissions, ports
+src/main.ts                 servePlugin(plugin)
+test/conformance.test.ts    runConformance on the ports, and the plugin's own checks
+fixtures.json               what some checks need: a binding to send on, a store's settings
+```
+
+Then `npm install`. If npm does not have `@kaiba-cloud/orbital-sdk`, install it
+from the tarball of the orbital release. It is the only package a plugin needs:
+
+```bash
+npm install ./kaiba-cloud-orbital-sdk-<v>.tgz
+```
+
+### 2. Implement
+
+```ts
+import type { PluginContext, PluginImplementation } from '@kaiba-cloud/orbital-sdk';
+
+export function plugin(context: PluginContext): PluginImplementation {
+  return {
+    name: 'discord',
+    version: '0.1.0',
+    permissions: { network: ['discord.com'], secrets: ['discord.token'], models: [] },
+    ports: { /* one key for each port */ },
+  };
+}
+```
+
+- `name` must match `orbital-plugin.json` and the key in `config.yaml`.
+- The SDK builds the manifest from this object. `provides` comes from the ports
+  you give.
+- Validate `context.init.config` at the start. Throw an error that names the
+  bad key.
+- Read secrets with `context.secret(name)` when you need them, not at start.
+- Call the node with `context.host()` inside a method, or with `host` in the
+  service. See [host-api.md](references/host-api.md).
+- Never write to stdout: it is the protocol. Use `context.log(level, message)`.
+  A line on stderr reaches the node's log as a warning.
+
+### 3. Test
+
+```bash
+npm test          # build, then the conformance checks and your own checks
+```
+
+- The conformance checks are the contract of each port. A check that needs a
+  value only you know skips. The skip names the fixture: `channels.<id>`,
+  `store`, `workspace`, `placements.<kind>`, `harness`.
+- The `policy` and `command` templates add one check of their own. When you
+  replace `src/plugin.ts`, replace or delete that check.
+- Test your own logic next to the checks: call the port methods with a fake
+  `PluginContext`, as the template's test does.
+- For a test against a real node, start the plugin with `startRemotePlugin`
+  and a node with `runNode`, as `plugins/channel-slack/__tests__` does in the
+  source repository.
+
+### 4. Check through the real protocol
+
+In a project with a definition (`orbital init`):
+
+```bash
+orbital plugin add ./<name>
+orbital plugin check <name> --fixtures <name>/fixtures.json
+```
+
+`plugin add` prints the permissions, and names a folder in `config.yaml` by its
+path. It does not copy it. Rebuild, and the next start of the node uses the new
+build. `plugin check` starts the built plugin with the config of its
+`config.yaml` entry and the secrets of `orbital plugin secret set`.
+
+### 5. Add to the config
+
+The node's file is `config.yaml` in a definition folder, or
+`.claude/orbital.yaml` in a project where `orbital init` found a `.claude`
+folder. This skill says `config.yaml` for both.
+
+```yaml
+plugins:
+  discord:
+    source: ./plugins/discord
+    config:
+      guild: "1234"
+```
+
+Some ports need a choice too: `directory:`, `placement:`, `policy:`,
+`telemetry:`, `store:`. Each section of [ports.md](references/ports.md) says
+how. Then `orbital node start`.
+
+### 6. Publish
+
+- **npm.** Publish `orbital-plugin.json` and `dist/`. Name the package so that
+  its last part is the plugin's name, such as `@acme/discord`.
+  `orbital plugin add npm:@acme/discord` names the plugin by that part.
+- **A marketplace.** A Git repository with a `marketplace.json`. A person adds
+  it with `orbital plugin marketplace add <git-url>`, then runs
+  `orbital plugin add discord@<marketplace>`.
+
+```json
+{
+  "name": "acme",
+  "plugins": [
+    { "name": "discord", "description": "Discord channels for teams.", "source": "npm:@acme/discord" },
+    { "name": "vault", "description": "A store in Vault.", "source": "./plugins/vault" }
+  ]
+}
+```
+
+A `source` is a folder of the repository, `npm:<package>` or `git:<url>`. A
+folder must hold a built `dist/`. Keep every dependency a dev dependency: the
+bundle holds them.
+
+## How a plugin runs
+
+```mermaid
+sequenceDiagram
+    participant N as node
+    participant P as plugin process
+    N->>P: initialize {config, folder, node}
+    P-->>N: manifest
+    N->>P: host.endpoint {url, token}
+    N->>P: channel.listen, service.start
+    N->>P: port calls: channel.send, policy.decide, missions.join, ...
+    P->>N: host.secret, host.log (stdio)
+    P->>N: host API over HTTP: deliver, submit, snapshot, ...
+    N->>P: shutdown
+```
+
+- The node starts the command in `orbital-plugin.json`, from the plugin's
+  folder. A source `exec:<command> <args>` starts a program on PATH instead.
+- Only the built-in plugins run in the node's process: `orbital` (policy),
+  `local` and `static` (directories), `git` (a channel and a store), `folder` (a store and a workspace store).
+- The node restarts a plugin that stops, with backoff, up to five times. It
+  then calls `channel.listen` and `service.start` again.
+
+## When something fails
+
+Run `orbital plugin check <name>` first. A plugin that the node refuses at
+start stops the start with "A plugin did not start: …".
+
+| Symptom | Cause |
+|---|---|
+| "is X, and config.yaml names it Y" | The manifest `name` differs from the `config.yaml` key. |
+| "exited (code N) before it answered" | It threw at start, or it wrote to stdout. Read the node's log for its stderr. |
+| "did not declare the secret" | Add the name to `permissions.secrets`. |
+| "declares the variables [...] as secrets, and its orbital-plugin.json declares env: [...]" | Make the secrets in variable form and `env` the same. |
+| Refused with `offline: true` | It declares a network host. |
+| "chooses the plugin X, and this host has no plugin of that name" | A port choice in `config.yaml` names a plugin that `plugins:` does not have. |
+| "chooses X for the Y port, and that plugin provides none" | The plugin does not give that port, or the manifest leaves it out. |
+| "No plugin of this node serves the placement" | No plugin has the placement kind in `ports.placements`. |
+| A send check fails with another ref | A second send of a message id must answer the first ref and send nothing. |
+| "ports must be orbital/v1alpha1" | The SDK is older or newer than the node. Build with the SDK of the node's version. |
+| "The node has not given this plugin its endpoint yet." | `context.host()` ran in the factory. Call it inside a method or the service. |
+| `npm test` fails on `hello` or `rm -rf` | The template's own check still tests the template. Replace it. |
+
+## Worked examples
+
+In the source repository of orbital:
+
+- `plugins/channel-slack`: a channel with a Socket Mode service, `host.deliver`, idempotent send, secrets, a panel and a command.
+- `plugins/policy-judge`: a policy that calls a model through `host.completeModel`.
+- `plugins/store-object`: a store in an object store.
+- `plugins/reasoner-open-ontologies`: a reasoner.
+- `packages/orbital/src/core/node/static-directory.ts`: a directory, a `sessions.create` hook and a placement that send `<agent>@<node>` to another node.
+- `packages/orbital/__tests__/core/fixtures/echo-plugin`: session hooks, a directory, a hosted tool, a panel, a service that submits a turn, and a command.
+- `packages/orbital/__tests__/core/fixtures/echo-harness`: a harness and its turn program.

package/skills/orbital-plugin-builder/references/host-api.md

@@ -0,0 +1,226 @@
+# The host API
+
+The host API is the node, as a plugin sees it. The type is `HostApi` from
+`@kaiba-cloud/orbital-sdk`.
+
+## How to get it
+
+- In a service: `start({ host, signal })` gives it.
+- Anywhere else: `context.host()`. It throws until the node gives the plugin
+  its endpoint. The node gives it before the first port call and before the
+  service starts, so call `context.host()` inside a method, never in the
+  factory.
+
+The plugin reaches the node over HTTP, on `127.0.0.1`, with a token that the
+node made for this plugin only. The node knows the caller by that token: a
+`submit` names the plugin as the one that placed the turn, and
+`completeModel` checks the plugin's `permissions.models`.
+
+Each method fails with an error that holds the HTTP status and the node's
+message. Catch it where a failure must not stop the plugin.
+
+## Methods
+
+| Method | Answer | Use |
+|---|---|---|
+| `submit(turn)` | `Task` | Start a turn: a new session, or the next turn of one. |
+| `stopSession(sessionId)` | nothing | Stop a session and its running turn. |
+| `status()` | `HostStatus` | Read how busy the node is. |
+| `settled(orFollowing)` | nothing | Wait until the node has no running work. |
+| `flush()` | nothing | Wait until the node delivers the pending session events to each sink. |
+| `liveSessions()` | `LiveSession[]` | Read the sessions the node runs now. |
+| `catalog()` | `MachineCatalog` | Read the teams, agents and sessions the node offers. |
+| `readLog(sessionId)` | `SessionEvent[]` or null | Read the event log of a session. |
+| `watch(sessionId, listener)` | a stop function | Follow the new events of a session. |
+| `a2a(body)` | the JSON-RPC answer | Call the node's A2A server. |
+| `deliver(inbound)` | `DeliveryAnswer` | Give the node a message that a channel received. |
+| `completeModel(request, signal?)` | `ModelCompletion` | Make one model call on the person's keys. |
+| `startMission(start)` | `MissionStarted` | Start a mission from an event. |
+| `missions()` | `MissionRecord[]` | Read the missions of this node. |
+| `joinMission(request)` | `MissionRecord` | Far side of `missions.join`. |
+| `replyMission(request)` | `MissionRecord` | Far side of `missions.reply`. |
+| `sayMission(request)` | `Said` | Far side of `missions.say`. |
+| `pauseMission(request)` | `MissionRecord` | Far side of `missions.pause`. |
+| `resumeMission(request)` | `MissionRecord` | Far side of `missions.resume`. |
+| `askGiver(question)` | `boolean` | Far side of `missions.ask`. |
+| `snapshot()` | `TelemetrySnapshot` | Read the telemetry graph of the node now. |
+
+### submit
+
+```ts
+interface HostTurn {
+  sessionId?: string;
+  taskId?: string;
+  message: Message;
+  start?: { agent: string; harness?: string; workspaceDir?: string; model?: string | null; parentSessionId?: string | null; team?: string | null; mission?: string | null };
+}
+```
+
+- With `start` and no `sessionId`, the node starts a new session of `agent`.
+  Name a team as the agent to start its lead.
+- With `sessionId`, the node gives the session its next turn.
+- The answer is the A2A `Task`. `task.contextId` is the session id.
+
+```ts
+const task = await host.submit({
+  message: { messageId: randomUUID(), role: 'ROLE_USER', parts: [{ text: 'Triage the new issues.' }] },
+  start: { agent: 'triage' },
+});
+```
+
+### stopSession
+
+`stopSession(sessionId)` stops the session's running turn and its tasks.
+
+### status
+
+```ts
+interface HostStatus { busy: number; idle: boolean; running: string[]; followingRemote: boolean }
+```
+
+`running` lists the sessions with a working task. `followingRemote` is true
+while the node follows a session on another placement.
+
+### settled
+
+`settled(false)` resolves when the node has no running work. `settled(true)`
+also resolves when the only work left is a remote session that the node
+follows. A service with `ends: true` can return `{ done: host.settled(false) }`.
+
+### flush
+
+`flush()` resolves when the node gave each `sessions.deliver` sink the events it has not taken yet.
+
+### liveSessions
+
+```ts
+interface LiveSession {
+  id: string; agent: string; harness: string; parentSessionId: string | null; status: string; isRunning: boolean;
+  team: string | null; mission: string | null; since: string | null; doing: string | null; lastActivityAt: string | null;
+  background: BackgroundTask[];
+}
+```
+
+### catalog
+
+```ts
+interface MachineCatalog { teams: CatalogTeam[]; agents: CatalogAgent[]; sessions: LiveSession[]; started: string[] }
+```
+
+The node gives the same catalog to `directory.announce`.
+
+### readLog and watch
+
+`readLog(sessionId)` answers the events of the session's log, or null when the
+node keeps no log of it. `watch(sessionId, listener)` calls `listener` with each
+new batch of events, and answers a function that stops the watch.
+
+### a2a
+
+`a2a(body)` posts a JSON-RPC body to the node's A2A server and answers the
+JSON answer. It serves `SendMessage`, `GetTask` and `CancelTask`. It does not
+serve a streaming method.
+
+### deliver
+
+```ts
+interface InboundDelivery { channel: string; bindingId: string; envelope: ChannelEnvelope }
+interface DeliveryAnswer { accepted: boolean; duplicate: boolean; sessionId: string | null; reason: string | null }
+```
+
+A channel service calls it for each message it receives. `duplicate: true`
+means that the node had the message id already. `accepted: false` gives the
+`reason`, such as "This host has no channels." The node checks the
+`channel.receive` policy action first.
+
+### completeModel
+
+```ts
+interface ModelRequest { model: string; system?: string; messages: Array<{ role: 'user' | 'assistant'; content: string }>; maxTokens?: number }
+interface ModelCompletion { text: string; model: string; inputTokens: number; outputTokens: number }
+```
+
+- `model` is `<provider>:<model>`, such as `anthropic:claude-haiku-4-5`.
+- `maxTokens` is at most 8192. The default is 1024.
+- The model must match a pattern in `permissions.models`, and the `model.use`
+  policy action decides each call. The key never reaches the plugin.
+- Pass `signal` to stop a long call.
+
+### startMission
+
+```ts
+interface MissionStart { team: string | null; mission: string; input: string | null; source: { event: string; key: string } }
+interface MissionStarted { missionId: string; sessionId: string; taskId: string; duplicate: boolean }
+```
+
+- `mission` is a mission id. The definition must hold `missions/<id>/MISSION.md`,
+  unless the team is not on this node: then the node starts the team as an
+  agent, and a directory or a placement can send it to another node.
+- `source.event` names the event, such as `github.issue.opened`. `source.key`
+  is a stable key of that event, at most 200 characters. A second start with
+  the same key answers `duplicate: true` and starts nothing.
+- The node checks the `mission.start` policy action first, with this plugin as
+  `plugin`.
+
+### missions
+
+`missions()` answers the missions that this node holds, with their state,
+lead, question, giver and history. It never includes the missions of other
+nodes, so a relay can ask each node which missions it holds.
+
+### joinMission, replyMission, sayMission, pauseMission, resumeMission, askGiver
+
+These are the far side of the `missions` port. A relay plugin on the node that
+holds the mission calls them when the same plugin on another node sends it a
+request. See [ports.md](ports.md#missions).
+
+```ts
+interface RelayJoin { missionId: string; giver: { node: string; sessionId: string } }
+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: { node: string; sessionId: string } }
+```
+
+- `joinMission` makes the remote session the giver of the mission. When the
+  mission waits, the node sends the question to the new giver at once.
+- `replyMission` answers a waiting mission. It fails when the mission is
+  paused, or is not waiting.
+- `sayMission` gives the words to the lead of the mission. `delivery` says
+  how: `steer` (in its running turn), `turn` (as its next turn) or `reply` (as
+  the answer to its question). It fails when the mission is paused, or has no
+  lead.
+- `pauseMission` pauses an active or waiting mission. `resumeMission` resumes a
+  paused one.
+- `askGiver` gives the question to the giver session on this node. It answers
+  false when the giver is not an attached session of this node.
+- Each of these acts only on this node. None relays again.
+
+### snapshot
+
+`snapshot()` answers the graph of the node now:
+
+```ts
+interface TelemetrySnapshot {
+  v: 'orbital.telemetry/v1'; node: string; sequence: number; at: string; startedAt: string;
+  teams: Array<{ name: string; node: string; purpose: string | null; lead: string | null; members: Array<{ agent: string; role: 'lead' | 'member'; responsibility: string | null; harness: string | null; placement: string | null; state: 'working' | 'idle'; lastActivityAt: string | null; work: MemberWork[] }> }>;
+  missions: Array<{ missionId: string; team: string | null; state: MissionState; sessionId: string | null; lead: string | null; giver: string | null; givenBy: string | null; question: string | null; result: string | null; updatedAt: string | null }>;
+  sessions: Array<{ sessionId: string; parentSessionId: string | null; agent: string; harness: string; team: string | null; mission: string | null; role: string; placement: string; running: boolean; since: string | null }>;
+  jobs: Array<{ jobId: string; sessionId: string; parentSessionId: string | null; agent: string; harness: string; team: string | null; mission: string | null; since: string }>;
+  tokens: Array<{ team: string | null; mission: string | null; provider: string; model: string; inputTokens: number; outputTokens: number; cacheReadTokens: number; cacheWriteTokens: number; costUsd: number; llmCalls: number; turns: number }>;
+}
+```
+
+`sequence` is the `seq` of the last event in the snapshot. Apply only the
+telemetry events with a higher `seq`. The JSON Schema is in the `schemas` folder
+of `@kaiba-cloud/orbital`.
+
+## Calls from the plugin to the node on stdio
+
+Besides the HTTP host API, the SDK uses two stdio methods for you:
+
+- `context.log(level, message)` sends `host.log`. The node writes it to its log.
+  `level` is `info`, `warn` or `error`.
+- `context.secret(name)` sends `host.secret` and answers the value or null. The
+  node refuses a name that `permissions.secrets` does not declare.

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

@@ -0,0 +1,154 @@
+# The plugin files: orbital-plugin.json, the manifest, permissions, secrets
+
+A plugin has two descriptions:
+
+- `orbital-plugin.json`: a file in the plugin's folder. It tells the node how
+  to start the plugin.
+- The manifest: the answer of the plugin to `initialize`. It tells the node
+  what the plugin provides and what it reaches. With the SDK, `manifestOf`
+  builds it from your plugin object, so you never write it.
+
+## orbital-plugin.json
+
+```json
+{
+  "name": "lan",
+  "command": ["node", "dist/plugin.js"],
+  "dir": ".",
+  "env": ["LAN_SHARED_KEY"],
+  "config": { "port": 7420 }
+}
+```
+
+| Field | Required | Meaning |
+|---|---|---|
+| `name` | yes | The plugin's name: lowercase letters, digits and hyphens, at most 63. |
+| `command` | yes | The program and its arguments. `node` runs with the node's own Node. |
+| `dir` | no | The working folder, relative to the plugin's folder. Default: the plugin's folder. |
+| `env` | no | Environment variables the node passes to the plugin. It must list the same names as the secrets in the manifest that have the form of a variable (`[A-Z][A-Z0-9_]*`). |
+| `config` | no | Default config. The `config` of the `config.yaml` entry overrides it key by key. |
+
+No other field is allowed. A `config.yaml` source `exec:<command> <args>`
+starts a program on PATH with no `orbital-plugin.json`. Only such an entry can
+name `env:` in `config.yaml`.
+
+The node starts the plugin with a small environment: `PATH`, `HOME`, the
+locale, the temp folders, the proxy and certificate variables, and the
+variables in `env`. Any other variable of the node does not reach the plugin.
+
+## The config.yaml entry
+
+```yaml
+plugins:
+  lan:
+    source: ./plugins/lan      # a folder, npm:<package>, git:<url>, <name>@<marketplace>, or exec:<command>
+    enabled: true              # false keeps the entry and does not start the plugin
+    config:                    # context.init.config, merged over the config of orbital-plugin.json
+      port: 7420
+```
+
+`orbital plugin add <source>` writes the entry. A folder source stays where it
+is. Any other source is installed in `<orbital home>/plugins/<name>`.
+
+## The manifest
+
+```ts
+interface PluginManifest {
+  name: string;
+  version: string;
+  ports: 'orbital/v1alpha1';
+  provides: {
+    directory: boolean;
+    placements: Array<{ kind: string; decides: boolean }>;
+    policy: { deterministic: boolean } | null;
+    telemetry: { usage: boolean; span: boolean; event: boolean } | null;
+    sessions: Array<'create' | 'open' | 'close' | 'deliver'>;
+    tools: string[];
+    channels: Array<{ id: string; capabilities: ChannelCapabilities }>;
+    store: { kinds: StateKind[]; lease: boolean } | null;
+    workspace: boolean;
+    harnesses: Array<{ id: string; description: string; callsModel: boolean }>;
+    service: { done: boolean } | null;
+    actions: boolean;
+    workflows: { engines: string[] } | null;
+    reasoner: boolean;
+    missions: boolean;
+  };
+  permissions: { network: string[]; secrets: string[]; models: string[] };
+  commands: Array<{ name: string; summary: string }>;
+  panels: Array<{ id: string; title: string; kind: 'list' | 'tree' | 'transcript' | 'form' }>;
+}
+```
+
+- `name` must be the key of the plugin in `config.yaml`. Else the node refuses
+  it: "is X, and config.yaml names it Y".
+- `ports` must be the version of the node. Build with the SDK of the node's
+  version.
+- The node makes the remote ports only from `provides`. A method that you give
+  and the manifest does not name is never called.
+- A plugin cannot have the name of a definition folder: `agents`,
+  `blueprints`, `local`, `policies`, `skills`, `system`, `teams`, `vendor`,
+  `workflows`.
+
+## Permissions
+
+```ts
+permissions: {
+  network: ['api.example.com', '*.example.net'],
+  secrets: ['example.token', 'EXAMPLE_KEY'],
+  models: ['anthropic:*'],
+},
+```
+
+| Field | Meaning | What the node does |
+|---|---|---|
+| `network` | Every host the plugin reaches, such as `*.example.net`. | `offline: true` in `config.yaml` refuses a plugin with any host. The node does not sandbox the plugin process: the list is a promise that a person and a policy read. |
+| `secrets` | Every secret the plugin reads. | `context.secret(name)` fails for a name not listed. A name in the form of a variable also comes in the environment. |
+| `models` | Every model the plugin calls through `host.completeModel`, as `<provider>:<model>`. `*` matches any part. | A call to a model that no pattern matches fails. The `model.use` policy decides each call. |
+
+- `orbital plugin add` prints the permissions. A person reads them before they
+  use the plugin.
+- When a plugin starts, the node checks the `plugin.load` policy action with
+  `network`, `secrets` and `models`. In this version the node checks it before
+  any policy engine runs, so no policy plugin refuses a plugin yet.
+- Declare a LAN plugin's peers as hosts too, such as `192.168.1.*` or
+  `*.local`. Then a person sees that it talks on the network.
+
+## Secrets
+
+A person keeps a secret on the machine:
+
+```bash
+orbital plugin secret set <plugin> <name>     # reads the value from stdin
+orbital plugin secret remove <plugin> <name>
+```
+
+The plugin reads it when it needs it, not at start:
+
+```ts
+const token = await context.secret('example.token');
+if (!token) throw new Error('No token: run `orbital plugin secret set example example.token`.');
+```
+
+The node keeps secrets in the system's secret store, or in a file of the
+orbital home. A secret never goes in `config.yaml` or in `orbital-plugin.json`.
+
+## The plugin's folder and the init data
+
+`context.init` is what the node gives in `initialize`:
+
+```ts
+interface PluginInit {
+  config: Record<string, unknown>;
+  folder: string | null;
+  node: { name: string; workspaceDir: string; harness: string; harnesses: string[]; once: boolean; idleExitMs: number | null; project: string | null };
+}
+```
+
+- `config`: the merged config. Validate it at the start, and throw an error that
+  names the bad key. The node shows it.
+- `folder`: `<definition folder>/<plugin name>`, such as `.atom/lan/`. Put the
+  files that a person writes for the plugin there. The folder can be absent, so
+  give a default. It is null when the node has no definition folder.
+- `node.name`: the name of this node. A cross-machine plugin uses it to
+  introduce itself to peers.