agent-trellis 0.4.0 → 0.6.0

package/docs/research.md

@@ -120,6 +120,17 @@ clients." Mature, but needs Docker + an LLM key. Documented as the
 upgrade path for cross-machine or richer semantic memory, alongside
 `totalrecallai` as a second real option in that same category.
 
+Two commands, one direction each: `trellis memory sync` (canonical
+`memories/*.md` → the shared graph file) and `trellis memory extract`
+(the graph's own real, non-Trellis entities → new canonical files) —
+closing P15's own explicitly-named "per-agent extraction into canonical
+remains a separate, open gap." The two are not symmetric round-trips:
+canonical's memory model is one flat blob per file, the graph's native
+model is typed entities plus a relation graph, so extraction is a
+one-way, lossy-in-structure (not in substance) transcription, not a
+serialization format — see `docs/getting-started.md`'s `memory extract`
+section for the exact trade-off.
+
 ## Secrets (formalize existing practice, don't build new infra)
 
 The 2026 consensus across 1Password, Vault, Infisical writeups is uniform:
@@ -133,6 +144,19 @@ which was silently invalid). Trellis's contribution here is `trellis secrets
 audit` — a linter that fails a build if any adapter output contains a raw
 credential — not a new secret store.
 
+A third real incident during migrate-in: a source config's `${VAR}`
+reference doesn't always name itself (`OPENAPI_MCP_HEADERS:
+"${NOTION_OPENAPI_MCP_HEADERS}"`, a real Notion MCP server entry). Migrate's
+read path originally only recognized a same-named reference as one; a
+differently-named reference silently fell through as a literal, unexpanded
+value — harmless on Claude Code/Codex (both expand `${VAR}` themselves from
+their own native config format), but a hard crash on pi, whose bridge has no
+`${VAR}` runtime of its own and merges an unrecognized value verbatim.
+`McpServerDef.envAliases` (target key → source variable name) closes this:
+every agent's adapter renders it through the exact same reference mechanism
+`env` already uses, and the pi bridge resolves it through the exact same
+`resolveSecretEnv` call.
+
 ## pi coding agent — the one place we write real code, not config generation
 
 Reverse-engineered directly from the installed binary
@@ -155,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

@@ -948,6 +948,26 @@ tests passing.
 | P15 | ✅ Shared memory: ingest canonical `memories/*.md` into the `server-memory` store's own graph file (per-agent extraction into canonical remains a separate, open gap) | P6 |
 | P16 | ✅ MCP migrate-in: `trellis migrate --only mcp` for claude-code/kiro/codex (codex remote transport + probe HOME-scoping closed same-day, see prose above), closing the gap P14 named | P12, P14 |
 | P17 | ✅ `onboard` orchestration catches up to P15/P16: three-way migrate-category selection (mcp added), `memory sync` wired in as a chained stage | P15, P16 |
+| 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 |
+
+**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.4.0",
+  "version": "0.6.0",
   "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

@@ -11,6 +11,12 @@
 #     scanned against `reject_patterns` like everything else, so a real
 #     credential accidentally placed there is still refused, not silently
 #     written (trellis-mcp-static-env-and-disabled-servers).
+#   - `env_aliases` is for a var whose own name differs from the name it
+#     should resolve (`target_key: source_variable_name`) — resolved
+#     through the exact same mechanism as `env`, just delivered under a
+#     different key. Do NOT reach for `static_env` here: a "${SOURCE_NAME}"
+#     string looks like it works but ships unexpanded to any agent with no
+#     `${VAR}` runtime of its own (trellis-migrate-env-var-alias).
 #   - `enabled: false` keeps a server's definition in canonical without
 #     writing it to any agent — for a server you want to keep configured
 #     but not currently active everywhere, matching how a real agent's
@@ -78,6 +84,18 @@ servers:
     args: ["-y", "@zereight/mcp-gitlab"]
     env: [GITLAB_PERSONAL_ACCESS_TOKEN, GITLAB_API_URL]
 
+  # `env_aliases`: the server wants `OPENAPI_MCP_HEADERS`, but your secret
+  # manager holds it under a differently-named variable — a real example
+  # found via migrating an actual Notion MCP server entry. Same resolution
+  # discipline as `env`, just target-key -> source-name instead of
+  # self-named.
+  notion:
+    transport: stdio
+    command: npx
+    args: ["-y", "@notionhq/notion-mcp-server"]
+    env_aliases:
+      OPENAPI_MCP_HEADERS: NOTION_OPENAPI_MCP_HEADERS
+
   # `enabled: false` keeps this definition in canonical without writing it
   # to any agent — for something you want configured but not currently
   # active anywhere. Remove the line (or set it to `true`) to turn it back
@@ -110,15 +128,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]