@kaiba-cloud/orbital 0.0.1 → 0.0.3

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.3",
   "license": "UNLICENSED",
   "type": "module",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/ai-kaiba/atom.git",
-    "directory": "packages/orbital"
-  },
   "engines": {
     "node": ">=22.18"
   },
@@ -16,14 +11,22 @@
     "orbital": "dist/orbital.js"
   },
   "exports": {
-    ".": "./dist/index.js",
-    "./package.json": "./package.json"
+    ".": "./src/index.ts",
+    "./protocol": "./src/protocol/index.ts",
+    "./sdk": "./src/sdk/index.ts",
+    "./tui": "./src/tui/index.tsx",
+    "./*": "./src/*.ts"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "check-types": "tsc -p tsconfig.json",
+    "schemas": "node scripts/schemas.ts",
+    "test": "vitest run"
   },
   "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",
@@ -44,12 +47,10 @@
     "schemas"
   ],
   "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "build": "node scripts/build.mjs",
-    "check-types": "tsc -p tsconfig.json",
-    "schemas": "node scripts/schemas.ts",
-    "test": "vitest run"
+    "access": "public",
+    "exports": {
+      ".": "./dist/index.js",
+      "./package.json": "./package.json"
+    }
   }
-}
+}

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.