feat: add optio-opencode package and opencode-demo reference task

Ship the optio-opencode Python package per the 2026-04-22 design spec:
a factory that runs `opencode web` as an optio task — either as a local
subprocess or on a remote host over SSH — with opencode's UI embedded
in the dashboard via the widget proxy.  Consumers pass an
OpencodeTaskConfig (system prompt + opencode.json passthrough + SSH
config + deliverable callback); the package handles install, launch,
port-forwarding, keyword-log-tailing, DONE/ERROR termination, and
cleanup.

Key components:

- `types.py` — SSHConfig, OpencodeTaskConfig, DeliverableCallback alias.
- `prompt.py` — coordination-protocol base prompt + `compose_agents_md`
  composer that prepends it to the consumer's own instructions.
- `logparse.py` — regex-based parser for STATUS / DELIVERABLE / DONE /
  ERROR log lines, with workdir-escape-guarded path validation.
- `host.py` — Host Protocol + LocalHost (asyncio.subprocess + aiofiles)
  + RemoteHost (asyncssh with SFTP, local port forward, tail -F).  Both
  implement detect_target + install_opencode_binary for the shipped-
  binary path (see below).
- `install.py` — OpencodeTarget dataclass + OS / arch / musl / baseline
  / rosetta detection logic ported from opencode's upstream installer.
- `session.py` — run_opencode_session state machine: provision workdir
  → install opencode → launch → pre-create a shared session via HTTP so
  multiple dashboard viewers of the same process converge on the same
  session → register widget upstream with random Basic-Auth password
  → set widgetData (with `{widgetProxyUrl}` template + iframeSrc
  pointing at the pre-created session) → spawn tail + fetcher + exit +
  cancellation watchers → teardown (polite / aggressive).  Also
  includes create_opencode_task factory.

Environment-variable configuration (no consumer-code impact):

- `OPTIO_OPENCODE_BINARY_DIR` — directory containing opencode's per-
  target build output (e.g. `opencode-linux-x64/bin/opencode`).  When
  set, optio-opencode probes the target host's triple, resolves the
  matching binary, and installs it — locally by running it in place,
  remotely by SFTP-uploading to `~/.local/bin/opencode` with an atomic
  temp-file + rename and a SHA-256 short-circuit so subsequent runs
  don't re-upload.  Bridges the gap while the iframe-embeddability fixes
  to opencode are being upstreamed.

Demo task:

- `packages/optio-demo/src/optio_demo/tasks/opencode.py` registers an
  `opencode-demo` task wired via `create_opencode_task`.  Defaults to
  local mode; set `OPTIO_OPENCODE_DEMO_SSH_HOST` (plus optional _USER,
  _KEY_PATH, _PORT) to run the same task over SSH.  The consumer
  prompt has the LLM print the hostname (so remote vs. local is
  visually obvious), ask for a favorite color, ship a deliverable
  containing 42 + the color, and append DONE to `./optio.log`.

Testing:

- 74 Python tests: types, prompt composer, log parser + path
  validation, host (LocalHost), install target / directory-name,
  full-stack local integration via a Python test-double for opencode
  web (happy / error / exit-before-done / invalid-path / non-UTF-8
  / callback-raises / cancellation / widget registration), remote
  integration via linuxserver/openssh-server (skip-on-no-docker).

AGENTS.md — root + optio-demo + new package-local cheatsheet describe
public API, log-file contract, operating modes, the binary-dir install
mechanism, and known MVP limits.

Author: csillag

AGENTS.md

@@ -43,6 +43,7 @@ must stay consistent with the package-level files.
 | 2 — Remote control | `optio-core[redis]` | Python | `pip install optio-core[redis]` |
 | 3 — REST API | `optio-api` | TypeScript | `npm install optio-api optio-contracts` |
 | 4 — React UI | `optio-ui` | TypeScript | `npm install optio-ui optio-contracts @tanstack/react-query react-i18next antd` |
+| 1+ — Opencode runner | `optio-opencode` | Python | workspace; runs `opencode web` as an optio task (local subprocess or remote via SSH) |
 
 Dependencies: Python requires `motor>=3.3.0`, `apscheduler>=4.0.0a5`, `quaestor`. Redis support: `redis>=5.0.0` (optional extra). TypeScript API requires `mongodb`, `ioredis`, `@ts-rest/core`. UI requires React 19+, Ant Design 5+.
 
