Adopt opencode as the taOS agent harness: one host assistant (taosagent) + sandboxed app-builder lane

[jaylfc]

Decision

Adopt opencode (the maintained anomalyco/opencode TS build, MIT, npm-distributed, OpenAI-partnered) as taOS's agent harness, installed from upstream with no fork. It serves two roles through one design:

1. The taOS assistant (replacing the current framework-less direct-LLM chat).
2. The App Builder code-generation engine.

The user-facing model is one host assistant, one brain — not two competing assistants. The only thing that physically separates is where untrusted code executes.

Why opencode

• Headless HTTP server (OpenAPI 3.1 + SSE + typed JS/TS SDK) is a cleaner driver surface than OpenClaw's ACP or Hermes' api_server. The host-side adapter is one codec mapping opencode SSE events to taOS's fixed 6-kind reply vocabulary (delta/final/tool_call/tool_result/reasoning/error). tinyagentos/adapters/acp_adapter.py is the copy template.
• Point it at the LiteLLM proxy (the deployer already injects OPENAI_BASE_URL + a per-agent virtual key) and it inherits the synced model-management that just shipped (permitted set == key scope), so its 75+ providers collapse to taOS's one governed surface.
• Multi-agent / persona / session natively, plus custom tools in any language and a per-tool wildcard permission system. That is exactly the configurability the two roles need.
• Fork-free: add as a store framework like OpenClaw/Hermes. No reinventing an agent loop.

Current state being replaced

tinyagentos/routes/taos_agent.py (/api/taos-agent/chat) is a direct streaming LiteLLM chat: system prompt from docs/taos-agent-manual.md, user-picked model, no tools, no MCP, no agent loop. It can talk about taOS but cannot act. opencode gives the assistant real tool-calling + actions.

Architecture: one host assistant + a sandboxed build lane

Host assistant (privileged)

