agent-trellis 0.5.2 → 0.6.2

package/docs/research.md

@@ -179,6 +179,172 @@ Reverse-engineered directly from the installed binary
   genuine code, not config templating — see
   [`src/adapters/pi/`](../src/adapters/pi).
 
+## Cross-machine / cloud sharing — surveyed 2026-09-15, future direction confirmed
+
+Trellis today is single-machine-only (`docs/architecture.md`'s "Global vs.
+workspace scope" section deliberately scopes out project-local merge, but
+says nothing about cross-*machine* sync — that's a separate, real gap, not
+something already decided against). **Cloud/cross-machine sharing is
+confirmed as a future requirement, not a maybe** — the open question is
+sequencing and substrate choice, not whether to build it.
+
+Two genuinely different problems got explored together and need to stay
+separate in any design that follows:
+
+1. **Keeping `~/.trellis` canonical source consistent across a person's own
+   multiple machines** (config sync — small files, low write frequency).
+2. **Coordinating agent execution across machines / providing a shared
+   runtime substrate** (running-process orchestration — a different problem
+   with different failure modes, not a natural extension of #1).
+
+### `cloudflare/computer` — evaluated, not adopted
+
+[cloudflare/computer](https://github.com/cloudflare/computer) gives an
+agent a durable virtual filesystem (SQLite inside a Durable Object,
+`@cloudflare/dofs`) plus a pluggable execution backend (container FUSE
+mount, isolate shell via `just-bash`, or isolate JS in a Dynamic Worker) —
+one `workspace.runtime.exec(source, { backend })` entrypoint. Aimed at
+SaaS-scale "give every concurrent agent task its own cheap, horizontally-
+scalable workspace," not at syncing a handful of config files between a
+person's own laptop and desktop.
+
+Explicitly **PREVIEW ONLY** per the project's own README: "APIs are
+unstable... NOT suitable for production use at this time." That alone
+rules it out as a dependency today, separate from the architectural
+mismatch.
+
+The one reusable idea, if problem #1 above is tackled with a real sync
+protocol later rather than git: `@cloudflare/dofs`'s sync building blocks
+(`applyChanges`/`stageBlob`/`materialiseChange`/`fetchChanges`/
+`buildManifest`/`currentRev`/watermark cursors) are a clean change-set +
+content-addressed-blob + watermark model worth studying as a *design
+reference*, not a dependency — adopting the package itself means adopting
+Cloudflare Durable Objects as a required backend, which is a vendor
+commitment Trellis has never needed for anything else it does (everything
+else runs as a local CLI against local files).
+
+**Recommendation for problem #1**: start with git as the sync transport
+(`~/.trellis` is already just markdown/YAML — a natural git repo; `trellis
+sync` gains a `git pull --rebase`/`git push` step, conflicts resolved by
+git's own mechanism) before building or adopting any bespoke sync engine.
+Matches the project's own existing principle for MCP hub mode — "no engine
+switch in the type, only a URL" — apply the same discipline here: don't
+build sync-engine abstraction ahead of validating that git alone doesn't
+already solve it.
+
+### Letta Cloud's "Agent state" — evaluated as a hosted-state model, not adopted
+
+Surveyed 2026-09-16 after recognizing the shape from
+[letta-ai/letta-code](https://github.com/letta-ai/letta-code): Letta Cloud
+keeps an agent's memory, identity, and conversation history entirely
+server-side; any machine (laptop, Cloud VM, Mac Mini, GitHub Actions) can
+run the `letta server` harness against that same state
+([README](https://github.com/letta-ai/letta-code/blob/main/README.md),
+[Constellation docs](https://docs.letta.com/letta-code/constellation)).
+Confirmed by reading the actual mechanism, not just the marketing diagram:
+
+- **Attach is outbound-only.** `letta server --env-name "work-laptop"`
+  opens one outbound WebSocket to Letta Cloud — no inbound port, ever
+  ([BYOM docs](https://docs.letta.com/platform/computers/byom)). OAuth
+  device-flow credentials persist under `~/.letta/` so reconnects are
+  silent.
+- **"Teleportation" (moving execution between machines) is a sequenced
+  single-writer handoff, never concurrent.** The source machine finishes
+  its current tool call, stops accepting new work, and releases before
+  the destination starts; "a conversation can have only one teleport in
+  flight at a time," and a failed handoff leaves the conversation on the
+  source rather than in a split state
+  ([Teleportation docs](https://docs.letta.com/platform/computers/teleportation)).
+  Memory, message history, pending tool approvals, credentials, and
+  permission mode move with it; files, working directories, running
+  processes, and installed dependencies do not — the destination
+  reconstructs its own environment rather than receiving a filesystem
+  snapshot.
+- **Even with a fully hosted state store, Letta's own docs still tell
+  users to mirror agent memory to GitHub** via `/memory-repository` as a
+  backup. The vendor that built the hosted-state alternative does not
+  treat it as a substitute for a plain, git-friendly copy.
+
+**Not adopted as a model for Trellis's own cross-machine problem, and the
+reason is structural, not a maturity/cost judgment**: Letta's "agent
+state" is the runtime state of an agent Letta itself executes — its own
+first-party memory and conversation loop. Trellis has no equivalent to
+host: canonical (`~/.trellis`) is *configuration projected into* other
+vendors' agents (Claude Code, Codex, Kiro), whose own sessions, auth, and
+runtime state Trellis never touches and has no execution loop of its own
+to hand off. There is no "conversation" for a Trellis-hosted service to
+teleport — Trellis's job ends at writing correct config to disk on the
+one machine it's invoked on. Building a hosted canonical-state service to
+mirror Letta's shape would mean Trellis becoming a resident,
+account-backed service — the same "material shift... needs its own
+explicit sign-off" line `trellis-mcp-gateway-hosting`'s proposal.md
+already drew around operating so much as a spawned subprocess, applied
+here to something with a much larger blast radius (a user's actual
+configuration data, not a per-session child process).
+
+**Two mechanisms are worth recording anyway — not as new ideas to adopt,
+but as independent confirmation that designs already committed to
+elsewhere in this project land on the same shape a production
+multi-machine system converged on:**
+
+1. Outbound-only, no-daemon-to-babysit attach is exactly
+   `trellis-mcp-gateway-hosting`'s own shape (design.md D2/D13) — an
+   agent spawns `trellis mcp-gateway`, it connects out, it exits with the
+   session. Letta using the identical pattern for "any machine attaches
+   to hosted state" is evidence the shape generalizes, not a coincidence
+   worth re-deriving from scratch if problem #2 (a shared runtime
+   substrate) is ever built.
+2. Sequenced single-writer handoff — finish, release, then let the next
+   party proceed — is exactly the OAuth refresh lock's shape
+   (`trellis-mcp-gateway-hosting` design.md D16, `withServerLock`:
+   acquire, re-read to check whether the work is already done, act, or
+   defer). Same problem (two parties who might touch shared state at
+   once), same answer (serialize, never split), arrived at independently
+   in a completely different subsystem.
+
+**Standing recommendation unchanged**: git remains the right transport
+for problem #1. This survey is a reason to be confident in that choice,
+not a reason to revisit it — the hosted-state alternative was evaluated
+on its merits and excluded on structural grounds, and even its own
+vendor keeps a git-based fallback for the same category of data Trellis
+already treats git-friendly YAML/Markdown as the source of truth for.
+
+### Sandbox / execution substrate landscape — problem #2
+
+Surveyed for "a place agents actually run" rather than "a place config
+gets copied to":
+
+| Project | Model | License / status | Notes |
+|---|---|---|---|
+| [dagger/container-use](https://github.com/dagger/container-use) | MCP server; each agent gets an isolated container + its own git branch | Apache-2.0-adjacent, early/active | Works with *any* MCP-compatible agent, no vendor lock-in per its own README; `git checkout <branch>` to review any agent's work. Lightest-weight fit for Trellis's existing "MCP is the one place we write real integration code" model — could ship as a documented default MCP server entry with zero new adapter code, the same way `memory` (P6) was added |
+| [awslabs/cli-agent-orchestrator](https://github.com/awslabs/cli-agent-orchestrator) (CAO) | Local `cao-server` + per-agent isolated tmux sessions; supervisor/worker delegation; Web UI, HTTP API, PTY WebSocket; K8s deployment (shared workspace, per-pod state, credential delivery) | Apache-2.0, active (AWS) | **Directly supports Kiro CLI, Claude Code, and Codex CLI** — three of Trellis's four managed agents by name. Closest existing match to "run agents more smoothly + fleet management," and the closest existing candidate for problem #2 (cross-machine coordination) via its K8s deployment story. Not yet verified against Trellis's own canonical source/scope model — CAO has its own agent-profile concept, which is a second place "what an agent is configured to do" could live, the exact fragmentation class `docs/research.md`'s mcp-router incident (§ MCP aggregation) already warns about |
+| [daytonaio/daytona](https://github.com/daytonaio/daytona) | Firecracker-level sandbox infra, multi-language SDKs | Open-source repo, **but its own README states core development moved to a private codebase as of June 2026 — "no longer maintained"** | Ruled out: not an active open-source target to build on |
+| [e2b-dev/E2B](https://github.com/e2b-dev/E2B), [opensandbox-group/OpenSandbox](https://github.com/opensandbox-group/OpenSandbox) | Firecracker microVM / Docker+K8s one-shot code-execution sandboxes | E2B mostly managed (weak self-host story); OpenSandbox self-hostable | Both model "spin up a sandbox per code execution," not "keep a long-lived agent runtime consistent across a person's machines" — weaker fit than container-use/CAO for Trellis's actual use case |
+
+### Recommended path, not yet built
+
+1. **Cheapest, ships now, zero new adapter code**: document `container-use`
+   as an optional MCP server entry in `schema/servers.example.yaml`
+   (same pattern P6 used for `memory`) — every managed agent gets isolated,
+   disposable containers per task through the exact mechanism Trellis
+   already has for distributing MCP config. No cross-machine claim yet,
+   just "agents run more safely/smoothly," which is this session's own
+   stated ask.
+2. **Validate cross-machine config sync with git before building anything
+   bespoke** (problem #1) — smallest possible experiment, no new runtime
+   dependency.
+3. **Evaluate CAO as the substrate for problem #2** (cross-machine
+   coordination) only after #1 and #2 are separately validated as real,
+   distinct needs — specifically check whether its agent-profile model can
+   be made to read Trellis's canonical source rather than becoming a
+   second source of truth. This is new-project-scale work, not an
+   incremental Trellis phase — should get its own openspec proposal with
+   explicit success criteria before any code is written.
+
+None of the above is built yet. This section exists so the next design
+pass starts from "what was already checked" instead of re-surveying the
+same ground.
+
 ## Codex — three hard constraints learned by breaking them
 
 All three below came from real incidents, not upfront design, and any Codex

package/docs/roadmap.md

@@ -951,6 +951,24 @@ tests passing.
 | P18 | ✅ `envAliases`: a migrated `${NAME}` env reference whose name differs from its own key (found via live dogfooding — a real Notion MCP server crashing pi after migrate, not a hypothetical) is now recognized as a reference, not silently shipped as literal unexpanded placeholder text. New `McpServerDef.envAliases` field, threaded through migrate-read (both JSON and Codex TOML sources), every adapter's write path, the pre-write unresolvable-env refusal guard, the pi bridge's runtime resolution, and canonical's own `env_aliases`/`envAliases` on-disk round-trip | P16 |
 | P19 | ✅ Migrate reclassify-repair: found immediately after P18 shipped — re-running migrate on data migrated *before* a classification fix didn't pick the fix up at all, since `planMcpServer`'s conflict check was plain `deepEqual` (any structural difference, real customization or not, was refused as "resolve by hand"). New narrow `isSafeReclassification` check + `"reclassify"` migrate action: applied automatically when a value only moved between `staticEnv`/`env`/`envAliases` while resolving to the exact same literal/reference text, everything else identical; any real difference still conflicts, unchanged. Verified for real on this machine: `migrate --from claude-code --only mcp` correctly reclassified notion's stale entry and left all 8 other already-migrated servers untouched | P18 |
 | P20 | ✅ Memory extraction: closes P15's own explicitly-named "per-agent extraction into canonical remains a separate, open gap." New `trellis memory extract` — the reverse of `memory sync` — reads the shared graph's real, non-`trellis-memory` entities (the same ownership marker `memory sync` already uses to leave agent-created content untouched, read the other direction) and writes each as a new canonical `memories/*.md` file: readable markdown, not a serialization format, not meant to round-trip byte-for-byte back through `memory sync`. Same create/no-op/conflict discipline as every other Trellis write; not wired into `onboard`'s automatic chain (a deliberate, occasional action, like `migrate`) | P15 |
+| P21 | ✅ MCP gateway hosting: collapses each agent's MCP config to ONE native stdio entry (`trellis mcp-gateway --agent <id>`) that Trellis itself spawns — no Docker, no daemon, no lifecycle command. Four third-party gateways were evaluated and excluded on hard constraints (MetaMCP is Docker-only; mcp-local-hub is Windows-only today; `@samanhappy/mcphub` is a 43-dependency authenticated web product with no importable SDK surface; `@pcandido/mcphub` has correct OAuth but zero `${VAR}` expansion in its stdio `env`, verified by inspecting what a spawned child actually received — adopting it would mean plaintext secrets or a second resolution path outside `secrets audit`). Built instead on `pi-bridge`'s already-proven connect logic, extracted to `src/lib/mcpConnect.ts`, behind a `GatewayBackend` seam so the confirmed next step — one shared service for all agents, with the per-session process becoming a thin MCP-over-Unix-socket client — is a substitution at one construction site, with every agent's written config identical either way. Includes Trellis's own OAuth client (RFC 8414/9728 discovery, RFC 7591 DCR, RFC 7636 PKCE S256, refresh), tested against a hand-built Authorization Server that *enforces* those RFCs rather than rubber-stamping them; tokens live 0600 one-file-per-server outside canonical, never the OS keychain (macOS `security add-generic-password` measurably fails exit 152/154 with no GUI session — the gateway's exact context). Two bugs the design caught before shipping: the MCP SDK's stdio transport reports no EOF, so without explicit teardown every agent session would leak a gateway plus its whole upstream process set; and concurrent OAuth refresh silently kills a rotated refresh token, so it is serialized by a per-server lock. Remaining: the shared service itself (v2) | P2 |
+| P22 | ✅ Onboard closed loop: onboard used to stop the moment files were written, never checking whether any of it took effect, and never telling the user how the run went — a real run with a genuine sync conflict still ended its printed output on a later stage's unrelated green line. Two distinct fixes, not one: a **self-verification re-plan** (the mechanism that actually closes the loop) runs `sync`/`mcp sync` a second time, dry-run, immediately after their real apply, and treats anything still outstanding as its own blocking finding — `trellis doctor` was tried first and rejected for this job, since its six detectors compare agents against each other and never read canonical, so they cannot prove a write took effect even in principle. Doctor still runs, last, as a secondary whole-machine health scan (never `--probe-mcp` — the worst moment to spawn every configured MCP server is a user's first run of this command), with findings on an unmanaged agent demoted to a warning rather than hidden. Every stage's conflicts and findings normalize into one `VerdictItem[]`, printed as a terminal verdict block that is always the last thing on screen and always agrees with the exit code, each blocking item carrying a concrete remediation instead of a restatement of the problem. Also adds stage progress to stderr (never stdout, so `onboard > report.txt` stays exactly the report) and, on a real terminal, a `--dry-run` that ends by offering to apply (declining is the default; accepting re-plans against current state rather than replaying a now-stale preview) | P0 |
+| P23 | ✅ Onboard MCP mode + memory toggle: closes the last hand-editing gap — turning on gateway or hub mode, or the shared memory server, meant directly editing `~/.trellis/mcp/servers.yaml`'s top-level `hub`/`gateway` keys or its commented-out `memory:` example, since no command wrote them (`trellis mcp add`'s flags are all per-server). New `writeMcpModeYaml` in `src/core/canonical.ts` (`Document`-based, mirrors `upsertServerYaml`'s comment-preserving edit) plus `trellis onboard --mcp-mode direct\|hub\|gateway` (`--hub-url`, `--gateway-agents`) and `--memory on\|off` close it. Both follow onboard's existing managed-set idempotency shape rather than a new one: read current state first, omitting the flag always preserves it untouched with zero prompting — identical on a first run (nothing configured) and a later one (something already is), which is the actual point: one command for both, not a setup path and a separate reconfigure path. Deliberately flag-only, never an interactive picker (a mode change reroutes every managed agent's MCP transport at once — too wide a blast radius for Enter-mashing through a prompt sequence to trigger by accident); a one-line, non-prompting status line on a real terminal keeps the flags discoverable anyway. `--memory on` refuses outright if `"memory"` is already in `known_host_injected`, rather than writing a definition the very next `mcp sync` would refuse to propagate to any agent. Because mode/memory resolution runs before onboard's existing `mcp sync`/`memory sync` stages in the same chain, `trellis onboard --memory on` enables the server, syncs it to every managed agent, and populates it from canonical `memories/*.md` — all in one run | P17, P21, P22 |
+
+**Cross-machine / cloud sharing — confirmed future direction, not yet
+scoped as a phase.** Surveyed 2026-09-15 (`docs/research.md`'s "Cross-
+machine / cloud sharing" section): keeping `~/.trellis` consistent across
+a person's own multiple machines, and separately, providing a smoother/
+shared runtime substrate for agents to actually execute in, are both
+confirmed as real, wanted future capabilities — not yet broken into a
+numbered phase because the substrate choice needs its own validation pass
+first (git-based sync for the config side; `dagger/container-use` as a
+zero-new-code MCP server entry for safer per-task sandboxing; `awslabs/
+cli-agent-orchestrator` as a candidate for actual cross-machine
+coordination, evaluated only after the simpler pieces are proven). See
+`docs/research.md` for the full survey, including why `cloudflare/computer`
+and `daytonaio/daytona` were both evaluated and not adopted (preview-only
+API instability, and unmaintained-as-of-June-2026, respectively).
 
 No dates. This is scoped by verification milestones, not calendar time.
 Execution order for P11–P16: P11 → P12 → P13 → P14 → P15 → P16 — CRUD

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-trellis",
-  "version": "0.5.2",
+  "version": "0.6.2",
   "description": "A single source of capability for every coding agent — skills, MCP, subagents, memory, and secret policy, adapted natively into Claude Code, Codex, Kiro, and pi.",
   "license": "MIT",
   "author": "Paul Leo",
@@ -26,8 +26,9 @@
     "build": "tsc -p tsconfig.json && node scripts/build-pi-bridge.mjs",
     "dev": "tsx src/cli.ts",
     "typecheck": "tsc --noEmit",
-    "test": "tsx --test test/unit/**/*.test.ts",
-    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+    "pretest": "node scripts/build-pi-bridge.mjs",
+    "test": "tsx --test \"test/unit/**/*.test.ts\"",
+    "prepublishOnly": "npm run typecheck && npm run build && npm test"
   },
   "engines": {
     "node": ">=20"

package/schema/servers.example.yaml

@@ -35,8 +35,12 @@
 servers:
   # Default shared-memory backend (docs/research.md "Shared memory") —
   # @modelcontextprotocol/server-memory: zero-dependency, local JSON
-  # knowledge graph, MIT-licensed. Left commented out here because this
-  # exact example ALSO lists "memory" under known_host_injected below —
+  # knowledge graph, MIT-licensed. `trellis onboard --memory on` writes
+  # exactly this shape for you (src/commands/memory.ts's
+  # DEFAULT_MEMORY_SERVER_DEF) — uncommenting it by hand below is only
+  # for understanding what that flag does, not required to use it.
+  # Left commented out here because this exact example ALSO lists
+  # "memory" under known_host_injected below —
   # uncommenting both would self-collide (Trellis's own collision guard
   # would correctly refuse to write it). Which situation you're actually
   # in depends on your host:
@@ -44,8 +48,9 @@ servers:
   #     under this name — check with `trellis doctor` — leave this
   #     commented out and keep "memory" in known_host_injected below;
   #     you already have it, just not from a static definition.
-  #   - If your host injects nothing under this name, uncomment this
-  #     entry AND remove "memory" from known_host_injected below (it's
+  #   - If your host injects nothing under this name, run `trellis
+  #     onboard --memory on` (or uncomment this entry by hand) AND
+  #     remove "memory" from known_host_injected below (it's
   #     only there as inherited example content, not a fact about your
   #     environment) — that's what actually wires the default.
   # mem0/OpenMemory or a totalrecallai-class semantic-search server are
@@ -128,15 +133,32 @@ known_host_injected:
   - memory
   - mirasim
 
-# How the servers above reach the four agents. Omit this whole block for
+# How the servers above reach the four agents. Omit BOTH blocks below for
 # direct mode (today's default: every agent gets all N server definitions
 # written straight into its native config).
 #
-# Set it to route every agent through a single HTTP endpoint instead —
-# every adapter then writes exactly ONE entry (this URL), not N. What runs
-# behind the URL is not Trellis's concern: could be a self-hosted
-# github.com/ravitemer/mcp-hub instance, a hosted mcp-router account,
-# anything else speaking MCP over HTTP. No engine/product switch to
-# maintain — see docs/architecture.md "MCP hub mode".
+# `hub` routes an agent through a single HTTP endpoint you operate
+# somewhere else — the adapter then writes exactly ONE entry (this URL),
+# not N. What runs behind the URL is not Trellis's concern: could be a
+# self-hosted github.com/ravitemer/mcp-hub instance, a hosted mcp-router
+# account, anything else speaking MCP over HTTP. No engine/product switch
+# to maintain — see docs/architecture.md "MCP hub mode".
 hub:
   url: "http://127.0.0.1:37373/mcp"
+
+# `gateway` also collapses an agent to one entry, but what sits behind it
+# is a local subprocess Trellis itself spawns (`trellis mcp-gateway`), not
+# a URL you operate. It connects out to the servers above once, resolves
+# their secrets through secrets.policy.yaml exactly as direct mode does,
+# and exposes their tools as `<server>__<tool>`. There is nothing to start
+# or stop: the agent spawns it like any other stdio MCP server, and it
+# exits when the session ends.
+#
+# `gateway` and `hub` are independent and may both be present; gateway
+# wins for any agent it covers. Omit `agents:` — the normal case — and it
+# applies to every managed agent; list them to leave the rest in direct or
+# hub mode.
+#
+# gateway:
+#   enabled: true
+#   agents: [claude-code, codex]