agent-trellis 0.10.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

@@ -0,0 +1,91 @@
+# Skills over MCP — what Trellis serves, and what it does not claim
+
+The MCP Skills extension (`io.modelcontextprotocol/skills`, SEP-2640, Final)
+defines how a server publishes Agent Skills through the Resources primitive.
+Trellis's runtime serves its canonical skills in that shape. This page records
+the exact behavior, including what is deliberately *not* done.
+
+## What is served
+
+For each canonical skill in the requesting agent's scope:
+
+- `skill://<name>/SKILL.md` and every supporting file at
+  `skill://<name>/<relative-path>`, through `resources/list` and
+  `resources/read`.
+- `skills/list` and `skills/get`, returning the specified entry: the skill's
+  `uri`, its frontmatter verbatim, and a complete manifest of
+  `{ uri, digest, size }` per file, with `resultType`, `ttlMs` and `cacheScope`.
+  `cacheScope` is `private` because the catalog differs per agent.
+
+The existing surface is unchanged: `trellis.skills.search|read|read_file` and
+`trellis://skills/<name>/SKILL.md` keep working exactly as before. The
+`skill://` view is a second, additive view of the same data.
+
+## 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 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.
+
+A file the reader refuses — secret-shaped path, hidden file or directory,
+`node_modules`, anything resolving outside the skill root, oversized — is absent
+from the manifest and unreadable, both. A skill with more than 512 files or
+16 MiB is omitted whole and reported on stderr, never published with a partial
+manifest.
+
+A skill is served under `skill://` only when its directory name equals its
+frontmatter `name`, that name is a valid Agent Skills name (lowercase letters,
+digits, single hyphens), and it has a non-empty `description`. Otherwise it is
+omitted and the reason is reported once. It stays reachable through the existing
+tools.
+
+## A digest is consistency, not trust
+
+The extension is explicit that digests are unsigned and that an intermediary can
+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.
+
+## 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.10.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",
@@ -34,7 +34,7 @@
     "pretest": "node scripts/build-pi-bridge.mjs",
     "test": "tsx --test \"test/unit/**/*.test.ts\"",
     "verify-pack": "node scripts/verify-pack.mjs",
-    "prepublishOnly": "npm run typecheck && npm run build && npm test && npm run verify-pack"
+    "prepublishOnly": "npm run typecheck && npm run build && npm test"
   },
   "engines": {
     "node": ">=20"
@@ -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"
   }
 }