@kaiba-cloud/orbital 0.0.0-stage → 0.0.1

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

@@ -0,0 +1,581 @@
+# Recipes
+
+Each recipe is one `src/plugin.ts`. Start each one with `orbital plugin new`,
+replace `src/plugin.ts`, then build, check and add it as SKILL.md says.
+
+The `policy` and `command` templates add one check of their own to
+`test/conformance.test.ts`, after the conformance check. When you replace
+`src/plugin.ts`, replace that check with one for your plugin, or delete it.
+
+## 1. Cross-machine work: missions relay, directory and placements
+
+The plugin `lan` joins the nodes of a local network. Each machine runs a node
+with the same plugin. The plugins talk to each other over HTTP with a shared
+key. Then:
+
+- an agent on one node dispatches `coder@build-box`, and the session runs on
+  the node `build-box` (`sessions.create`, `placements`);
+- 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
+  node (`missions`);
+- `orbital mission list` and the claims see the missions of every node, and
+  `orbital up` shows the peers (`panels`).
+
+Start it:
+
+```bash
+orbital plugin new lan --port panel
+```
+
+Replace `src/plugin.ts`:
+
+```ts
+import { createServer, type IncomingMessage, type ServerResponse } from 'node:http';
+import type { HostApi, MissionRecord, PluginContext, PluginImplementation, Said } from '@kaiba-cloud/orbital-sdk';
+
+export const NAME = 'lan';
+
+const TERMINAL = ['TASK_STATE_COMPLETED', 'TASK_STATE_FAILED', 'TASK_STATE_CANCELED', 'TASK_STATE_REJECTED'];
+const REMOTE_AGENT = /^(.+)@([a-z0-9][a-z0-9-]{0,62})$/;
+
+interface Peer { name: string; url: string }
+interface Hello { node: string; agents: Array<{ name: string; description: string | null }>; missions: MissionRecord[] }
+interface Seen { at: string; hello: Hello }
+
+function send(response: ServerResponse, status: number, body: unknown): void {
+  response.writeHead(status, { 'content-type': 'application/json' });
+  response.end(JSON.stringify(body));
+}
+
+function read(request: IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    request.on('data', (chunk: Buffer) => chunks.push(chunk));
+    request.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+    request.on('error', reject);
+  });
+}
+
+export function plugin(context: PluginContext): PluginImplementation {
+  const { config } = context.init;
+  const self = context.init.node.name;
+  const port = typeof config.port === 'number' ? config.port : 7420;
+  const peers: Peer[] = Object.entries((config.peers ?? {}) as Record<string, string>)
+    .filter(([name]) => name !== self)
+    .map(([name, url]) => ({ name, url: url.replace(/\/$/, '') }));
+  const seen = new Map<string, Seen>();
+
+  async function key(): Promise<string> {
+    const value = await context.secret('lan.key');
+    if (!value) throw new Error('No shared key: run `orbital plugin secret set lan lan.key` on each machine.');
+    return value;
+  }
+
+  async function call<T>(peer: Peer, path: string, body?: unknown): Promise<T | null> {
+    const response = await fetch(`${peer.url}${path}`, {
+      method: body === undefined ? 'GET' : 'POST',
+      headers: { authorization: `Bearer ${await key()}`, 'content-type': 'application/json' },
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (response.status === 404) return null;
+    if (!response.ok) throw new Error(`${peer.name} ${path}: ${response.status} ${await response.text()}`);
+    return (await response.json()) as T;
+  }
+
+  async function firstAnswer<T>(path: string, body: unknown): Promise<T | null> {
+    for (const peer of peers) {
+      const answer = await call<T>(peer, path, body).catch(() => null);
+      if (answer) return answer;
+    }
+    return null;
+  }
+
+  async function poll(): Promise<void> {
+    for (const peer of peers) {
+      const hello = await call<Hello>(peer, '/hello').catch(() => null);
+      if (hello) seen.set(peer.name, { at: new Date().toISOString(), hello });
+    }
+  }
+
+  async function a2a(host: HostApi, body: string, response: ServerResponse): Promise<void> {
+    const rpc = JSON.parse(body) as { id: number | string; method: string; params: { id?: string } };
+    if (rpc.method !== 'SubscribeToTask') return send(response, 200, await host.a2a(body));
+    response.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache' });
+    let last = '';
+    while (!response.destroyed) {
+      const answer = (await host.a2a(JSON.stringify({ jsonrpc: '2.0', id: rpc.id, method: 'GetTask', params: { id: rpc.params.id } }))) as { result?: { status?: { state: string } }; error?: unknown };
+      if (!answer.result) {
+        response.write(`data: ${JSON.stringify(answer)}\n\n`);
+        break;
+      }
+      const frame = JSON.stringify({ jsonrpc: '2.0', id: rpc.id, result: { task: answer.result } });
+      if (frame !== last) response.write(`data: ${frame}\n\n`);
+      last = frame;
+      if (TERMINAL.includes(answer.result.status?.state ?? '')) break;
+      await new Promise((done) => setTimeout(done, 1000));
+    }
+    response.end();
+  }
+
+  async function serve(host: HostApi, request: IncomingMessage, response: ServerResponse): Promise<void> {
+    if (request.headers.authorization !== `Bearer ${await key()}`) return send(response, 401, { error: 'The key does not match.' });
+    const path = new URL(request.url ?? '/', 'http://lan').pathname;
+    if (request.method === 'GET' && path === '/hello') {
+      const catalog = await host.catalog();
+      const agents = [...catalog.teams, ...catalog.agents].map(({ name, description }) => ({ name, description }));
+      return send(response, 200, { node: self, agents, missions: await host.missions() } satisfies Hello);
+    }
+    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)) });
+    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);
+    if (!(await host.missions()).some((one) => one.missionId === asked.missionId)) return send(response, 404, { error: `No mission ${asked.missionId} here.` });
+    switch (relay[1]) {
+      case 'join':
+        return send(response, 200, await host.joinMission(asked));
+      case 'say':
+        return send(response, 200, await host.sayMission(asked));
+      case 'reply':
+        return send(response, 200, await host.replyMission(asked));
+      case 'pause':
+        return send(response, 200, await host.pauseMission(asked));
+      default:
+        return send(response, 200, await host.resumeMission(asked));
+    }
+  }
+
+  return {
+    name: NAME,
+    version: '0.1.0',
+    permissions: { network: peers.map((peer) => new URL(peer.url).hostname), secrets: ['lan.key'], models: [] },
+    ports: {
+      directory: {
+        agents: async () => [...seen.values()].flatMap(({ hello }) => hello.agents.map((agent) => ({ name: `${agent.name}@${hello.node}`, id: null, description: agent.description }))),
+        lookup: async () => null,
+        agent: async () => null,
+        skill: async () => null,
+      },
+      sessions: {
+        create: async (start) => {
+          const match = REMOTE_AGENT.exec(start.agent);
+          if (!match || !peers.some((peer) => peer.name === match[2])) return null;
+          return { kind: 'placement', placement: `lan:${match[2]}` };
+        },
+      },
+      placements: {
+        lan: {
+          decides: true,
+          endpoint: async (placement) => {
+            const name = placement.slice('lan:'.length);
+            const peer = peers.find((one) => one.name === name);
+            if (!peer) throw new Error(`No peer ${name}: add it under config.peers of the lan plugin.`);
+            return { url: `${peer.url}/a2a`, headers: { authorization: `Bearer ${await key()}` } };
+          },
+        },
+      },
+      missions: {
+        join: async (request) => firstAnswer<MissionRecord>('/missions/join', request),
+        say: async (request) => firstAnswer<Said>('/missions/say', request),
+        reply: async (request) => firstAnswer<MissionRecord>('/missions/reply', request),
+        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);
+          if (!peer) return false;
+          return (await call<{ delivered: boolean }>(peer, '/missions/ask', question).catch(() => null))?.delivered === true;
+        },
+      },
+      panels: {
+        missions: {
+          title: 'missions of the other nodes',
+          kind: 'list',
+          read: async () => ({
+            columns: ['mission', 'node', 'team', 'state', 'lead', 'session', 'claim', 'claimedAt', 'question', 'result', 'updated', 'seen'],
+            rows: [...seen.values()].flatMap(({ at, hello }) => hello.missions.map((one) => ({
+              mission: one.missionId, node: one.node, team: one.team, state: one.state, lead: one.lead, session: one.sessionId,
+              claim: one.claim, claimedAt: one.claimedAt, question: one.question, result: one.result, updated: one.updatedAt, seen: at,
+            }))),
+          }),
+        },
+        peers: {
+          title: 'peers on the network',
+          kind: 'list',
+          read: async () => ({
+            columns: ['node', 'address', 'trust'],
+            rows: peers.map((peer) => ({ node: peer.name, address: peer.url, trust: seen.has(peer.name) ? 'shared key' : 'not seen' })),
+          }),
+        },
+      },
+    },
+    service: {
+      ends: false,
+      start: async ({ host, signal }) => {
+        const server = createServer((request, response) => {
+          serve(host, request, response).catch((error: unknown) => send(response, 500, { error: error instanceof Error ? error.message : String(error) }));
+        });
+        await new Promise<void>((done) => server.listen(port, '0.0.0.0', done));
+        await poll();
+        const timer = setInterval(() => void poll(), 10_000);
+        signal.addEventListener('abort', () => clearInterval(timer));
+        context.log('info', `${NAME} listens on port ${port} for ${peers.length} peers`);
+        return { stop: async () => { clearInterval(timer); server.close(); } };
+      },
+    },
+  };
+}
+```
+
+How it works:
+
+- **Two sides.** Each method of a port is the near side. The HTTP route of the
+  same plugin on the other node is the far side, and it calls the host API of
+  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.
+- **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
+  `GetTask` results until the task ends.
+- **Directory.** The list shows `<agent>@<node>`. `lookup` and `agent` answer
+  null: such a session never runs here, because `sessions.create` sends it to
+  the placement. The far node takes the `@<node>` part off.
+- **Panels.** The `missions` panel feeds the mission list and the claims of the
+  node. `seen` marks a row stale when the peer stops answering. The `peers`
+  panel feeds `orbital up`.
+
+Keep `fixtures.json` as `{}`: `npm test` gives the plugin no config and no
+secret, so the placement check skips. To run the placement check through the
+real protocol, set the key and the `peers` config first, then give a second
+fixtures file:
+
+```bash
+echo '{ "placements": { "lan": "lan:build-box" } }' > lan-check.json
+orbital plugin check lan --fixtures lan-check.json
+```
+
+`plugin check` reads the config of the `config.yaml` entry and the secrets that
+`orbital plugin secret set` keeps.
+
+`config.yaml` on the machine `laptop`, with its node started as
+`orbital node start --name laptop`:
+
+```yaml
+plugins:
+  lan:
+    source: ./plugins/lan
+    config:
+      port: 7420
+      peers:
+        build-box: http://192.168.1.20:7420
+```
+
+The machine `build-box` names `laptop` the same way. Keep the same key on
+both:
+
+```bash
+orbital plugin secret set lan lan.key
+```
+
+## 2. A telemetry dashboard sink
+
+The plugin holds the graph of the node and posts it to a dashboard after each
+change. It uses the snapshot once, then the events.
+
+```bash
+orbital plugin new board --port telemetry
+```
+
+The template already keeps the graph. Add the post at the end of `event`, and
+declare the host:
+
+```ts
+permissions: { network: ['board.example.com'], secrets: ['board.token'], models: [] },
+```
+
+```ts
+async function post(body: unknown): Promise<void> {
+  const token = await context.secret('board.token');
+  if (!token) throw new Error('No token: run `orbital plugin secret set board board.token`.');
+  const response = await fetch('https://board.example.com/api/graph', {
+    method: 'POST',
+    headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(5000),
+  });
+  if (!response.ok) throw new Error(`The board answered ${response.status}.`);
+}
+```
+
+```ts
+event: async (event) => {
+  if (!graph) {
+    early.push(event);
+    return;
+  }
+  if (event.seq > graph.sequence + 1) {
+    graph = await context.host().snapshot();
+    await post(graph);
+    return;
+  }
+  apply(event);
+  await post(graph);
+},
+```
+
+- A `seq` more than one above the graph's `sequence` means that the node
+  dropped events for this sink. Take a new snapshot.
+- The node never waits for the sink. A slow post only costs this sink its
+  oldest calls.
+- To send each event instead of the whole graph, post `event` and let the
+  dashboard apply it.
+- Watch the same data with `orbital telemetry watch` and
+  `orbital telemetry snapshot` while you test.
+
+`config.yaml`:
+
+```yaml
+plugins:
+  board:
+    source: ./plugins/board
+telemetry: board
+```
+
+## 3. A Slack channel
+
+The plugin posts messages to Slack and gives the node each message a person
+writes in a channel that a binding names.
+
+```bash
+orbital plugin new slack-lite --port channel
+```
+
+```ts
+import type { ChannelBinding, ChannelEnvelope, PluginContext, PluginImplementation } from '@kaiba-cloud/orbital-sdk';
+
+export const NAME = 'slack-lite';
+
+export function plugin(context: PluginContext): PluginImplementation {
+  const sent = new Map<string, { ref: string; thread: string | null }>();
+  let bindings: ChannelBinding[] = [];
+
+  async function slack<T>(method: string, body: Record<string, unknown>): Promise<T> {
+    const token = await context.secret('slack.botToken');
+    if (!token) throw new Error('No token: run `orbital plugin secret set slack-lite slack.botToken`.');
+    const response = await fetch(`https://slack.com/api/${method}`, {
+      method: 'POST',
+      headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json; charset=utf-8' },
+      body: JSON.stringify(body),
+    });
+    const answer = (await response.json()) as T & { ok: boolean; error?: string };
+    if (!answer.ok) throw new Error(`Slack ${method}: ${answer.error ?? response.status}`);
+    return answer;
+  }
+
+  const text = (envelope: ChannelEnvelope) => envelope.message.parts.flatMap((part) => (part.text ? [part.text] : [])).join('\n');
+
+  return {
+    name: NAME,
+    version: '0.1.0',
+    permissions: { network: ['slack.com'], secrets: ['slack.botToken'], models: [] },
+    ports: {
+      channels: {
+        [NAME]: {
+          capabilities: { live: true, human: true, threads: true, durable: true, offline: false },
+          send: async (envelope, binding) => {
+            const known = sent.get(envelope.message.messageId);
+            if (known) return known;
+            const posted = await slack<{ ts: string }>('chat.postMessage', {
+              channel: String(binding.config.channel),
+              text: text(envelope),
+              ...(envelope.thread && { thread_ts: envelope.thread }),
+            });
+            const answer = { ref: posted.ts, thread: envelope.thread ?? posted.ts };
+            sent.set(envelope.message.messageId, answer);
+            return answer;
+          },
+          listen: async (given) => {
+            bindings = [...given];
+          },
+        },
+      },
+    },
+    service: {
+      ends: false,
+      start: async ({ host, signal }) => {
+        const oldest = new Map<string, string>();
+        const poll = async () => {
+          for (const binding of bindings) {
+            const channel = String(binding.config.channel);
+            const history = await slack<{ messages: Array<{ ts: string; user?: string; text: string; thread_ts?: string; bot_id?: string }> }>('conversations.history', { channel, oldest: oldest.get(channel) ?? String(Date.now() / 1000) });
+            for (const message of history.messages.reverse()) {
+              oldest.set(channel, message.ts);
+              if (message.bot_id || !message.user) continue;
+              const answer = await host.deliver({
+                channel: NAME,
+                bindingId: binding.id,
+                envelope: {
+                  message: { messageId: `slack-${channel}-${message.ts}`, role: 'ROLE_USER', parts: [{ text: message.text }] },
+                  from: { kind: 'person', name: message.user },
+                  to: binding.team ? { kind: 'team', name: binding.team } : { kind: 'node', name: binding.ade },
+                  thread: message.thread_ts ?? message.ts,
+                },
+              });
+              if (!answer.accepted && !answer.duplicate) context.log('warn', `not taken: ${answer.reason}`);
+            }
+          }
+        };
+        const timer = setInterval(() => void poll().catch((error: unknown) => context.log('error', String(error))), 5000);
+        signal.addEventListener('abort', () => clearInterval(timer));
+        return { stop: async () => clearInterval(timer) };
+      },
+    },
+  };
+}
+```
+
+- The message id `slack-<channel>-<ts>` is stable, so the node drops a second
+  delivery of the same message.
+- An answer goes to the thread of its question: `thread` carries the `ts` of
+  the first message.
+- This recipe polls. For pushes, use Socket Mode with the `ws` package, as
+  `plugins/channel-slack` in the source repository does. `ws` is a CommonJS
+  package: the template's build banner gives it a `require`.
+
+A team uses it in `teams/<team>/channels.yaml`:
+
+```yaml
+- type: slack-lite
+  channel: C0123456789
+```
+
+Fixture for the send check, with a real test channel:
+
+```json
+{ "channels": { "slack-lite": { "id": "node:0", "channel": "slack-lite", "config": { "channel": "C0123456789" }, "team": null, "ade": "conformance" } } }
+```
+
+## 4. A policy engine
+
+The plugin reads rules from its folder in the definition, such as
+`.atom/guard/rules.json`, and asks a model only when no rule matches.
+
+```bash
+orbital plugin new guard --port policy
+```
+
+```ts
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { PluginContext, PluginImplementation, PolicyAction, PolicyDecision } from '@kaiba-cloud/orbital-sdk';
+
+export const NAME = 'guard';
+
+interface Rule { tool: string; contains: string; verdict: 'deny' | 'ask'; reason: string }
+
+export function plugin(context: PluginContext): PluginImplementation {
+  const file = context.init.folder ? join(context.init.folder, 'rules.json') : null;
+  const rules: Rule[] = file && existsSync(file) ? (JSON.parse(readFileSync(file, 'utf8')) as Rule[]) : [{ tool: 'shell', contains: 'git push', verdict: 'deny', reason: 'Pushes go through review.' }];
+  const judge = typeof context.init.config.judge === 'string' ? context.init.config.judge : null;
+
+  async function byModel(action: PolicyAction): Promise<PolicyDecision> {
+    if (!judge) return { verdict: 'allow' };
+    try {
+      const { text } = await context.host().completeModel({
+        model: judge,
+        system: 'You guard a coding agent. Answer DENY: <reason>, or OK.',
+        messages: [{ role: 'user', content: JSON.stringify(action) }],
+        maxTokens: 200,
+      });
+      return text.startsWith('DENY') ? { verdict: 'deny', reason: text.slice(5).trim() || 'The judge refused it.', policy: NAME } : { verdict: 'allow' };
+    } catch (error) {
+      return { verdict: 'ask', question: `The judge failed (${error instanceof Error ? error.message : String(error)}). Allow ${action.kind}?`, policy: NAME };
+    }
+  }
+
+  return {
+    name: NAME,
+    version: '0.1.0',
+    permissions: { network: [], secrets: [], models: judge ? [`${judge.slice(0, judge.indexOf(':'))}:*`] : [] },
+    ports: {
+      policy: {
+        deterministic: judge === null,
+        decide: async (action) => {
+          if (action.kind !== 'tool.call') return { verdict: 'allow' };
+          const rule = rules.find((one) => one.tool === action.tool && action.target.includes(one.contains));
+          if (rule?.verdict === 'deny') return { verdict: 'deny', reason: rule.reason, policy: NAME };
+          if (rule?.verdict === 'ask') return { verdict: 'ask', question: rule.reason, policy: NAME };
+          return byModel(action);
+        },
+      },
+    },
+  };
+}
+```
+
+- With `judge` set, the engine is not deterministic, so the node reads its
+  `allow` as no answer. Only `deny` and `ask` count.
+- When the model fails, answer `ask`, never `allow`.
+- `permissions.models` must match the judge model, or `completeModel` fails.
+- A rule file is optional. Without it, the plugin uses its default rule.
+
+`config.yaml`:
+
+```yaml
+plugins:
+  guard:
+    source: ./plugins/guard
+    config:
+      judge: anthropic:claude-haiku-4-5
+policy: [orbital, guard]
+```
+
+## 5. A team member on your own harness
+
+A harness plugin runs a team member on another agent program, the same way
+`claude` and `pi` run. Checked end to end with a lead on `claude` that
+dispatches a member on the harness `scripted`.
+
+1. Write the plugin, and add your program to `src/turn.ts`:
+
+   ```bash
+   orbital plugin new scripted --port harness --dir plugins/scripted
+   cd plugins/scripted && npm install && npm test
+   ```
+
+   The template writes thinking, one tool call with its output, the answer, the
+   tokens and the result, and says `callsModel: false`.
+
+2. Name the plugin in `config.yaml`. A relative source is relative to the
+   definition folder:
+
+   ```yaml
+   plugins:
+     scripted:
+       source: ../plugins/scripted
+   ```
+
+3. Give a member the harness in its charter:
+
+   ```yaml
+   lead: lead
+   members:
+     - name: scout
+       role: Looks around the workspace.
+       harness: scripted
+   ```
+
+4. Start the node, and give the team a mission whose lead dispatches `scout`.
+
+What you see:
+
+- `orbital up` lists `scout` under the team with `· scripted` on each session, and enter opens its transcript: the thinking, `ls(…)` with its output, and the answer, live while the turn runs.
+- `orbital telemetry snapshot` holds the tokens of the model `example:scripted` for the mission, and the events hold a `job.dispatched` and a `job.ended` for each dispatch.
+- A second message to the same job starts a turn with `spec.resume` true.
+- `orbital mission pause` stops a running turn of the member (SIGTERM), and `orbital mission resume` lets the lead go on.
+

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.