@@ -343,6 +344,28 @@ Collection: `{prefix}_processes`
 
 ---
 
+## Python: optio-opencode
+
+Run `opencode web` as an optio task.  Public API:
+
+```python
+from optio_opencode import create_opencode_task, OpencodeTaskConfig, SSHConfig
+
+task = create_opencode_task(
+    process_id="my-task", name="My task",
+    config=OpencodeTaskConfig(
+        consumer_instructions="...",
+        opencode_config={...},     # passthrough to opencode.json
+        ssh=None,                  # None = local subprocess
+        on_deliverable=cb,
+    ),
+)
+```
+
+Full details: `packages/optio-opencode/AGENTS.md`.
+
+---
+
 ## TypeScript: optio-contracts
 
 Package: `optio-contracts`

packages/optio-demo/AGENTS.md

@@ -81,3 +81,11 @@ Environment variables (all optional, shown with defaults):
 - `MONGODB_URL` — `mongodb://localhost:27017/optio-demo`
 - `REDIS_URL` — `redis://localhost:6379`
 - `OPTIO_PREFIX` — `optio`
+
+## Opencode demo
+
+Task `opencode-demo` runs a short local opencode session that asks the
+human for a favorite color and ships a deliverable containing the
+color and the number 42.  Reference consumer for `optio-opencode`;
+exercises the full iframe + proxy + log-tail stack.  Requires opencode
+to be installed and authenticated on the developer's machine.

packages/optio-demo/pyproject.toml

@@ -11,6 +11,7 @@ requires-python = ">=3.11"
 dependencies = [
     "optio-core[redis]",
     "marimo>=0.9",
+    "optio-opencode",
 ]
 
 [tool.setuptools.packages.find]

packages/optio-demo/src/optio_demo/tasks/__init__.py

@@ -8,6 +8,7 @@
 from optio_demo.tasks.festival import get_tasks as festival_tasks
 from optio_demo.tasks.wakeup import get_tasks as wakeup_tasks
 from optio_demo.tasks.marimo import get_tasks as marimo_tasks
+from optio_demo.tasks.opencode import get_tasks as opencode_tasks
 
 
 async def get_task_definitions(services: dict) -> list[TaskInstance]:
@@ -18,4 +19,5 @@ async def get_task_definitions(services: dict) -> list[TaskInstance]:
         *festival_tasks(),
         *wakeup_tasks(),
         *marimo_tasks(),
+        *opencode_tasks(),
     ]

packages/optio-demo/src/optio_demo/tasks/opencode.py

