agent-trellis 0.11.0 → 0.12.0

package/docs/architecture.md

@@ -261,9 +261,9 @@ reach such a server at all.
 
 Gateway mode does not automatically take ownership of OAuth servers. Mark a
 server explicitly with `auth: oauth` (or `trellis mcp set <name> --auth oauth`)
-and gateway planning keeps it direct. This preserves the native Agent OAuth
-flow for Claude Code/Codex/Kiro; Pi's bridge is the client for its direct OAuth
-connection and may use Trellis's own OAuth store. Trellis never infers this
+and gateway/runtime planning keeps it native. This preserves each Agent's own
+OAuth identity. Only `auth: { kind: oauth, owner: trellis }` explicitly opts into
+Trellis hosting, with a gateway/runtime route required. Trellis never infers this
 classification from a URL or a transient 401.
 
 The classification optionally carries pre-registered client metadata, for
@@ -288,18 +288,19 @@ be pre-filled.
 Trellis still implements the client half itself — discovery (RFC 8414 /
 RFC 9728), dynamic client registration (RFC 7591), authorization code with
 PKCE S256 (RFC 7636), and the refresh grant — in `src/lib/oauth/`, but that
-path is currently used for Pi/direct bridge connections rather than silently
-replacing native Agent authorization.
+path is used for explicitly hosted connections. It never imports or silently
+replaces native Agent authorization. See
+[MCP authorization ownership](mcp-authorization-ownership.md).
 
 Two rules shape it, both from the constraint that the gateway is spawned
 silently by an agent with no terminal attached:
 
-- **Only an explicit human authorization command opens a browser.** Native
-  clients use their own login command for direct OAuth entries. Pi's direct
-  bridge uses `trellis mcp auth <server>`. The gateway never initiates an
-  interactive flow and never connects an OAuth-marked server.
+- **Only an explicit human action opens a browser.** Native clients use their
+  own authorization entry. Trellis-hosted connections can use the desktop
+  Authorize action or `trellis mcp auth <server>`. The gateway never initiates
+  an interactive flow and excludes Agent-owned OAuth servers.
 - **Refreshing is silent, and serialized by a lock.** A `refresh_token`
-  grant needs neither a browser nor a callback, so the Pi direct bridge can
+  grant needs neither a browser nor a callback, so the hosted gateway can
   do it at connect time. The lock (`~/.trellis/mcp/oauth/<name>.lock`) exists
   because most authorization servers rotate the refresh token and
   invalidate its predecessor — two concurrent refreshes would leave one
@@ -312,8 +313,8 @@ non-interactive, no-GUI-session context the gateway runs in — measured,
 not assumed).
 
 In direct mode nothing here changes: each agent keeps using its own native
-OAuth flow. In gateway mode, an OAuth-marked server is also kept direct; only
-ordinary MCP servers enter the gateway.
+OAuth flow. Gateway/runtime mode retains native entries for Agent-owned OAuth;
+ordinary and explicitly Trellis-owned servers enter the gateway.
 
 ## MCP gateway mode
 
@@ -362,7 +363,7 @@ could reach disk.
 **What it changes for the agents:** Codex's single-`bearer_token_env_var`
 limitation stops applying, because Codex no longer receives any server's
 `headers` — the gateway holds them. OAuth-marked servers are intentionally
-kept direct; ordinary remote servers remain shared through the gateway. An
+kept native by default; explicit Trellis ownership enables hosted OAuth. An
 upstream tool keeps its original name when that name is unique and longer than
 the short-name threshold; generic short names receive a compact
 `<server>__<tool>` prefix even when unique. A tool already carrying its source

package/docs/mcp-authorization-ownership.md

@@ -0,0 +1,59 @@
+# MCP authorization ownership
+
+Each Agent-owned connection is authorized by that Agent. Trellis does not read,
+copy or refresh its credentials. Existing `auth: oauth` and metadata-bearing
+OAuth entries default to `owner: agent`. Runtime delivery also retains these
+native OAuth entries beside the Trellis runtime.
+
+The MCP desktop view labels native state as unknown and shows the relevant Agent
+entry or guidance. A stray Trellis token does not change that state. The view's
+credential badge describes stored credentials, not connection health.
+
+## Explicit Trellis hosting
+
+For providers that accept a Trellis registration, opt in per server:
+
+```yaml
+auth:
+  kind: oauth
+  owner: trellis
+  # Optional provider-published client identifier:
+  # client_id: YOUR_REGISTERED_CLIENT_ID
+  # client_secret_env: YOUR_CLIENT_SECRET_VARIABLE
+```
+
+Or run `trellis mcp set NAME --auth oauth --auth-owner trellis`, then sync.
+Gateway or runtime delivery must be enabled for the receiving Agent. Plain
+direct routing reports a conflict rather than moving Trellis's identity into a
+native connection. `--auth-owner agent` returns the server to native ownership.
+The desktop owner selector previews a plan and requires Apply before changing
+canonical configuration and syncing it.
+
+Remote connections without an OAuth classification can choose an owner directly
+in the desktop selector. Its No OAuth classification option clears that setting;
+neither choice starts a grant automatically.
+
+The hosted desktop Authorize button launches the existing PKCE flow in the
+system browser. Progress is observable, cancellation closes the callback, and
+timeouts/provider failures permit retry. Repeated clicks share one active job.
+Tokens are saved in the existing per-server 0600 store, never sent to the UI.
+A changed endpoint/auth configuration during the grant prevents persistence.
+Authorization actions require a trusted desktop/development Origin.
+
+New credentials retain their MCP resource and authorization-server issuer.
+Authorization, exchange and refresh send the resource indicator; callback issuer
+is checked when supplied or advertised as required. A changed resource cannot
+receive its previous bound credential. The final save shares the refresh lock,
+so a cancelled grant cannot overwrite a concurrent refresh.
+
+The gateway can silently refresh its own hosted credentials; it never opens a
+browser. Agents with native connections continue using their own flows.
+
+## Verification
+
+Run core tests and typecheck, GUI sidecar tests/typecheck and GUI smoke tests.
+`npm run test:oauth-browser --workspace @trellis/gui` additionally uses installed
+Google Chrome headlessly with a local authorization-server fixture. It exercises
+real browser CORS, PKCE callback, progress, cancellation, retry and owner
+confirmation without contacting a real provider or using personal credentials.
+Desktop packaging and installed-app acceptance happen after these checks.

