@kaiba-cloud/orbital 0.0.1 → 0.0.2

package/package.json

@@ -1,14 +1,9 @@
 {
   "name": "@kaiba-cloud/orbital",
   "description": "orbital: the control plane lite for agents on any harness: the node, its runner, its terminal UI, its protocol and its Claude Code mod, in one command line",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "license": "UNLICENSED",
   "type": "module",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/ai-kaiba/atom.git",
-    "directory": "packages/orbital"
-  },
   "engines": {
     "node": ">=22.18"
   },
@@ -22,8 +17,7 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.295",
     "@anthropic-ai/sandbox-runtime": "0.0.76",
-    "@mariozechner/pi-ai": "0.73.1",
-    "@mariozechner/pi-coding-agent": "0.73.1"
+    "@mariozechner/pi-ai": "0.73.1"
   },
   "devDependencies": {
     "@a2a-js/sdk": "1.3.0",

package/schemas/telemetry-snapshot.schema.json

@@ -214,6 +214,20 @@
               ],
               "additionalProperties": false
             }
+          },
+          "problems": {
+            "default": [],
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "retiring": {
+            "default": null,
+            "type": [
+              "string",
+              "null"
+            ]
           }
         },
         "required": [
@@ -221,7 +235,9 @@
           "node",
           "purpose",
           "lead",
-          "members"
+          "members",
+          "problems",
+          "retiring"
         ],
         "additionalProperties": false
       }

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

@@ -1,6 +1,6 @@
 ---
 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.