@@ -0,0 +1,98 @@
+"""Reference demo task for optio-opencode.
+
+Defaults to local mode (per the design spec, Section 10); set the
+``OPTIO_OPENCODE_DEMO_SSH_HOST`` environment variable to run the same
+task via SSH on a remote host.  Relevant env vars (all optional except
+``_HOST``):
+
+- ``OPTIO_OPENCODE_DEMO_SSH_HOST`` — enables remote mode.
+- ``OPTIO_OPENCODE_DEMO_SSH_USER`` — default: ``$USER`` on the worker.
+- ``OPTIO_OPENCODE_DEMO_SSH_KEY_PATH`` — default: ``~/.ssh/id_ed25519``.
+- ``OPTIO_OPENCODE_DEMO_SSH_PORT`` — default: ``22``.
+
+The consumer prompt is the hostname-and-color-and-42 prompt described
+in the spec.  The deliverable callback surfaces the file contents back
+into the optio log channel so the human can visually confirm
+round-trip success.
+"""
+
+import os
+
+from optio_core.context import ProcessContext
+from optio_core.models import TaskInstance
+from optio_opencode import OpencodeTaskConfig, SSHConfig, create_opencode_task
+
+
+CONSUMER_PROMPT = (
+    "Tell me the hostname of the system you are running on. "
+    "Then ask the human about their favorite color, then ship a "
+    "deliverable containing the number 42 and the designated color. "
+    "Then signal completion by appending a `DONE` line to the "
+    "`./optio.log` file (writing `DONE` in the chat has no effect — "
+    "it must go into that file)."
+)
+
+
+def _resolve_ssh_config() -> SSHConfig | None:
+    """Build an SSHConfig from env vars, or None for local mode."""
+    host = os.environ.get("OPTIO_OPENCODE_DEMO_SSH_HOST")
+    if not host:
+        return None
+    user = (
+        os.environ.get("OPTIO_OPENCODE_DEMO_SSH_USER")
+        or os.environ.get("USER")
+        or "root"
+    )
+    key_path = os.environ.get(
+        "OPTIO_OPENCODE_DEMO_SSH_KEY_PATH",
+        os.path.expanduser("~/.ssh/id_ed25519"),
+    )
+    port_raw = os.environ.get("OPTIO_OPENCODE_DEMO_SSH_PORT", "22")
+    try:
+        port = int(port_raw)
+    except ValueError:
+        raise RuntimeError(
+            f"OPTIO_OPENCODE_DEMO_SSH_PORT must be an integer, got {port_raw!r}"
+        )
+    return SSHConfig(host=host, user=user, key_path=key_path, port=port)
+
+
+def _make_on_deliverable(ctx: ProcessContext):
+    async def _cb(path: str, text: str) -> None:
+        ctx.report_progress(
+            None,
+            f"deliverable {os.path.basename(path)}: {text[:200]}",
+        )
+    return _cb
+
+
+def get_tasks() -> list[TaskInstance]:
+    async def _execute(ctx: ProcessContext) -> None:
+        config = OpencodeTaskConfig(
+            consumer_instructions=CONSUMER_PROMPT,
+            opencode_config={},
+            # Resolved at execution time so env-var changes between
+            # worker restarts are picked up without reinstalling the task.
+            ssh=_resolve_ssh_config(),
+            on_deliverable=_make_on_deliverable(ctx),
+        )
+        inner = create_opencode_task(
+            process_id="opencode-demo-inner",
+            name="opencode demo inner",
+            config=config,
+        )
+        await inner.execute(ctx)
+
+    return [
+        TaskInstance(
+            execute=_execute,
+            process_id="opencode-demo",
+            name="Opencode demo",
+            description=(
+                "Opencode session asking for a color and shipping a "
+                "deliverable. Set OPTIO_OPENCODE_DEMO_SSH_HOST to run "
+                "remotely; otherwise runs locally."
+            ),
+            ui_widget="iframe",
+        )
+    ]

packages/optio-opencode/.gitignore

@@ -0,0 +1,5 @@
+tests/ssh-keys/
+tests/scenario.txt
+*.egg-info/
+__pycache__/
+.pytest_cache/

packages/optio-opencode/AGENTS.md

