@mseep/open-computer-use 1.0.0

package/docs/future-architecture/adr/0009-external-protocol-dialects.md

@@ -0,0 +1,94 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+# ADR-0009 — L4 external surface: MCP primary, optional adapter dialects
+
+- **Status:** Proposed
+- **Date:** 2026-05-18
+- **Related:** [ADR-0005](./0005-mcp-as-control-plane-gateway.md), [ADR-0008](./0008-internal-grpc-external-rest-mcp.md), [research/18](../research/18-open-webui-terminals-observed.md)
+
+## Context
+
+We have one external protocol today (MCP at `/mcp`) and a confirmed requirement that **multiple clients reach an identical capability surface**: Open WebUI, n8n, Claude Desktop, LiteLLM, OpenAI Agents SDK. Skills must be portable across all of them — a tool that works in one client and not another splits the surface and is rejected by definition (see [`COMPARISON.md`](../../COMPARISON.md), [`MCP.md`](../../MCP.md)).
+
+Two distinct external-protocol pressures have emerged:
+
+1. **Open WebUI native UX.** Open WebUI ships a native "terminal connection" mechanism with embedded file browser (`FileNav`), embedded xterm.js (`XTerminal`), and OpenAPI-driven tool injection. To use it, a server must speak either the single-terminal wire contract (`open-webui/open-terminal`) or the orchestrator wire contract (`open-webui/terminals`). See [research/18](../research/18-open-webui-terminals-observed.md) §3 for the contract.
+2. **OpenAI-compatible API.** A non-trivial fraction of integration requests assume `/v1/chat/completions`. Not blocking today, but recurring.
+
+The question is whether L4 should expose only `/mcp` or accept additional external dialects as adapters.
+
+## Decision
+
+- **MCP remains the only frozen, primary user-facing contract** ([ADR-0005](./0005-mcp-as-control-plane-gateway.md) stands).
+- **Additional external dialects may be added as L4 adapters** over the same internal connect-go RPC ([ADR-0008](./0008-internal-grpc-external-rest-mcp.md)), under three conditions enforced per dialect:
+  1. **Skill parity.** Every skill we ship MUST behave identically through the dialect and through MCP. If a skill cannot be expressed losslessly in the dialect, the dialect is not added.
+  2. **No coupling to dialect-specific clients.** Removing the adapter must not affect any other client.
+  3. **Wire contract must be stable.** If the dialect's wire format belongs to an upstream we don't control, the upstream's compatibility guarantees must be acceptable; otherwise pin and document supported version ranges.
+- **No adapter is committed by this ADR.** Each dialect is gated on its own validation gate (see Verification below).
+
+```text
+                  ┌─── /mcp                        Primary, frozen        (n8n, Claude Desktop, LiteLLM, OpenAI Agents SDK)
+L4 (Go) ──────────┼─── /api/v1/policies, /p/...    Proposed adapter       Open WebUI orchestrator dialect, status Hypothesis
+                  ├─── /v1/chat/completions        Proposed adapter       OpenAI-compatible, status Hypothesis
+                  └─── /admin/*                    Operator UI            REST, ADR-0008
+```
+
+## Rationale
+
+- **One internal contract, many external surfaces** is the same shape as ADR-0008's internal/external split — just extended to external. The cost of adding a dialect is bounded by the adapter; the cost of NOT being able to add one is permanent client lock-in.
+- **MCP as the parity floor.** Because MCP is the lowest-common-denominator protocol across all current target clients, locking MCP as the source of truth guarantees portability automatically. Any adapter that cannot match MCP's capability is by construction worse than the floor and is rejected.
+- **Adapter, not branch.** Dialects do not fork the tool set, do not add MCP-incompatible methods, and do not reshape the sandbox lifecycle. An adapter that needs internal RPC changes is no longer an adapter — it's a fork — and falls outside this ADR.
+
+## What this ADR does NOT do
+
+- It does **not** approve adding the Open WebUI dialect. That hypothesis lives in [research/18](../research/18-open-webui-terminals-observed.md) §5 with five explicit open questions; until they are answered the dialect is not built.
+- It does **not** approve adding an OpenAI-compatible dialect. Same status.
+- It does **not** change the MCP contract.
+- It does **not** authorise dropping the existing Open WebUI tool + filter integration. That decision is downstream of skill-parity validation per condition 1.
+
+## Consequences
+
+**Positive:**
+- Adapters become an explicit, bounded extension mechanism — not ad-hoc patches scattered across the codebase.
+- Conditions 1–3 make "should we add dialect X?" answerable with a checklist instead of a debate.
+- Skill portability is structurally enforced: anything that breaks MCP parity is out by definition.
+
+**Negative:**
+- Each adapter adopted is permanent surface area to maintain. The decision to add must include the decision to maintain.
+- Some upstream wire contracts (notably the Open WebUI orchestrator dialect) are at early version numbers and may break between releases. Adapters against them need a supported-version-range policy.
+
+**Neutral:**
+- Phase 6 L4 framework choice (HTTP router, middleware) must support multiple route trees mounted on the same connect-go core. Not a constraint on connect-go itself — every candidate router meets this.
+
+## Alternatives considered
+
+### MCP-only forever
+- **Pro:** Smallest surface; zero adapter maintenance.
+- **Con:** Locks us out of native UX in clients that don't speak MCP first-class. Open WebUI patches and our `computer_link_filter` then have to evolve in lockstep with upstream — the patch-maintenance burden grows with every Open WebUI release.
+- **Verdict:** Acceptable today; this ADR keeps it as the default by requiring per-dialect justification.
+
+### One adapter per client, deeply coupled
+- **Pro:** Each client gets its perfect UX.
+- **Con:** N adapters × M clients explosion; condition 1 (skill parity) becomes impossible to enforce; internal surface starts to bend toward dialects.
+- **Verdict:** Rejected.
+
+### Fork MCP with our own extensions
+- **Pro:** Single protocol, richer capability.
+- **Con:** Breaks every off-the-shelf MCP client. Loses the parity floor.
+- **Verdict:** Rejected by ADR-0005.
+
+## Verification
+
+For each proposed adapter, before it is built:
+
+1. **Skill-parity matrix.** Every skill in `skills/` must have a documented mapping that produces equivalent model behaviour via the dialect as via MCP. Discrepancies → adapter not built.
+2. **Removal test.** Acceptance includes a CI configuration that builds and runs L4 with the adapter disabled; all other clients must still pass their integration tests unchanged.
+3. **Version-range policy.** If the adapter speaks an upstream-owned wire format, the supported upstream version range is documented in the adapter's README and pinned in CI.
+4. **Phase placement.** Adapters land no earlier than Phase 6 (L4 rewrite). Adding adapters to the current Python `computer-use-server` is not authorised by this ADR — that would create migration debt against ADR-0001.
+
+## Migration notes
+
+- Phases 1–5: unchanged. Single MCP endpoint stays on Python.
+- Phase 6: L4 framework selection must explicitly preserve the option to mount additional route trees. No adapter built yet.
+- Phase 6+: adapters added one at a time, each gated by the conditions above.