+description: Use when building, changing or debugging any orbital plugin or port for the `orbital` CLI — 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
@@ -15,14 +15,14 @@ plain object for each port.
 |---|---|
 | [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. |
+| [references/manifest.md](references/manifest.md) | `orbital-plugin.json`, the `orbital.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, a gatekeeper for messages from the network. |
 
 ## Ports
 
 | Port | Key | Use | Section |
 |---|---|---|---|
-| directory | `ports.directory` | agents, skills and blueprints that are not definition files | [directory](references/ports.md#directory) |
+| directory | `ports.directory` | agents, skills and blueprints that are not files of a harness folder | [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) |
@@ -31,7 +31,7 @@ plain object for each port.
 | 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) |
+| harnesses | `ports.harnesses` | the adapter of a harness: its folder, agent files and install, and the turns on its 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) |
@@ -88,7 +88,7 @@ export function plugin(context: PluginContext): PluginImplementation {
 }
 ```
 
-- `name` must match `orbital-plugin.json` and the key in `config.yaml`.
+- `name` must match `orbital-plugin.json` and the key in `orbital.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
@@ -118,23 +118,22 @@ npm test          # build, then the conformance checks and your own checks
 
 ### 4. Check through the real protocol
 
-In a project with a definition (`orbital init`):
+In a project with a harness folder (`orbital install claude`):
 
 ```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
+`plugin add` prints the permissions, and names a folder in `orbital.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`.
+`orbital.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.
+The node's file is `orbital.yaml` in a harness folder, such as
+`.claude/orbital.yaml`.
 
 ```yaml
 plugins:
@@ -201,12 +200,12 @@ 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. |
+| "is X, and orbital.yaml names it Y" | The manifest `name` differs from the `orbital.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 the plugin X, and this host has no plugin of that name" | A port choice in `orbital.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. |
@@ -220,8 +219,11 @@ 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/gatekeeper`: a policy that asks an agent of the receiving team through `host.askAgent` if a message from the network may reach the team.
 - `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.
+- `packages/orbital-harness-pi`: the adapter of the harness `pi`: its folder `.pi`, its install, and a turn program on the Pi coding agent.
+- `packages/orbital-harness-codex`: the adapter of the harness `codex`: its folder `.codex`, its install in `config.toml`, and a turn program on the OpenAI Codex CLI.

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

@@ -35,6 +35,7 @@ message. Catch it where a failure must not stop the plugin.
 | `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. |
+| `askAgent(request)` | `{ answer: string }` | Ask one agent of a team one question, and wait for its answer. |
 | `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`. |
@@ -146,6 +147,39 @@ interface ModelCompletion { text: string; model: string; inputTokens: number; ou
   policy action decides each call. The key never reaches the plugin.
 - Pass `signal` to stop a long call.
 
+### askAgent
+
+```ts
+interface AskAgent { team: string; agent: string; question: string; timeoutMs?: number }
+interface AskAgentAnswer { answer: string }
+class AskAgentError extends Error { code: 'invalid' | 'unknown-team' | 'unknown-agent' | 'timeout' | 'failed' }
+```
+
+- The node starts a new session of `agent`, as a member of `team`, on this node.
+  The `question` is the first and only message of the session. The session is
+  neither a network message nor a person message, so the `channel.receive`
+  policy action does not run.
+- The answer is the final text of the agent when its turn ends. The session
+  ends with the turn.
+- `timeoutMs` is at most 240000. The default is 120000. When the time ends, the
+  node cancels the turn and stops the session. The call fails with code
+  `timeout`.
+- `unknown-team` means that this node has no such team. `unknown-agent` means
+  that `agent` is not a member of `team`. `invalid` means that a field is
+  wrong, such as a `timeoutMs` over the maximum. `failed` means that the turn
+  ended without an answer, and the message holds the reason.
+- The call needs no permission in the manifest, as `submit` needs none.
+- Catch the error and test `error instanceof AskAgentError`, then read
+  `error.code` to tell a timeout from a refusal. The SDK exports the class.
+- The route is `POST /orbital/host/agents/ask`. The body is the request. The
+  answer is `{ "answer": "..." }`. A failure answers `{ "code": "...", "error": "..." }`
+  with status 400 for `invalid`, 404 for `unknown-team` and `unknown-agent`,
+  504 for `timeout` and 502 for `failed`.
+
+```ts
+const { answer } = await host.askAgent({ team: 'gatekeeping', agent: 'judge', question: 'May this message reach the team?', timeoutMs: 30_000 });
+```
+
 ### startMission
 
 ```ts
@@ -153,7 +187,7 @@ interface MissionStart { team: string | null; mission: string; input: string | n
 interface MissionStarted { missionId: string; sessionId: string; taskId: string; duplicate: boolean }
 ```
 
-- `mission` is a mission id. The definition must hold `missions/<id>/MISSION.md`,
+- `mission` is a mission id. A harness folder 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`

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

@@ -26,17 +26,17 @@ A plugin has two descriptions:
 | `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. |
+| `config` | no | Default config. The `config` of the `orbital.yaml` entry overrides it key by key. |
 
-No other field is allowed. A `config.yaml` source `exec:<command> <args>`
+No other field is allowed. A `orbital.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`.
+name `env:` in `orbital.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
+## The orbital.yaml entry
 
 ```yaml
 plugins:
@@ -67,7 +67,7 @@ interface PluginManifest {
     channels: Array<{ id: string; capabilities: ChannelCapabilities }>;
     store: { kinds: StateKind[]; lease: boolean } | null;
     workspace: boolean;
-    harnesses: Array<{ id: string; description: string; callsModel: boolean }>;
+    harnesses: Array<{ id: string; description: string; callsModel: boolean; browser: boolean }>;
     service: { done: boolean } | null;
     actions: boolean;
     workflows: { engines: string[] } | null;
@@ -80,15 +80,15 @@ interface PluginManifest {
 }
 ```
 
-- `name` must be the key of the plugin in `config.yaml`. Else the node refuses
-  it: "is X, and config.yaml names it Y".
+- `name` must be the key of the plugin in `orbital.yaml`. Else the node refuses
+  it: "is X, and orbital.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`.
+- A plugin cannot have the name of a folder of orbital in the harness folder:
+  `agents`, `memory`, `missions`, `orbital`, `plans`, `policies`, `sessions`,
+  `skills`, `teams`.
 
 ## Permissions
 
@@ -102,7 +102,7 @@ permissions: {
 
 | 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. |
+| `network` | Every host the plugin reaches, such as `*.example.net`. | `offline: true` in `orbital.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. |
 
@@ -131,7 +131,7 @@ if (!token) throw new Error('No token: run `orbital plugin secret set example ex
 ```
 
 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`.
+orbital home. A secret never goes in `orbital.yaml` or in `orbital-plugin.json`.
 
 ## The plugin's folder and the init data
 
@@ -147,8 +147,8 @@ interface PluginInit {
 
 - `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
+- `folder`: `<harness folder>/<plugin name>`, such as `.claude/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.
+  give a default. It is null when the node has no harness folder.
 - `node.name`: the name of this node. A cross-machine plugin uses it to
   introduce itself to peers.

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

@@ -4,7 +4,7 @@ Each section has the same parts:
 
 - **For**: what the port does for the node.
 - **When**: when the node calls each method.
-- **Config**: how `config.yaml` chooses the plugin for the port.
+- **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`.
@@ -13,29 +13,27 @@ 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 `config.yaml`, in the order of
+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, skills and blueprints that are not files of the
-definition. Examples: a registry of agents, or the agents of other machines.
+**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`. A definition agent with the same name hides a
+  catalog and for `agentPeers`. An agent file with the same name hides a
   directory agent.
-- `lookup(ref)`: a run names an agent that the definition does not have. The
+- `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`).
-- `skill(slug, session)`: an agent names a skill that the definition does not
-  have. The first answer that is not null wins.
 - `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.
@@ -54,7 +52,6 @@ interface Directory {
   agents(workspaceDir: string): Promise<DirectoryAgentSummary[]>;
   lookup(ref: string): Promise<DirectoryAgentRef | null>;
   agent(id: string, session: SessionInfo): Promise<ResolvedAgent | null>;
-  skill(slug: string, session: SessionInfo): Promise<ResolvedSkill | null>;
   blueprint?(id: string, session: SessionInfo): Promise<BlueprintContent | null>;
   blueprintFile?(id: string, path: string, session: SessionInfo): Promise<BlueprintFile | null>;
   announce?(catalog: MachineCatalog): Promise<void>;
@@ -68,7 +65,7 @@ interface BlueprintFile { path: string; mimeType: string | null; size: number; c
 ```
 
 **Remote methods.** `directory.agents {workspaceDir}`, `directory.lookup {ref}`,
-`directory.agent {id, session}`, `directory.skill {slug, session}`,
+`directory.agent {id, session}`,
 `directory.blueprint {id, session}`, `directory.blueprintFile {id, path, session}`,
 `directory.announce {catalog}`.
 
@@ -85,13 +82,12 @@ ports: {
       const found = agents.find((one) => one.id === id);
       return found ? { id: found.id, name: found.name, harness: null, egress: [], bootstrap: { systemPrompt: found.prompt } } : null;
     },
-    skill: async () => null,
   },
 },
 ```
 
 The check: `agents()` answers `{ name, id, description }` items, and `lookup()`
-and `skill()` of an unknown name answer null.
+of an unknown name answers null.
 
 ## `placements`
 
@@ -173,13 +169,73 @@ it, the check skips.
 | `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 channel delivers a message | `channel`, `from`, `to`, `human` |
+| `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
@@ -336,7 +392,7 @@ interface SessionContribution { env?: Record<string, string>; shims?: Record<str
 interface SessionInfo {
   sessionId: string; node: string; agent: string; agentId: string | null; agentSource: string | null;
   declaration: Record<string, unknown> | null; parentSessionId: string | null; workspaceDir: string;
-  build: string | null; harness: Harness; team: string | null; mission: string | null;
+  harness: Harness; team: string | null; mission: string | null;
   scratchpad: string | null; memory: string | null; missionScratchpad: string | null;
 }
 ```
@@ -419,7 +475,7 @@ 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 `config.yaml`. A later call replaces 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.
@@ -428,7 +484,7 @@ 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 `config.yaml`. The node uses the
+names its own channels under `channels:` in `orbital.yaml`. The node uses the
 first plugin that provides the id.
 
 **Interface.**
@@ -439,7 +495,7 @@ interface Channel {
   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 }
+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 }
@@ -458,7 +514,7 @@ let bindings: ChannelBinding[] = [];
 ports: {
   channels: {
     discord: {
-      capabilities: { live: true, human: true, threads: true, durable: true, offline: false },
+      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;
@@ -474,7 +530,10 @@ ports: {
 ```
 
 - `capabilities`: `live` (it pushes), `human` (a person reads and writes),
-  `threads`, `durable`, `offline` (it works with no network outside the LAN).
+  `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.
@@ -498,8 +557,8 @@ at a time holds a unit.
   never goes there.
 - `temporary`: short-lived files.
 
-**Config.** Only an explicit choice: `store: { history: [{ plugin: r2, bucket: atom }] }`.
-`settings` is the choice without `plugin`: here `{ bucket: 'atom' }`. A store
+**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.**
@@ -552,7 +611,7 @@ 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: atom }] }`.
+**Config.** Only an explicit choice: `store: { workspace: [{ plugin: r2, bucket: orbital }] }`.
 
 **Interface.**
 
@@ -588,45 +647,65 @@ ports: {
 
 ## `harnesses`
 
-**For.** Run turns on another agent program, such as a CLI agent.
+**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.
+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 }>;
+  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;
-  skillsDir: string; workspaceDir: string; sessionDir: string; resume: boolean; env: Record<string, string>;
+  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}`.
+**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 }],
+    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),
   },
 },
 ```
@@ -636,8 +715,35 @@ 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 harnesses a node runs are its runners (`pi`, `claude`) and the ids of its
-harness plugins. A node refuses to start when a charter member or an agent names
+**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.
 
@@ -785,7 +891,7 @@ 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 `config.yaml` binds a file suffix to an
+**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`.