@@ -0,0 +1,109 @@
+# optio-opencode — Agent Cheatsheet
+
+Run `opencode web` as an optio task.  Either a local subprocess or a
+remote host reached over SSH; the optio dashboard embeds opencode's UI
+via the widget proxy.
+
+Full design: `docs/2026-04-22-optio-opencode-design.md`.
+
+## Public API
+
+```python
+from optio_opencode import (
+    create_opencode_task,
+    OpencodeTaskConfig,
+    SSHConfig,
+    DeliverableCallback,
+)
+
+async def on_file(path: str, text: str) -> None:
+    ...
+
+task = create_opencode_task(
+    process_id="my-task",
+    name="My task",
+    config=OpencodeTaskConfig(
+        consumer_instructions="...",      # prepended with optio-opencode's base prompt
+        opencode_config={"model": "..."},  # passthrough to opencode.json
+        ssh=None,                          # None = local subprocess
+        on_deliverable=on_file,
+        install_if_missing=True,
+    ),
+    description="optional",
+)
+```
+
+The returned `TaskInstance` has `ui_widget="iframe"` baked in.
+
+## Log-file contract
+
+optio-opencode tells opencode (via AGENTS.md) to append one line per
+event to `./optio.log` with keywords:
+
+- `STATUS: [N%] <msg>`
+- `DELIVERABLE: <path>`
+- `DONE[: summary]`
+- `ERROR[: message]`
+
+The Python side tails the file, dispatches by keyword, SFTPs
+deliverable files back, decodes UTF-8, and invokes `on_deliverable`.
+DONE / ERROR terminate the session; other keywords flow through as
+progress updates / log entries.
+
+## Operating modes
+
+- **Local**: `asyncio.create_subprocess_exec("opencode", "web", ...)`.
+  Workdir is a `tempfile.mkdtemp`.  Expects opencode pre-installed
+  (or use `OPTIO_OPENCODE_BINARY_DIR`, below).
+- **Remote**: single asyncssh connection multiplexes exec (install,
+  launch, `tail -F`, teardown), SFTP, and local port forward.  Workdir
+  is `/tmp/optio-opencode-<uuid>/` on the remote.
+
+## Shipping a specific opencode binary
+
+Set `OPTIO_OPENCODE_BINARY_DIR` in the worker's environment to a
+directory matching opencode's build layout (i.e. containing per-target
+subdirs like `opencode-linux-x64/bin/opencode`, `opencode-darwin-arm64/
+bin/opencode`, `opencode-linux-x64-baseline-musl/bin/opencode`, …).  When
+set, optio-opencode:
+
+1. Detects the target host's OS / arch / libc / AVX2 via `uname`, `ldd`
+   and `/proc/cpuinfo` (detection mirrors opencode's upstream install
+   script so the subdir name is the one opencode's build would emit).
+2. Resolves the matching binary inside `OPTIO_OPENCODE_BINARY_DIR`.
+3. **Local mode:** runs that binary directly (bypasses any `opencode`
+   on PATH).
+4. **Remote mode:** SFTP-uploads the binary to `~/.local/bin/opencode`
+   on the remote host (atomic via temp-file + rename), skipping the
+   upload when the existing file's SHA-256 already matches.  Launches
+   via the absolute path, so the user doesn't need `~/.local/bin` on
+   their PATH for optio-opencode to work (though they'll benefit from
+   having it on PATH for later manual invocations).
+
+When the env var is unset, behavior falls back to the previous scheme:
+local mode expects `opencode` on PATH, remote mode runs the upstream
+curl installer if `opencode` is missing.
+
+This is a bridge feature for shipping an iframe-embeddability fork of
+opencode until those fixes land upstream; once upstream ships, the env
+var's only remaining use is pinning to a specific build.
+
+## Testing
+
+Unit + local integration: `pytest tests/` (needs MongoDB via Docker).
+
+Remote integration: `pytest tests/test_session_remote.py` — skips on
+machines without Docker; brings up `linuxserver/openssh-server` on
+`127.0.0.1:22222`.
+
+## Known limits (MVP)
+
+- SSH auth is key-path only; no agent, inline keys, or passwords.
+- No host-key verification (`known_hosts=None`).
+- Fail-fast on SSH drop; no reconnect.
+- Text deliverables only (non-UTF-8 files are skipped, not delivered).
+- Grace-period sensitive: teardown can exceed 5 s; host apps running
+  slow / remote sessions should call
+  `optio_core.shutdown(grace_seconds=30)`.
+
+Deferred items live in spec Section 11.

packages/optio-opencode/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "optio-opencode"
+version = "0.1.0"
+description = "Run opencode web as an optio task; local subprocess or remote via SSH."
+license = "Apache-2.0"
+requires-python = ">=3.11"
+dependencies = [
+    "optio-core",
+    "asyncssh>=2.14",
+    "aiofiles>=23.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

packages/optio-opencode/src/optio_opencode/__init__.py

@@ -0,0 +1,26 @@
+"""optio-opencode — run opencode web as an optio task."""
+
+import logging as _logging
+
+from optio_opencode.session import create_opencode_task, run_opencode_session
+from optio_opencode.types import (
+    DeliverableCallback,
+    OpencodeTaskConfig,
+    SSHConfig,
+)
+
+# asyncssh emits per-connection / per-channel INFO lines ("Opening SSH
+# connection...", "Received channel close", etc.) that flood the worker's
+# stdout once an SSH-backed opencode session starts.  Quiet it down by
+# default.  Consumers that want the verbose trace can override:
+#
+#     logging.getLogger("asyncssh").setLevel(logging.INFO)
+_logging.getLogger("asyncssh").setLevel(_logging.WARNING)
+
+__all__ = [
+    "create_opencode_task",
+    "run_opencode_session",
+    "DeliverableCallback",
+    "OpencodeTaskConfig",
+    "SSHConfig",
+]