• Runs on the host, not in a container, so it can diagnose and fix taOS (logs, systemctl, config, the LiteLLM proxy, containers). A sandboxed assistant cannot recover a broken install.
• Two frontends over one instance: the taOS web panel (via opencode's headless HTTP/SSE API) and the native TUI as taosagent in the terminal.
• Tool surface is a curated taOS-management set exposed via routes/mcp.py (read logs, snapshot+repair config, restart service, manage agents/proxy/containers), NOT raw arbitrary shell.
• Runs as its own service, independent of tinyagentos.service, so it can restart the main server when that is what is broken.

Sandboxed build-execution lane

• The host assistant handles "build me an app" via a dedicated app-creation persona, but the actual untrusted codegen executes in a disposable container sandbox it supervises.
• Rationale: opencode isolation is application-level only (permission matching, no OS/syscall sandbox), and the host instance is root. Agent-generated, prompt-injectable, often-shared code must never execute with host-root privilege. The container is the hard boundary; opencode permissions are a second layer.
• Tier: local-only scratch builds may use an in-process restricted persona; anything bound for the community store goes in the sandbox, no exception.
• Decision rule: one assistant, one brain, but untrusted code never executes in the privileged host process.

taosagent recovery CLI

"Run taosagent in the terminal and ask it to fix your install." This is the sanctioned exception to the no-terminal-for-end-users rule: one memorable command, then natural language, not a sequence of apt/systemctl spells. Three hard constraints:

1. Runs when taOS is down. Zero dependency on tinyagentos.service or the web stack; bootstraps its own context (finds the install, reads config/logs/journal). Shipped by the bootstrap installer so it is always present.
2. Survives the LLM chicken-and-egg. If the LiteLLM proxy is the broken thing, the agent still needs to reason: run deterministic, no-LLM diagnostics first (port checks, service status, config lint, disk/journal scan), and provide a fallback/direct model path that bypasses the proxy.
3. Repairs are vetted recipes, not freestyle root shell. A defined toolset (restart service, rebuild SPA, repair/snapshot config, restart proxy, unwedge a container, free a stuck port) that the LLM selects and explains while the recipe performs the action: snapshot-first, confirm destructive, audit-log every repair.

Guardrail stack (before agent-built apps reach the public store)

1. Constrain the build persona into a .taosapp factory: locked Plan/Build permissions, a scaffold template it edits rather than invents, and a taos_app_validate / taos_app_package custom tool giving a hard pass/fail loop before the user sees anything.
2. Re-validate every artifact through the existing untrusted pipeline with zero trust on "the agent built it": userspace/package.py manifest validation, zip-slip defense, userspace/url_guard.py SSRF guard, capability-broker grant gating.
3. Automated pre-gate feeding the human approval step: manifest lint, permission-diff, dependency/secret scan, static analysis of web bundles.
4. Web apps only at launch. The container app type ships an arbitrary OCI image with no provenance, scan, or egress controls; gate it behind registry allowlist + digest pinning + image scan + default-deny egress before it is publicly shareable.

Security boundaries

• Host assistant is the highest-privilege component in taOS. Curated tool surface, snapshot-first + confirm on destructive actions, audit log.
• OPENCODE_SERVER_PASSWORD is not a security boundary: bind 127.0.0.1 only, per-session-generated, never on taos.local/mDNS.
• The recovery TUI must be auth-gated: "GUI is down" must not mean "unauthenticated host agent with fix powers."
• Pin anomalyco/opencode at a version/digest; explicitly avoid the abandoned Go opencode-ai/opencode.

Real (not free) work

• The SSE to 6-kind adapter codec.
• An opencode branch in tinyagentos/framework_model_sync.py plus adding it to the reconciler allowlist (currently hard-coded to ('openclaw','hermes')).
• Reconcile opencode's multi-session model against taOS's per-agent turn serialization (pin one session per agent).
• Measure host + cluster footprint to set manifest tiers.

Phased path

1. Spike the adapter: install pinned opencode in one container, point it at LiteLLM, deploy a test agent, run one turn, confirm a non-permitted model call is rejected by LiteLLM. Copy the acp_adapter mapping table.
2. Host assistant MVP: opencode on the host with the taOS-management MCP tools + taosagent TUI, replacing routes/taos_agent.py. Deterministic diagnostics + fallback model path.
3. App Builder: app-creation persona + the .taosapp factory tools + sandboxed build lane + the opaque-origin iframe live preview. Ships before share.
4. Model-sync codec for opencode.
5. Share-to-store + the automated pre-gate. Web apps only initially.

Blocked / dependencies

• Share-to-store depends on gitaos + taOS accounts.
• The npm version-probe gap (no GitHub-release version tracking for npm-distributed frameworks) is shared with OpenClaw and tracked under the framework version-selection work.

[jaylfc]

Implementation grounding (opencode API verified live on the Pi)

opencode-ai 1.15.13 installed and inspected live. Confirmed the real headless API so the adapter is built against facts, not docs:

• Server: opencode serve --port <n> --hostname 127.0.0.1. Basic auth via OPENCODE_SERVER_PASSWORD (warns "unsecured" when unset). OpenAPI at GET /doc (294 schemas).
• Drive a turn: POST /session -> POST /session/:id/message (sync) or /session/:id/prompt_async (204). Body: { model: {providerID, modelID}, agent?, system?, noReply?, parts: [{type:"text", text}] }.
• Events: SSE GET /event. Each event is {type:"sync", name, id, seq, aggregateID, data}; name discriminates. The codec maps to taOS's 6 kinds:
  • text delta data{delta} -> delta; text ended data{text} -> final segment
  • reasoning delta data{reasoningID, delta} -> reasoning
  • tool called data{callID, tool, input} -> tool_call
  • tool success data{callID, structured, content} / tool failed data{callID, error} -> tool_result
  • step failed data{error} -> error
  • bonus: model switched data{model} -> reverse-reconcile signal (opencode tells us when its model changes natively)

This mirrors adapters/acp_adapter.py (same 6-kind target). Exact name strings get pinned from a live event capture during the spike turn.

Two added requirements (jay)

• The taOS agent gets its own LiteLLM virtual key. It becomes a first-class agent record (own scoped key, not the master key), so it rides the synced model-management rails (permitted set == key scope) just like deployed agents.
• Configurable from the Agents app. Model, permitted-model set, and persona/instructions editable via the same UI shipped in feat(agents): change an agent's model from agent settings #577/feat(agents): permitted-model set + agent-facing model API (#570) #581/feat(agents): multi-select permitted-model set in the Framework tab (#570) #583. The taOS agent is a managed agent entity (reserved/system-badged), not a bespoke hidden path.

Phased PRs

1. opencode adapter (SSE->6-kind codec) + a thin host runtime that drives one turn through LiteLLM; capture exact event names live.
2. taOS agent as an agent record: mint its own virtual key, framework opencode, surfaced + configurable in the Agents app (model/permitted/persona).
3. Rewire routes/taos_agent.py chat to drive the host opencode session; rename "taOS Assistant" -> "taOS agent" in the UI.
4. Run opencode as a host service; taosagent TUI.
5. framework_model_sync opencode codec + reconciler allowlist; MCP management tools; sandboxed build lane.

[jaylfc]

Reference: how odysseus uses opencode (and why our approach differs)

Studied pewdiepie-archdaemon/odysseus, which is also "built on opencode".

• They ported opencode's agent loop into Python (src/agent_loop.py wraps their own stream_llm() with multi-round tool execution; tools detected via fenced code blocks; ACKNOWLEDGMENTS says "adapted for agent-loop/tool-execution"). That is effectively a soft-fork of opencode's logic. Our approach drives the real opencode headless binary and tracks upstream anomalyco/opencode. For taOS that is better aligned with the no-fork / framework-agnostic goals, and we get opencode's structured tool calls + in-session features for free (they get a text-protocol tool-calling they must maintain).
• Context compaction: opencode compacts the session itself (there is a CompactionPart in its event stream). Because the taOS agent uses a persistent session, we inherit this. Confirm during longer-conversation testing that the session does not grow unbounded.
• AGENTS.md: opencode's native persistent-instructions file. Prefer rendering the taOS agent's system context there over the per-turn system we send today (this is also the render target for the canonical-skills work, Canonical taOS-operations skills: one source of truth, framework-portable injection, permission-bound #595).

[jaylfc]

Requirement: taosagent TUI is the SAME agent as the GUI

When a user cannot get into the UI and drops to taosagent in the terminal, they must be talking to the SAME taOS agent they would inside the UI: same memory, same profile, same settings (model / permitted set / persona), same conversation history, same identity/key. Not a fresh opencode invocation with defaults.

Design that enforces this:

• The TUI ATTACHES to the running host taOS-agent opencode instance (same port, same server password, same persistent session, same config) rather than spawning its own. The GUI panel and the TUI are two frontends onto one opencode session + one config, so nothing can diverge.
• The taOS-agent opencode server runs as its OWN service (independent of the main taOS server), so it stays up when the UI/main server is down and the TUI can attach for recovery.
• If even that server is down, taosagent starts it from the on-disk config (the same settings the GUI uses), so a cold recovery wakes the same agent, not a default one.

Config and memory both come from the single shared source (the taOS agent's config + its taOSmd memory profile + the shared opencode session) — read by both frontends.