package/docs/skills-over-mcp.md

@@ -24,8 +24,9 @@ The existing surface is unchanged: `trellis.skills.search|read|read_file` and
 ## The manifest is computed from the bytes served
 
 `digest` is `sha256:` plus 64 lowercase hex characters of the raw bytes;
-`size` is their length. The same reader produces the manifest and the
-`resources/read` response, so they cannot disagree. Invalid UTF-8 is returned as
+`size` is their length. The manifest and `resources/read` use the same bounded
+byte reader. Hosts still verify the retained manifest: a file can change between
+listing and reading. Invalid UTF-8 is returned as
 a base64 `blob` rather than lossy `text`, so the bytes a host verifies are the
 bytes that were hashed.
 
@@ -48,32 +49,43 @@ rewrite entry and content together. A matching digest tells a host the bytes
 match the manifest; it says nothing about whether the content is safe. Nothing in
 Trellis treats a match as an authorization.
 
-## The extension is not declared yet
-
-The extension is declared through `server/discover`, introduced with protocol
-revision 2026-07-28. The MCP SDK Trellis uses speaks at most 2025-11-25 and has
-neither `server/discover` nor `skills/*`, and the specification defines no
-declaration for the `initialize` handshake. Declaring it in another field would
-invent a protocol, and a conforming client only issues `skills/list` after
-observing a declaration anyway.
-
-So on today's SDK the runtime declares nothing, answers `skills/list` and
-`skills/get` through the SDK's fallback for unregistered methods, and serves
-`skill://` as ordinary resources — which the specification expressly allows. Once
-the SDK exposes `server/discover`, the declaration is a one-place change. Any other
-unknown method still gets JSON-RPC `-32601`.
-
-## Relaying skills from upstream servers is not implemented
-
-Today an upstream server's skills are not relayed — the gateway backend
-aggregates tools only. When a change adds that, it must:
-
-- identify a skill by (upstream label, URI) together, never by URI alone, with a
-  namespace per upstream;
-- never let an upstream skill shadow a canonical skill or another upstream's;
-- bind reads to the originating upstream, with no cross-upstream reads;
-- pass the upstream manifest through unchanged or re-derive it from the relayed
-  bytes — never pair an upstream digest with different bytes;
-- not write an upstream skill into `~/.trellis/skills` automatically. The
-  specification requires per-skill user approval before such content is used, and
-  materializing it would bypass that.
+## Discovery and protocol compatibility
+
+The runtime uses the official TypeScript SDK v2 serving entry. Modern clients
+discover resources and the `io.modelcontextprotocol/skills` extension through
+`server/discover`; legacy clients can still initialize and call existing tools
+and resources. Merely constructing a v2 Server is not sufficient: the runtime
+explicitly uses `serveStdio` to select modern or legacy behavior.
+
+Skills list/get are registered custom methods with parameter/result schemas.
+The SDK handles modern request metadata, result discrimination and server
+identity. Unknown methods still return JSON-RPC `-32601`. A legacy host can use
+ordinary resources/tools even if it does not understand the Skills extension.
+
+## Upstream resources and skills
+
+The gateway negotiates modern or legacy upstream behavior. Legacy HTTP+SSE uses
+its existing transport. An upstream with resources but no tools remains valid.
+Declared modern Skills catalogs are paginated, validated and relayed:
+
+- URIs use a reversible `trellis-upstream://` namespace per source, preserving
+  final path segments and relative references. Provenance records the original
+  server label and URI. Canonical and equal-named upstream skills stay distinct.
+- Listing does not fetch file content. Supporting files become readable from a
+  complete manifest, even when absent from `resources/list`; direct `skills/get`
+  also works for unlisted skills.
+- Reads go back to the registered source and preserve exact bytes, digest and
+  size. Skill content is rejected if digest, size or SKILL.md frontmatter differ
+  from the entry. Refresh the entry before reading changed content.
+- Dynamic skill manifests are currently declined with a diagnostic. Manifests
+  are bounded to 512 files and 16 MiB per skill; unsupported or malformed entries
+  do not remove other skills.
+- No upstream skill is installed into `~/.trellis/skills`, activated, or given
+  execution permissions by the relay. The consuming host retains its own approval
+  and integrity checks.
+
+Authorization ownership and the desktop flow are documented in
+[MCP authorization ownership](mcp-authorization-ownership.md).
+
+Protocol references: [SDK v2 migration](https://ts.sdk.modelcontextprotocol.io/v2/migration/support-2026-07-28)
+and [Skills extension](https://modelcontextprotocol.io/extensions/skills/overview).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-trellis",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "A unified Code Agent Runtime for Skills, MCP, Memory, and shared instructions across Claude Code, Codex, Kiro, pi, Kimi Code, and ZCode.",
   "license": "MIT",
   "author": "Paul Leo",
@@ -61,7 +61,10 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.8.1",
+    "@modelcontextprotocol/client": "^2.3.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "yaml": "^2.9.1"
+    "@modelcontextprotocol/server": "^2.3.1",
+    "yaml": "^2.9.1",
+    "zod": "^4.6.5"
   }
 }