@kaiba-cloud/orbital 0.0.4 → 0.0.6

package/dist/runner.js

@@ -61666,7 +61666,7 @@ var MissionStateFileSchema = external_exports.object({
   source: external_exports.string().nullable(),
   result: external_exports.string().nullable(),
   question: external_exports.string().nullable(),
-  giver: external_exports.string().nullable(),
+  receivers: external_exports.array(external_exports.string().min(1)).default([]),
   lead: external_exports.string().nullable(),
   claim: external_exports.string().nullable(),
   claimedAt: external_exports.string().nullable(),
@@ -61693,7 +61693,7 @@ var MissionRecordSchema = external_exports.object({
   result: external_exports.string().nullable(),
   question: external_exports.string().nullable(),
   questions: external_exports.array(MissionAskedSchema).default([]),
-  giver: external_exports.string().nullable(),
+  receivers: external_exports.array(external_exports.string().min(1)).default([]),
   lead: external_exports.string().nullable(),
   lastActivity: external_exports.string().nullable().default(null),
   claim: external_exports.string().nullable().default(null),
@@ -61735,9 +61735,9 @@ var MissionReplySchema = external_exports.object({
   text: external_exports.string().min(1),
   questionId: external_exports.string().min(1).optional()
 });
-var RemoteGiverSchema = external_exports.object({ node: external_exports.string().min(1), sessionId: external_exports.string().min(1) });
+var RemoteReceiverSchema = external_exports.object({ node: external_exports.string().min(1), sessionId: external_exports.string().min(1) });
 var SENDER_FIELDS = { team: external_exports.string().min(1).nullable().default(null), agent: external_exports.string().min(1).nullable().default(null) };
-var RelayJoinSchema = external_exports.object({ missionId: MissionIdSchema, giver: RemoteGiverSchema, ...SENDER_FIELDS });
+var RelayJoinSchema = external_exports.object({ missionId: MissionIdSchema, receiver: RemoteReceiverSchema, ...SENDER_FIELDS });
 var RelayReplySchema = external_exports.object({ missionId: MissionIdSchema, text: external_exports.string().min(1), questionId: external_exports.string().min(1).optional(), by: external_exports.string().min(1), ...SENDER_FIELDS });
 var MissionControlSchema = external_exports.object({ missionId: MissionIdSchema });
 var SayRequestSchema = external_exports.object({
@@ -61758,11 +61758,12 @@ var MissionQuestionSchema = external_exports.object({
   leadSessionId: external_exports.string().min(1),
   question: external_exports.string(),
   questionId: external_exports.string().min(1).optional(),
-  giver: RemoteGiverSchema,
+  receiver: RemoteReceiverSchema,
   team: external_exports.string().min(1).nullable().default(null)
 });
 var MissionJoinSchema = external_exports.object({
-  missionId: MissionIdSchema
+  missionId: MissionIdSchema,
+  externalId: external_exports.string().min(1).optional()
 });
 
 // src/protocol/charter.ts
@@ -61836,7 +61837,7 @@ var MissionStateEventSchema = external_exports.object({
   transition: MissionTransitionSchema,
   reason: external_exports.string().nullable(),
   by: external_exports.string(),
-  giver: external_exports.string().nullable(),
+  receivers: external_exports.array(external_exports.string()).default([]),
   sessionId: external_exports.string().nullable(),
   lead: external_exports.string().nullable(),
   question: external_exports.string().nullable(),
@@ -61890,7 +61891,7 @@ var TelemetrySnapshotSchema = external_exports.object({
     state: MissionStateSchema,
     sessionId: external_exports.string().nullable(),
     lead: external_exports.string().nullable(),
-    giver: external_exports.string().nullable(),
+    receivers: external_exports.array(external_exports.string()).default([]),
     givenBy: external_exports.string().nullable(),
     question: external_exports.string().nullable(),
     questions: external_exports.array(MissionAskedSchema).default([]),
@@ -62281,6 +62282,9 @@ var NodeClient = class {
   async joinMission(missionId) {
     return MissionRecordSchema.parse(await this.request("/orbital/missions/join", { method: "POST", body: { missionId } }));
   }
+  async leaveMission(missionId) {
+    return MissionRecordSchema.parse(await this.request("/orbital/missions/leave", { method: "POST", body: { missionId } }));
+  }
   async handoff(handoff2) {
     return MissionRecordSchema.parse(await this.request("/orbital/missions/handoff", { method: "POST", body: handoff2 }));
   }
@@ -62517,6 +62521,13 @@ var DeliverySchema = external_exports.object({
   question: external_exports.string().nullable().default(null),
   text: external_exports.string()
 });
+var AnsweredSchema = external_exports.object({
+  kind: external_exports.literal("answered"),
+  mission: external_exports.string().min(1),
+  question: external_exports.string().nullable(),
+  by: external_exports.string().min(1),
+  text: external_exports.string()
+});
 var SettleSchema = external_exports.object({
   taskId: external_exports.string().min(1).optional(),
   text: external_exports.string()
@@ -62668,6 +62679,60 @@ var LeaseSchema = external_exports.object({ holder: external_exports.string(), e
 
 // src/protocol/plugin-protocol.ts
 var PORTS_VERSION = "orbital/v1alpha1";
+var PLUGIN_COMMAND_RESERVED_OPTIONS = ["output", "quiet", "non-interactive", "confirm", "timeout", "help", "version", "workspace", "node"];
+var PluginCommandOptionSchema = external_exports.object({
+  name: external_exports.string().regex(NAME_SHAPE).refine((name) => !PLUGIN_COMMAND_RESERVED_OPTIONS.includes(name), { error: `an option cannot take a name orbital gives every command: ${PLUGIN_COMMAND_RESERVED_OPTIONS.join(", ")}` }),
+  type: external_exports.enum(["string", "boolean", "integer", "enum", "path"]),
+  summary: external_exports.string().min(1),
+  values: external_exports.array(external_exports.string().min(1)).min(1).optional(),
+  required: external_exports.boolean().default(false),
+  default: external_exports.union([external_exports.string(), external_exports.number().int(), external_exports.boolean()]).optional()
+}).strict().superRefine((option, issues) => {
+  if (option.type === "enum" !== (option.values !== void 0)) issues.addIssue({ code: "custom", message: `the option ${option.name} names values only when its type is enum` });
+  if (option.type === "boolean" && option.required) issues.addIssue({ code: "custom", message: `the boolean option ${option.name} cannot be required` });
+  if (option.default === void 0) return;
+  const fits = option.type === "boolean" ? typeof option.default === "boolean" : option.type === "integer" ? typeof option.default === "number" : typeof option.default === "string" && (option.values?.includes(option.default) ?? true);
+  if (!fits) issues.addIssue({ code: "custom", message: `the default of the option ${option.name} is not a ${option.type === "enum" ? `value of ${option.values.join(", ")}` : option.type}` });
+});
+var PluginCommandArgSchema = external_exports.object({
+  name: external_exports.string().regex(NAME_SHAPE),
+  summary: external_exports.string().min(1),
+  required: external_exports.boolean().default(false),
+  variadic: external_exports.boolean().default(false)
+}).strict();
+var PluginCommandSchema = external_exports.object({
+  name: external_exports.string().regex(NAME_SHAPE),
+  summary: external_exports.string().min(1),
+  args: external_exports.array(PluginCommandArgSchema).default([]),
+  options: external_exports.array(PluginCommandOptionSchema).default([]),
+  interactive: external_exports.boolean().default(false),
+  node: external_exports.boolean().default(false)
+}).strict().superRefine((command, issues) => {
+  const twice = (names) => names.find((name, index) => names.indexOf(name) !== index);
+  const arg = twice(command.args.map((one) => one.name));
+  if (arg) issues.addIssue({ code: "custom", message: `the command ${command.name} names the argument ${arg} twice` });
+  const option = twice(command.options.map((one) => one.name));
+  if (option) issues.addIssue({ code: "custom", message: `the command ${command.name} names the option ${option} twice` });
+  if (command.args.slice(0, -1).some((one) => one.variadic)) issues.addIssue({ code: "custom", message: `only the last argument of the command ${command.name} can be variadic` });
+  if (command.args.some((one, index) => one.required && command.args.slice(0, index).some((before) => !before.required))) issues.addIssue({ code: "custom", message: `a required argument of the command ${command.name} cannot come after an optional one` });
+  if (command.interactive && command.node) issues.addIssue({ code: "custom", message: `the command ${command.name} cannot be interactive and need the node: the node has no terminal to give it` });
+});
+var PluginCommandsSchema = external_exports.array(PluginCommandSchema).default([]).superRefine((commands, issues) => {
+  const names = commands.map((one) => one.name);
+  const twice = names.find((name, index) => names.indexOf(name) !== index);
+  if (twice) issues.addIssue({ code: "custom", message: `the command ${twice} is declared twice` });
+});
+var PluginCommandRequestSchema = external_exports.object({
+  name: external_exports.string().regex(NAME_SHAPE),
+  args: external_exports.record(external_exports.string(), external_exports.union([external_exports.string(), external_exports.array(external_exports.string())])).default({}),
+  options: external_exports.record(external_exports.string(), external_exports.union([external_exports.string(), external_exports.number(), external_exports.boolean()])).default({}),
+  terminal: external_exports.object({ tty: external_exports.boolean() }).nullable().default(null)
+}).strict();
+var PluginCommandResultSchema = external_exports.object({
+  exitCode: external_exports.union([external_exports.literal(0), external_exports.literal(1), external_exports.literal(2), external_exports.literal(3), external_exports.literal(5)]).default(0),
+  text: external_exports.string().nullable().default(null),
+  data: external_exports.record(external_exports.string(), external_exports.unknown()).default({})
+}).strict();
 var PluginManifestSchema = external_exports.object({
   name: external_exports.string().regex(NAME_SHAPE),
   version: external_exports.string().min(1),
@@ -62697,7 +62762,7 @@ var PluginManifestSchema = external_exports.object({
     secrets: external_exports.array(external_exports.string().min(1)).default([]),
     models: external_exports.array(external_exports.string().regex(/^[a-z0-9-]+:.+$/, "a model pattern is <provider>:<model>, such as anthropic:*")).default([])
   }).prefault({}),
-  commands: external_exports.array(external_exports.object({ name: external_exports.string().regex(NAME_SHAPE), summary: external_exports.string() })).default([]),
+  commands: PluginCommandsSchema,
   panels: external_exports.array(external_exports.object({ id: external_exports.string().min(1), title: external_exports.string(), kind: external_exports.enum(["list", "tree", "transcript", "form"]) })).default([])
 }).strict();
 var PluginInitSchema = external_exports.object({
@@ -62720,7 +62785,8 @@ var PluginPackageSchema = external_exports.object({
   dir: external_exports.string().min(1).optional(),
   env: external_exports.array(external_exports.string().regex(PLUGIN_ENV_NAME, "is not the name of an environment variable")).default([]),
   config: external_exports.record(external_exports.string(), external_exports.unknown()).default({}),
-  harnesses: external_exports.array(HarnessAdapterDeclarationSchema).default([])
+  harnesses: external_exports.array(HarnessAdapterDeclarationSchema).default([]),
+  commands: PluginCommandsSchema
 }).strict();
 var MarketplaceSchema = external_exports.object({
   name: external_exports.string().regex(NAME_SHAPE),
@@ -81712,14 +81778,14 @@ function buildMissionLinkTool(messaging, options) {
   };
 }
 var MissionAskParams = Type.Object({
-  question: Type.String({ minLength: 1, description: "The question, in full, with the options you see and what each one means: the giver has none of your context." })
+  question: Type.String({ minLength: 1, description: "The question, in full, with the options you see and what each one means: the receivers have none of your context." })
 });
 function buildMissionAskTool(messaging, options) {
   return {
     name: "missionAsk",
     label: "Ask Mission Giver",
-    description: "Ask the giver of the mission of your session a question, as its lead, at any moment, also while your workers run. The node keeps each question open with the mission until the giver answers it, shows it to the person as waiting on them, and pushes it to the giver at once. The answer comes back to you as a message that names the question. Use it for every decision you need from the giver: a question only in your reply text reaches no one. Keep working on what does not depend on the answer.",
-    promptSnippet: "missionAsk: ask the giver of your mission a question at any moment, also while your workers run",
+    description: "Ask the decision receivers of the mission of your session a question, as its lead, at any moment, also while your workers run. The node keeps each question open with the mission until a receiver answers it, shows it to the person as waiting on them, and pushes it at once to every live receiver. The answer comes back to you as a message that names the question. Use it for every decision you need: a question only in your reply text reaches no one. Keep working on what does not depend on the answer.",
+    promptSnippet: "missionAsk: ask the decision receivers of your mission a question at any moment, also while your workers run",
     parameters: MissionAskParams,
     executionMode: "sequential",
     async execute(_toolCallId, params) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.4",
+  "version": "0.0.6",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {
@@ -11,17 +11,16 @@
     "orbital": "dist/orbital.js"
   },
   "exports": {
-    ".": "./src/index.ts",
-    "./protocol": "./src/protocol/index.ts",
-    "./sdk": "./src/sdk/index.ts",
-    "./tui": "./src/tui/index.tsx",
-    "./*": "./src/*.ts"
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
   },
   "scripts": {
     "build": "node scripts/build.mjs",
     "check-types": "tsc -p tsconfig.json",
     "schemas": "node scripts/schemas.ts",
-    "test": "vitest run"
+    "test": "vitest run",
+    "prepack": "node ../../scripts/pack-manifest.mjs prepack",
+    "postpack": "node ../../scripts/pack-manifest.mjs postpack"
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.295",

package/schemas/telemetry-event.schema.json

@@ -566,11 +566,12 @@
         "by": {
           "type": "string"
         },
-        "giver": {
-          "type": [
-            "string",
-            "null"
-          ]
+        "receivers": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
         },
         "sessionId": {
           "type": [
@@ -611,7 +612,7 @@
         "transition",
         "reason",
         "by",
-        "giver",
+        "receivers",
         "sessionId",
         "lead",
         "question",

package/schemas/telemetry-snapshot.schema.json

@@ -279,11 +279,12 @@
               "null"
             ]
           },
-          "giver": {
-            "type": [
-              "string",
-              "null"
-            ]
+          "receivers": {
+            "default": [],
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
           },
           "givenBy": {
             "type": [
@@ -342,7 +343,7 @@
           "state",
           "sessionId",
           "lead",
-          "giver",
+          "receivers",
           "givenBy",
           "question",
           "questions",

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

@@ -37,7 +37,7 @@ plain object for each port.
 | 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) |
+| commands | `commands` (beside `ports`), and `commands` in `orbital-plugin.json` | `orbital <plugin> <command>`, such as a login | [commands](references/ports.md#commands) |
 | service | `service` (beside `ports`) | background work while the node serves | [service](references/ports.md#service) |
 
 ## Workflow
@@ -126,7 +126,10 @@ orbital plugin check <name> --fixtures <name>/fixtures.json
 
 `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
+build. A plugin that checks its config when it starts gets it at the add:
+`orbital plugin add ./<name> --config channel=general`, or `--config-file <file>`.
+The add starts the plugin with that config, and writes it to `orbital.yaml` only
+when the plugin starts. `plugin check` starts the built plugin with the config of its
 `orbital.yaml` entry and the secrets of `orbital plugin secret set`.
 
 ### 5. Add to the config
@@ -148,9 +151,9 @@ 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.
+- **npm.** Publish `orbital-plugin.json` and `dist/`. The package can have any
+  name: `orbital plugin add npm:@acme/orbital-discord` names the plugin by the
+  `name` of its `orbital-plugin.json`, such as `discord`.
 - **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>`.

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

@@ -43,7 +43,7 @@ message. Catch it where a failure must not stop the plugin.
 | `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`. |
+| `askReceiver(question)` | `boolean` | Far side of `missions.ask`. |
 | `snapshot()` | `TelemetrySnapshot` | Read the telemetry graph of the node now. |
 
 ### submit
@@ -199,26 +199,26 @@ interface MissionStarted { missionId: string; sessionId: string; taskId: string;
 ### missions
 
 `missions()` answers the missions that this node holds, with their state,
-lead, question, giver and history. It never includes the missions of other
+lead, question, decision receivers 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
+### joinMission, replyMission, sayMission, pauseMission, resumeMission, askReceiver
 
 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 }; team: string | null; agent: string | null }
+interface RelayJoin { missionId: string; receiver: { node: string; sessionId: string }; team: string | null; agent: string | null }
 interface RelayReply { missionId: string; text: string; by: string; team: string | null; agent: string | null }
 interface RelayControl { missionId: string; by: string; team: string | null; agent: string | null }
 interface RelayMessage { missionId: string; text: string; by: string; team: string | null; agent: string | null }
 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 }; team: string | null }
+interface MissionQuestion { missionId: string; node: string; lead: string | null; leadSessionId: string; question: string; receiver: { node: string; sessionId: string }; team: string | null }
 ```
 
-- `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.
+- `joinMission` adds the remote session to the decision receivers of the
+  mission. The node sends each open question to the new receiver 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
@@ -227,8 +227,8 @@ interface MissionQuestion { missionId: string; node: string; lead: string | null
   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.
+- `askReceiver` gives the question to the receiver session on this node. It
+  answers false when the receiver is not a live session of this node.
 - `team` and `agent` name the team and the agent of the session that sent the
   request, or are null. In a question, `team` is the team of the mission and
   `lead` is the agent. The node gives them to the `channel.receive` policy
@@ -243,7 +243,7 @@ interface MissionQuestion { missionId: string; node: string; lead: string | null
 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 }>;
+  missions: Array<{ missionId: string; team: string | null; state: MissionState; sessionId: string | null; lead: string | null; receivers: string[]; 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 }>;

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

@@ -16,7 +16,8 @@ A plugin has two descriptions:
   "command": ["node", "dist/plugin.js"],
   "dir": ".",
   "env": ["LAN_SHARED_KEY"],
-  "config": { "port": 7420 }
+  "config": { "port": 7420 },
+  "commands": [{ "name": "status", "summary": "Show the peers." }]
 }
 ```
 
@@ -27,6 +28,7 @@ A plugin has two descriptions:
 | `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 `orbital.yaml` entry overrides it key by key. |
+| `commands` | no | The CLI commands of the plugin, the same as its `commands` in code. See [commands](ports.md#commands). |
 
 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
@@ -49,6 +51,9 @@ plugins:
 
 `orbital plugin add <source>` writes the entry. A folder source stays where it
 is. Any other source is installed in `<orbital home>/plugins/<name>`.
+`--config key=value` (repeatable) and `--config-file <file>` give the config:
+the add starts the plugin with it, and writes the entry only when the start
+succeeds.
 
 ## The manifest
 
@@ -75,7 +80,7 @@ interface PluginManifest {
     missions: boolean;
   };
   permissions: { network: string[]; secrets: string[]; models: string[] };
-  commands: Array<{ name: string; summary: string }>;
+  commands: Array<{ name: string; summary: string; args: PluginCommandArg[]; options: PluginCommandOption[]; interactive: boolean; node: boolean }>;
   panels: Array<{ id: string; title: string; kind: 'list' | 'tree' | 'transcript' | 'form' }>;
 }
 ```

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

@@ -227,7 +227,7 @@ 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.joinMission`, `replyMission`, `sayMission`, `pauseMission`, `resumeMission`, `askReceiver` | 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
@@ -1007,8 +1007,8 @@ LAN or cross-machine plugin implements.
 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.
+- `join(request)`: a session on this node joins a mission as a decision
+  receiver (`missionJoin`). `request.receiver` 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
@@ -1017,7 +1017,7 @@ that is not null (or true) wins.
   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
+  and a decision receiver 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
@@ -1033,7 +1033,7 @@ transport, then calls the host API of its node:
 | `reply(request)` | `host.replyMission(request)` |
 | `pause(request)` | `host.pauseMission(request)` |
 | `resume(request)` | `host.resumeMission(request)` |
-| `ask(question)` | `host.askGiver(question)` (true when delivered) |
+| `ask(question)` | `host.askReceiver(question)` (true when delivered) |
 
 The near node fills `team` and `agent` with the team and the agent of the
 session that sends the request, or null. In a question, `team` is the team of
@@ -1058,18 +1058,18 @@ interface MissionRelayPort {
   ask(question: MissionQuestion): Promise<boolean>;
   say(request: RelayMessage): Promise<Said | null>;
 }
-interface RemoteGiver { node: string; sessionId: string }
-interface RelayJoin { missionId: string; giver: RemoteGiver; team: string | null; agent: string | null }
+interface RemoteReceiver { node: string; sessionId: string }
+interface RelayJoin { missionId: string; receiver: RemoteReceiver; team: string | null; agent: string | null }
 interface RelayReply { missionId: string; text: string; by: string; team: string | null; agent: string | null }
 interface RelayControl { missionId: string; by: string; team: string | null; agent: string | null }
 interface RelayMessage { missionId: string; text: string; by: string; team: string | null; agent: string | null }
 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; team: string | null }
+interface MissionQuestion { missionId: string; node: string; lead: string | null; leadSessionId: string; question: string; receiver: RemoteReceiver; team: string | null }
 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;
+  source: string | null; result: string | null; question: string | null; receivers: string[]; 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 }>;
 }
@@ -1090,7 +1090,7 @@ ports: {
     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,
+    ask: async (question) => (await peer.send(question.receiver.node, 'ask', question)) === true,
     say: async (request) => peer.ask('say', request),
   },
 },
@@ -1103,19 +1103,72 @@ 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.
+`commands` sits beside `ports`, not in it. Each command adds a command to the
+CLI: a person runs `orbital <plugin> <command> [args] [--options]`.
+`orbital help` and `orbital <plugin> --help` list the commands.
+
+Declare each command two times, with the same fields:
+
+- In `orbital-plugin.json`, so that orbital lists the command without a start
+  of the plugin.
+- In the code, with `defineCommand`. The SDK types `args` and `options` from
+  the declaration.
+
+The node refuses a plugin when the two lists are not the same.
+
+```json
+{ "name": "acme", "command": ["node", "dist/plugin.js"],
+  "commands": [
+    { "name": "login", "summary": "Sign in to acme in the browser.", "interactive": true },
+    { "name": "status", "summary": "Show the account.", "options": [{ "name": "verbose", "type": "boolean", "summary": "Show more." }] }
+  ] }
+```
 
 ```ts
-commands: {
-  whoami: {
-    summary: 'Name the account this plugin posts as.',
-    run: async (args) => `bot in ${args[0] ?? 'the default guild'}`,
-  },
-},
+import { defineCommand } from '@kaiba-cloud/orbital-sdk';
+
+commands: [
+  defineCommand({
+    name: 'login',
+    summary: 'Sign in to acme in the browser.',
+    interactive: true,
+    run: async ({ terminal }) => {
+      terminal!.output.write(`Open ${url} and type the code.\n`);
+      return { text: 'Signed in.', data: { account } };
+    },
+  }),
+  defineCommand({
+    name: 'status',
+    summary: 'Show the account.',
+    options: { verbose: { type: 'boolean', summary: 'Show more.' } },
+    run: async ({ options }) => ({ text: options.verbose ? detail : account, data: { account } }),
+  }),
+],
 ```
 
-**Remote method.** `command.run {name, args}`, answered with `{ output }`.
+| Field | Meaning |
+|---|---|
+| `name`, `summary` | The command word and its line in the help. A plugin whose name is a built-in command, such as `plugin` or `check`, gets no command. |
+| `args` | Positional arguments: `name`, `summary`, `required`, `variadic` (the last only). |
+| `options` | Flags: `name`, `type` (`string`, `boolean`, `integer`, `enum`, `path`), `summary`, `values` (enum only), `required`, `default`. `output`, `quiet`, `non-interactive`, `confirm`, `timeout`, `help`, `version`, `workspace` and `node` belong to orbital. |
+| `interactive` | The command needs a terminal, such as a browser or device login. `terminal` gives it the person's stdin, stdout and stderr. With `--output json`, its stdout goes to stderr. Without a terminal, orbital refuses the command. |
+| `node` | The command runs in the plugin of the running node, not in a new process. Without a node, orbital refuses it. It cannot be interactive. |
+
+orbital starts the plugin for the command only, with its config from
+`orbital.yaml` and the workspace in `context.init`. No node needs to run.
+
+`run` answers `{ text?, data?, exitCode? }`, or a string as `text`. Text mode
+prints `text`. `--output json` prints `data` in the envelope. `exitCode` is 0,
+1, 2 (no credential), 3 (bad input) or 5, and orbital exits with it.
+
+In an interactive command, write to `terminal.output`, never to
+`process.stdout`: stdout carries the protocol.
+
+The commands are for a person at the CLI. Agents do not see them: give agents
+a tool with `ports.tools`.
+
+**Remote method.** `command.run {name, args, options, terminal}`, answered
+with `{ exitCode, text, data }`.
 
 ## `service`
 

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

@@ -18,7 +18,7 @@ key. Then:
 - the agents of each node list the teams and agents of the other nodes
   (`directory`);
 - a person on one node joins, talks to, answers, pauses and resumes a mission
-  whose lead runs on another node, and the lead's question reaches the giver on its own
+  whose lead runs on another node, and the lead's question reaches each decision receiver on its own
   node (`missions`);
 - `orbital mission list` and the claims see the missions of every node, and
   `orbital up` shows the peers (`panels`).
@@ -130,7 +130,7 @@ export function plugin(context: PluginContext): PluginImplementation {
     }
     const body = await read(request);
     if (path === '/a2a') return a2a(host, body, response);
-    if (path === '/missions/ask') return send(response, 200, { delivered: await host.askGiver(JSON.parse(body)) });
+    if (path === '/missions/ask') return send(response, 200, { delivered: await host.askReceiver(JSON.parse(body)) });
     const relay = /^\/missions\/(join|say|reply|pause|resume)$/.exec(path);
     if (!relay) return send(response, 404, { error: `No route ${path}.` });
     const asked = JSON.parse(body);
@@ -184,7 +184,7 @@ export function plugin(context: PluginContext): PluginImplementation {
         pause: async (request) => firstAnswer<MissionRecord>('/missions/pause', request),
         resume: async (request) => firstAnswer<MissionRecord>('/missions/resume', request),
         ask: async (question) => {
-          const peer = peers.find((one) => one.name === question.giver.node);
+          const peer = peers.find((one) => one.name === question.receiver.node);
           if (!peer) return false;
           return (await call<{ delivered: boolean }>(peer, '/missions/ask', question).catch(() => null))?.delivered === true;
         },
@@ -236,7 +236,7 @@ How it works:
   its node. See the table in [ports.md](ports.md#missions).
 - **Missions.** `join`, `say`, `reply`, `pause` and `resume` ask each peer. A peer
   answers 404 when `host.missions()` does not hold the mission, and the next
-  peer is asked. `ask` goes to the peer that `question.giver.node` names.
+  peer is asked. `ask` goes to the peer that `question.receiver.node` names.
 - **Placements.** The node of the far agent never shows its own secret. The
   plugin serves A2A at `/a2a` and passes each call to `host.a2a`. The host API
   does not stream, so the plugin answers `SubscribeToTask` as a stream of