agent-trellis 0.11.0 → 0.13.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/getting-started.md

@@ -907,6 +907,15 @@ An Agent can call the read-only `trellis.mcp.status` Runtime tool to explain
 this partial state to the user. It reports unavailable or authorization-
 required servers and gives the next safe action, such as `trellis mcp auth
 figma`, without exposing tokens or opening a browser from the Agent process.
+Each connected upstream also carries a structured `toolCount`, and an `oauth`
+section reports credential health with explicit ownership: Trellis-owned
+OAuth servers (which connect through the gateway on a Trellis-store token)
+report `valid` / `no-token` / `expired-renewable` / `needs-auth` /
+`unreadable` with `expiresAt` when known; agent-owned servers report
+`agent-managed`, since their authorization lives in the Agent's own client
+and is never inferred from Trellis's store. The classification is read-only
+and shared with `trellis mcp renew` and `trellis doctor`, so the three can
+never disagree.
 
 This command only applies to `http`/`sse` servers. stdio servers get
 their credentials from `env`/`env_aliases` as described above; running

package/docs/mcp-authorization-ownership.md

@@ -0,0 +1,78 @@
+# 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.
+
+## Browser callback feedback
+
+The local callback page shows a compact Trellis/service label, one status message,
+one short instruction and a close action, with Chinese or English copy based on
+the browser's preferred language. Receiving an
+authorization response is an intermediate step: validation, token exchange and
+credential storage still determine the final result shown in Trellis or the
+terminal. Cancellation, provider errors and incomplete responses have separate
+messages and guidance for starting again.
+
+The page uses no external assets and does not display authorization parameters
+or raw provider descriptions. Responses disable caching and referrer disclosure;
+when JavaScript is available, the page also removes the query and fragment from
+the current browser history entry. The close action offers manual-close guidance
+when a browser blocks it, and manual guidance remains visible without JavaScript.
+
+## 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. Set
+`TRELLIS_OAUTH_BROWSER_EXECUTABLE` to use a compatible Chromium executable instead.
+It exercises real browser CORS, PKCE callback, progress, cancellation, retry,
+owner confirmation and callback feedback without contacting a real provider or
+using personal credentials. Set `TRELLIS_OAUTH_SCREENSHOTS` to an output directory
+to save callback desktop/mobile previews during that run.
+Desktop packaging and installed-app acceptance happen after these checks.

package/docs/mcp-oauth-renewal.md

@@ -0,0 +1,88 @@
+# Scheduled OAuth renewal — `trellis mcp renew`
+
+The gateway and the pi bridge already refresh OAuth tokens silently before
+every upstream call. `trellis mcp renew` moves that renewal *earlier*: run
+on a schedule, it refreshes whatever is expiring and reports — with a
+non-zero exit code — anything that needs a human, before an Agent session
+discovers it as a 401.
+
+```
+trellis mcp renew              # refresh what's expiring, report health
+trellis mcp renew --dry-run    # report only; no token-endpoint call
+trellis mcp renew --json       # machine-readable (no credential material)
+```
+
+Scope is canonical OAuth servers with an explicit `owner: trellis` —
+classification is explicit (mcp-auth-routing-policy), and ownership decides
+whose problem the credential is (trellis-desktop-oauth-ownership): an
+agent-owned server (the default, e.g. scalar `auth: oauth`) is authorized by
+the Agent's own client, never reads Trellis's token store, and is neither
+renewed nor reported here. The command never opens a browser and never
+performs an initial grant; that remains `trellis mcp auth <name>`
+(mcp-gateway-hosting design.md D9). Exit code: `0` when every Trellis-owned
+server is valid or refreshed, `1` when any needs `trellis mcp auth`, has
+never been authorized, or has an unreadable credential file.
+
+`trellis doctor` reports the same per-server health read-only (no network,
+no writes) and surfaces an `oauth-expired` finding — contributing to a
+non-zero doctor exit — for credentials that are expired or absent.
+
+## launchd setup (macOS)
+
+Trellis has no daemon; periodic renewal belongs to the platform
+scheduler. Save this as `~/Library/LaunchAgents/com.trellis.mcp-renew.plist`,
+adjusting the `trellis` path (`which trellis`):
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.trellis.mcp-renew</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/usr/local/bin/trellis</string>
+    <string>mcp</string>
+    <string>renew</string>
+    <string>--json</string>
+  </array>
+  <key>StartInterval</key>
+  <integer>21600</integer>
+  <key>ThrottleInterval</key>
+  <integer>600</integer>
+  <key>StandardOutPath</key>
+  <string>/tmp/trellis-mcp-renew.log</string>
+  <key>StandardErrorPath</key>
+  <string>/tmp/trellis-mcp-renew.log</string>
+</dict>
+</plist>
+```
+
+Then:
+
+```
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.trellis.mcp-renew.plist
+launchctl kickstart gui/$(id -u)/com.trellis.mcp-renew   # run once now
+launchctl bootout gui/$(id -u)/com.trellis.mcp-renew     # uninstall
+```
+
+Why these knobs:
+
+- **`ThrottleInterval`** (design.md D3) caps how close together runs may
+  be. A machine waking from sleep with a launchd backlog runs once, not N
+  times — refresh-endpoint hammering is the failure mode that gets refresh
+  tokens revoked by rate-limiting providers, which is worse than the
+  disease this job exists to prevent.
+- **`StartInterval` of 6h** is comfortably inside typical refresh-token
+  lifetimes (days to months) while keeping token-endpoint traffic near
+  zero: a valid token is a no-op *read*, so most runs make no network
+  calls at all.
+- **Overlapping runs are safe**: refresh is serialized by the per-server
+  lock (`src/lib/oauth/lock.ts`). A second concurrent run waits, then
+  reads the token the first one just wrote.
+- **`--json` to a log** gives you a parseable trail. A `1` exit means
+  "something needs `trellis mcp auth <name>`" — the JSON names which.
+
+Check on demand: `trellis doctor` shows the same per-server credential
+health.

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.13.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"
   }
 }