package/docs/future-architecture/adr/0010-lambda-as-inspiration-not-runtime.md

@@ -0,0 +1,86 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+# ADR-0010 — AWS Lambda: inspiration, not runtime
+
+- **Status:** Accepted
+- **Date:** 2026-05-18
+- **Deciders:** project owner
+- **Supersedes:** —
+- **Superseded by:** —
+- **Related:** [ADR-0003](./0003-docker-poc-first-then-k8s.md), [ADR-0004](./0004-pluggable-runtime-via-runtimeclass.md), [references.md](../references.md), [research/05](../research/05-firecracker.md)
+
+## Context
+
+AWS Lambda recurs across the reference catalogue. It is the original consumer of Firecracker; its MicroManager pool is the design lineage behind the two-tier placement plane we adopt at L4/L1; its cold-start economics underwrite the snapshot-pool pattern we evaluate at Phase 10.
+
+This recurrence has begun to confuse the architecture conversation. "Lambda" appears in [`references.md`](../references.md) as a Firecracker provenance note and in [`research/05`](../research/05-firecracker.md) as a foundation. Neither document makes the explicit claim that we will or won't run on Lambda.
+
+This ADR makes the claim and closes the question.
+
+## Decision
+
+**Open Computer Use will not run on AWS Lambda or AWS Fargate.** Lambda is treated as a **design reference**, not a deployment target. The patterns we borrow are explicit, named, and bounded; nothing beyond them transfers.
+
+### What "inspiration" means concretely
+
+We adopt **patterns** from the Lambda design lineage:
+
+| Pattern | How it lands for us | Where |
+|---|---|---|
+| Firecracker as a microVM tier with the smallest attack surface | `kata-fc` runtime tier | [`research/05`](../research/05-firecracker.md), [`architecture/04-layer2-runtimes.md`](../architecture/04-layer2-runtimes.md), Phase 9 |
+| Two-tier control split (host-side router + in-guest supervisor) | L4 (Go) + L1 (Rust, [ADR-0002](./0002-guest-agent-language-go.md)) with WS over vsock | Phase 7 |
+| Frozen-snapshot pool with block-device hot-swap on resume | Snapstart-style cold-start optimization | Phase 10 |
+| Per-session VM isolation (no reuse across tenants) | RuntimeClass-driven, per-tenant namespace | [ADR-0004](./0004-pluggable-runtime-via-runtimeclass.md), `architecture/07-security.md` |
+
+### What we are explicitly **not** adopting
+
+- **The deployment substrate.** We do not deploy on `aws-lambda` (function-as-a-service) or `aws-fargate` (managed-task). The runtime substrate is Kubernetes ([ADR-0003](./0003-docker-poc-first-then-k8s.md)) plus a RuntimeClass-pluggable microVM tier ([ADR-0004](./0004-pluggable-runtime-via-runtimeclass.md)).
+- **Per-invocation billing model.** Our sandboxes are session-shaped, not request-shaped. The cost model is per-session, per-RuntimeClass — not per-100ms-CPU-burst.
+- **15-minute hard wall.** Lambda's 15-minute invocation cap is a non-starter for Computer Use sessions. We need sessions that survive multi-hour LLM-driven work.
+- **Lambda's specific orchestrator.** Lambda's placement router is a custom AWS system. We are not cloning it; k8s + a custom L4 control plane do the same job at our scale.
+- **Lambda Extensions / Layers / SnapStart-the-AWS-product.** These are AWS-product names. We use the *technique* SnapStart describes without using AWS's implementation.
+
+## Rationale
+
+- **Scale mismatch.** Lambda's design optimizes for millions of short serverless invocations. We target 100–10K concurrent long-lived sandboxes. k8s + RuntimeClass remains the right fit; serverless infra is over-engineered for the bottom and under-fit for the top.
+- **Workload shape mismatch.** Computer-Use sessions are stateful, long-running, and need predictable resource ceilings (memory for screencast frame buffers, CPU for browser rendering). Lambda's stateless-by-default, scale-on-bursts model fights every assumption.
+- **Self-hosting requirement.** A serious chunk of the addressable user base self-hosts. Lambda is not portable; k8s is.
+- **Vendor lock.** Lambda ties us to AWS as the deployment substrate. The architecture explicitly aims for AWS, GCP, on-prem RKE2, and Docker Compose ([ADR-0001](./0001-control-plane-language-go.md) Context).
+- **Open-source posture.** The project is open-source ([ADR-0006](./0006-no-agpl-no-bsl-dependencies.md) on license hygiene). Optimizing for a single-cloud managed runtime is at odds with that posture.
+
+## Consequences
+
+**Positive:**
+- The Lambda question is closed. Future debate about "should we go serverless?" can be answered by linking to this ADR.
+- Phase 9 / Phase 10 design discussions can use Lambda as a reference point without confusion about commitment.
+- `references.md` gets one explicit Lambda paragraph; everything else cross-links to it.
+
+**Negative:**
+- We carry the operational cost of running k8s ourselves. Acceptable per [ADR-0001](./0001-control-plane-language-go.md), [ADR-0003](./0003-docker-poc-first-then-k8s.md).
+- Snapshot-pool engineering at Phase 10 is non-trivial without Lambda's MicroManager doing it for us. Acceptable; it's also what makes the system buildable outside AWS.
+
+**Neutral:**
+- A future small-scale deployment optimization could in theory wrap sandboxes in Fargate Tasks. This ADR does not preempt that; it forbids it as the *default*.
+
+## Alternatives considered
+
+### Run on AWS Lambda
+- **Verdict:** rejected. 15-minute cap, stateless-by-default, no Kubernetes affinity, vendor lock. Doesn't fit the workload.
+
+### Run on AWS Fargate
+- **Pro:** managed task substrate, no node ops.
+- **Con:** opaque scheduler, no RuntimeClass control, no microVM tiering (Firecracker is there but you can't pick), still AWS-only.
+- **Verdict:** rejected as the *default*. Possibly viable as a future "managed tier" for AWS-only users; that would land in its own ADR.
+
+### Adopt Lambda's MicroManager pattern wholesale
+- **Pro:** proven at scale.
+- **Con:** rebuilds Lambda's orchestrator on our side — a huge engineering bill for problems we don't have yet at our scale.
+- **Verdict:** rejected. We adopt the **patterns** ("two-tier control", "snapshot pool", "per-session isolation") without rebuilding the orchestrator. k8s + a custom L4 are enough.
+
+## Verification
+
+- `references.md` contains a single "Lambda framing" subsection that cross-links to this ADR.
+- `architecture/04-layer2-runtimes.md` mentions Firecracker's Lambda lineage exactly once, with a back-link here.
+- Search the docs tree for "Lambda" — every hit either points to this ADR, the references paragraph, or a research digest. No standalone claims.
+- Phase 9 / Phase 10 PRs that touch microVM choice or snapshot pooling tick the **"ADRs reviewed"** checklist in [`.github/PULL_REQUEST_TEMPLATE.md`](../../../.github/PULL_REQUEST_TEMPLATE.md) with `ADR-0010` listed.

package/docs/future-architecture/adr/0011-kata-as-first-class-dind-runtime.md

@@ -0,0 +1,84 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+# ADR-0011 — Kata Containers as a first-class DinD runtime
+
+- **Status:** Accepted
+- **Date:** 2026-05-20
+- **Supersedes:** the runtime phasing in ADR-0004 *Consequences* ("Phase 9 adds `kata-fc` / `kata-ch`")
+- **Issue:** [#116](https://github.com/Wide-Moat/open-computer-use/issues/116)
+
+## Context
+
+The `computer-use-server` Helm chart shipped with [Sysbox](https://github.com/nestybox/sysbox)
+as its default — and only documented — DinD runtime. Sysbox lets the inner
+`dockerd` run unprivileged, which is why the chart couples
+`runtimeClassName` to `dind.securityContext.privileged`.
+
+Sysbox no longer works on **containerd 2.x**, which ships with current
+Kubernetes distributions (RKE2 / k3s / kubeadm ≥ 1.34). Sysbox fails there with
+mount-permission errors. Docker acquired Nestybox; public Sysbox releases are
+frozen at containerd 1.x compatibility and there is no upstream fix on the
+horizon. Any operator on a modern cluster cannot deploy the chart at all.
+
+ADR-0004 anticipated Kata, but only as a *Phase 9* item for the future native
+backend. The Sysbox EOL makes that timeline untenable: Kata is needed **now**,
+in the current DinD-based chart, just to keep the chart installable.
+
+## Decision
+
+Make **Kata Containers (`kata-qemu`)** a first-class, fully documented runtime
+for the current Helm chart, alongside Sysbox.
+
+Concretely:
+
+1. **`dind.privileged`** — a new explicit override (default `null` = legacy
+   auto-derivation). Kata requires `privileged: true` because `dockerd` needs
+   `CAP_NET_ADMIN`/`CAP_NET_RAW` for the iptables NAT chain. This is safe under
+   Kata — capabilities are confined to the microVM.
+2. **`dind.kataInit`** — a chart-templated entrypoint wrapper (shipped in a
+   ConfigMap, **not** a custom published image) that prepares the Kata guest:
+   installs `fuse-overlayfs`, creates `/dev/fuse`, formats/mounts the Block
+   PVC, and runs the cgroup-v2 PID-1 evacuation shim.
+3. **`persistence.varLibDocker.persistentVolume`** — optional Block-mode PVC for
+   `/var/lib/docker`. Under Kata this is required for workloads needing
+   `security.capability` xattrs (the virtio-fs root drops them — CVE-2021-20263).
+4. All Kata machinery is gated behind `dind.kataInit.enabled: false` so existing
+   Sysbox installs render byte-identically.
+
+## Rationale
+
+- **Chart-templated wrapper over a custom image.** A published
+  `docker:dind + fuse-overlayfs` image would burden maintainers with a build
+  pipeline, CVE patching, and multi-arch releases. `fuse-overlayfs` is a single
+  `apk add` performed idempotently at container start; the wrapper lives in the
+  chart, is fully visible in `helm template`, and is testable in CI without a
+  cluster. A pre-baked image remains documented as an optional alternative.
+- **`fuse-overlayfs`, not `overlay2`.** `overlay2` cannot mount on the Kata
+  virtio-fs guest root ([kata-containers#1888](https://github.com/kata-containers/kata-containers/issues/1888)).
+  `fuse-overlayfs` is a userspace filesystem with full xattr support.
+- **Block PVC for `/var/lib/docker`.** A filesystem PVC reaches the guest over
+  virtio-fs and drops xattrs; a Block PVC arrives as virtio-blk, so a real ext4
+  filesystem inside the guest preserves them.
+- **Backward compatibility is non-negotiable.** Sysbox users must see no
+  behavior change — enforced by `null` defaults and a CI render regression check.
+
+## Consequences
+
+- The chart now documents two runtimes; `docs/kata-runtime.md` is the Kata
+  runbook (install kata-deploy → configure → deploy → verify → troubleshoot).
+- Operators on containerd 2.x have a supported path; Sysbox remains supported
+  for containerd 1.x clusters.
+- The vendored-chart patches that yambr ran in production are upstreamed, so
+  that fork can be retired.
+- This is validated in a production deployment but **cannot** be exercised in
+  OCU CI (no Kata-capable runners); CI covers chart rendering only.
+
+## Alternatives
+
+- **Document Kata without chart changes** — rejected; operators would still
+  hand-patch the `dindPrivileged` helper and hand-roll the guest init.
+- **Ship a custom dind image** — rejected as the default (maintenance burden);
+  kept as a documented opt-in alternative.
+- **Wait for the Phase 9 native-Pod backend** — rejected; leaves every
+  containerd 2.x cluster unable to install the chart in the meantime.