Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.
TypeScript browser-shellcontrol-planefile-managerhomelabmobile-firstnextjsptyreactself-hostedserver-managementshadcn-uisysadmintailwindcssterminaltypescriptvpsweb-desktopweb-terminal
feat(skills): add mso-agent-fleet for Orca + OpenCode fan-out (#217)
Abdurrahman Fakhrulaf7ce44f3874
diff --git a/claude-skills/mso-agent-fleet/SKILL.md b/claude-skills/mso-agent-fleet/SKILL.mdnew file mode 100644index 00000000..b36c42ec--- /dev/null+++ b/claude-skills/mso-agent-fleet/SKILL.md@@ -0,0 +1,107 @@+---+name: mso-agent-fleet+description: Drive Orca worktrees and OpenCode sessions through MSO tool calls, fan out bounded subagents per session, supervise progress, and expose the whole loop to HTTPS webhook triggers.+metadata:+ mso:+ risk: medium+ policy: orchestrate-supervise-verify+---++# /mso-agent-fleet — Orca + OpenCode fleet from MSO tool calls++MSO stays the control plane. Orca is the visible surface (worktrees, terminals, board).+OpenCode is a worker CLI. Neither gets new trust: every step is an existing bounded tool.++## Trigger and boundaries++- **Use when:** one request must become several parallel coding sessions, must stay visible on a board, or must be startable from an HTTPS call instead of a chat.+- **Do not use when:** one bounded edit answers the request, or the task needs no second agent. Do not build a fleet for a single file change.+- **Required context:** repo/project identity, how many workers, target host (`local` or `ssh:...`), and whether a human must approve each worker.++## Two control surfaces++| Need | Use | Why |+|---|---|---|+| Visible worktree/terminal/board | `orca_*` MCP tools from `bin/orca-mcp.mjs` | thin argv onto `orca <cmd> --json`, no shell |+| Isolated reasoning worker, no UI | `agent_subagent_run` | isolated context, foreground, non-recursive |+| OpenCode session as a process | `exec_run` / `exec_job_start` around `opencode run` | bounded, jailed, cancellable |+| Server-side automation + webhook | Workflow Graph `webhook` → `tool`/`agent` nodes | token auth, receipts, idempotency |++`orca` is `orca-ide` on this laptop (WSL launcher → PowerShell bridge). Never call bare `orca`.++## Fast route++1. `orca_status` — stop if `runtime.state` is not `not_running`/ready. Every orca call fails otherwise.+2. `orca_host_list` — learn the exact host label. Handles belong to the host that issued them; never move a handle across hosts.+3. `orca_worktree_list` → `orca_worktree_create` — one worktree per workstream. `agent`/`prompt` launch a worker immediately; omit both to only create the checkout.+4. Fan out with `agent_subagent_run` when workers need isolation but no UI; use `orca_agent_launch` or `orca_terminal_create` when a human must watch.+5. Supervise with `orca_worktree_ps` (cheapest board read), then `orca_terminal_wait` instead of polling `orca_terminal_read`.+6. Finish: `orca_terminal_close`, then one summary. Never leave orphan terminals behind.++## Fan-out patterns++**Board-visible fan-out**++```text+orca_worktree_create name:<stream> repo:name:<repo> agent:opencode prompt:<task>+orca_agent_launch agent:opencode worktree:name:<stream> prompt:<follow-up>+orca_worktree_ps limit:50+```++**Invisible reasoning fan-out** — one `agent_subagent_run` per workstream, `max_scope` no higher than the caller holds, `max_turns` ≤ 12 for a review pass. Subagents cannot spawn subagents and cannot touch session/memory/A2A tools.++**OpenCode as a worker** — `exec_job_start` with `opencode run --format json -m <provider/model> "<task>"`, then `exec_job_status`. Use `exec_run` only when the task fits the 30s budget. Add `--session <id>` to continue, `--fork` to branch an existing session.++## Webhook trigger++```text+graph: webhook(POST, authVariable=secret var ≥16 chars)+ → project (resolve canonical path at runtime)+ → tool (exec_job_start: opencode run … or orca agent launch …)+ → wait (bounded)+ → tool (exec_job_status / orca_worktree_ps)+ → output+```++Endpoint `/api/v1/workflows/webhook/<graphId>/<nodeId>`, bearer from a private secret variable. `responseMode=onReceived` returns a run id immediately — correct for fleets. `lastNode` waits under a bounded budget; do not use it for long agent work. Send `idempotency-key` so a retried webhook does not create a second fleet.++## Tool routing++| Need | Preferred | Avoid |+|---|---|---|+| Board state | `orca_worktree_ps` | listing every terminal |+| Wait for a worker | `orca_terminal_wait` (`for:"tui-idle"`) | fixed `sleep` loops |+| Isolated research | `agent_subagent_run` | spawning a whole worktree |+| Long process | `exec_job_start` + `exec_job_status` | `exec_run` near 30s |+| Repeatable trigger | Workflow Graph webhook | hand-rolled HTTP server |+| Human approval gate | Orca terminal + board comment | silent `--auto` agents |++## Execution flow++1. **Preflight** — `orca_status`, confirm host, confirm repo identity. Refuse to guess a repo.+2. **Shape** — pick worker count from real independent workstreams, not from a round number.+3. **Launch** — create worktrees first, then launch, then record the mapping `stream → worktree → handle`.+4. **Supervise** — wait on idle/exit; read bounded output only when a wait returns a change.+5. **Verify** — the worker's claim is not evidence. Run the narrow test or read the diff yourself.+6. **Converge** — close terminals, set board status via `orca_worktree_set`, report per-stream outcome.+7. **Persist** — only when the loop must repeat: encode it as a Workflow Graph, activate it, and store the bearer in a secret variable.++## Verification contract++- **Expected state:** each requested stream has one worktree, one known terminal/agent, and one recorded outcome.+- **Targeted checks:** diff or test output per stream; `orca_worktree_ps` shows no stuck agent.+- **Runtime proof:** `exec_job_status` reaches `succeeded`/`failed`, or `orca_status` stays ready with zero leaked terminals.+- **Webhook proof:** one authenticated `POST` returns a `runId`, and the run receipt shows the expected nodes.+- **Diff boundary:** worker edits stay inside their own worktree; the MSO checkout is never a worktree target.++## Failure and rollback++- Orca `not_running` → `orca open`, then re-check `orca_status`. Do not retry the failed call blindly.+- Wrong-host handle → the handle belongs to another runtime; re-list on the correct host instead of forcing it.+- Runaway fleet → `orca_terminal_close` per worktree, `exec_job_cancel` per job, keep the worktrees for inspection.+- Webhook unauthenticated → an active webhook without a secret variable fails closed by design; fix configuration, never disable the check.+- Never force-push, delete a worktree with uncommitted work, or point a worker at the live MSO checkout.++## Recipe memory++Save the mapping and the exact argv shapes, never prompts containing secrets, tokens, pairing codes, or terminal contents. A successful fan-out recipe is only reusable when the host label, repo identity and node list are all still observed live.diff --git a/claude-skills/mso-agent-fleet/agents/openai.yaml b/claude-skills/mso-agent-fleet/agents/openai.yamlnew file mode 100644index 00000000..ec450ab2--- /dev/null+++ b/claude-skills/mso-agent-fleet/agents/openai.yaml@@ -0,0 +1,4 @@+interface:+ display_name: "Agent Fleet Orchestration"+ short_description: "Fan out Orca + OpenCode workers from MSO"+ default_prompt: "Use $mso-agent-fleet to split this request into supervised Orca worktrees and OpenCode sessions, then verify each stream."diff --git a/claude-skills/mso-agent-fleet/contract.yaml b/claude-skills/mso-agent-fleet/contract.yamlnew file mode 100644index 00000000..c3635330--- /dev/null+++ b/claude-skills/mso-agent-fleet/contract.yaml@@ -0,0 +1,39 @@+version: 1+routing:+ use_when:+ - "one request must become several parallel coding sessions"+ - "work must stay visible on an Orca board or reachable from an HTTPS webhook"+ - "fan out bounded subagents and supervise them to a verified outcome"+ do_not_use_when:+ - "One bounded edit answers the request; a fleet adds risk with no benefit."+ - "The task is a single obvious tool call with no second agent or trigger needed."+ fallback: false+ prefer_over:+ - a2a+context:+ target: agent-fleet+ mode: execute+ actor: operator+lifecycle:+ discover:+ - orca_status+ - orca_host_list+ - orca_worktree_list+ - workflow_start+ validate:+ - host-label-matches-handle+ - repo-identity-exact+ - subagent-scope-not-widened+ verify:+ - orca_worktree_ps+ - exec_job_status+ - workflow_finish+state:+ source_of_truth: live+ refresh: always+safety:+ risk: medium+ confirmation: contextual+ concurrency: contextual+presentation:+ authority: hybriddiff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.mdindex 6440e08a..5bf0a743 100644--- a/docs/CHANGELOG.md+++ b/docs/CHANGELOG.md@@ -8,6 +8,7 @@ this is the *what*, and it is what Settings → Account → About shows as “Wh**Added**+- `skills` add mso-agent-fleet for Orca + OpenCode fan-out- `ci` three security scanners that actually run, and lanes that fail closed (#210)- `tui` the panel is the default, and the banner lives in the transcript (#209)