agent-trellis 0.9.0 → 0.10.0

package/dist/pi-bridge/index.js

@@ -17,7 +17,7 @@ import { resolveMcpPlan } from "../adapters/mcpPlan.js";
 import { connectServer, withTimeout, DEFAULT_CONNECT_TIMEOUT_MS } from "../lib/mcpConnect.js";
 import { McpToolRegistry } from "../lib/mcpToolRegistry.js";
 import { withOAuthHeader } from "../lib/gatewayBackend.js";
-import { ALL_AGENTS } from "../core/types.js";
+import { ALL_AGENTS, isOAuthAuth } from "../core/types.js";
 import { toParametersSchema, toPiContent } from "./schemaTranslate.js";
 /** Re-exported so `trellis-mcp-connect-timeout`'s existing test keeps
  * importing it from the module it was written against — proving the
@@ -75,7 +75,7 @@ export default async function trellisMcpBridge(pi, homeDir = homedir(), connectT
     const discovered = await Promise.all(desired.map(async ({ name, def }) => {
         let client;
         try {
-            const effectiveDef = def.auth === "oauth" && def.url
+            const effectiveDef = isOAuthAuth(def.auth) && def.url
                 ? await withOAuthHeader(name, def, homeDir)
                 : def;
             client = await connectServer(effectiveDef, canonical.secretsPolicy, connectTimeoutMs, CLIENT_INFO);

package/docs/architecture.md

@@ -266,6 +266,25 @@ 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
 classification from a URL or a transient 401.
 
+The classification optionally carries pre-registered client metadata, for
+providers that refuse Dynamic Client Registration and require an allowlisted
+client instead:
+
+```yaml
+auth:
+  kind: oauth
+  client_id: "<provider-published-id>"    # public by design, literal
+  client_secret_env: PROVIDER_CLIENT_SECRET  # a NAME, resolved via secrets.policy.yaml
+```
+
+`client_id` wins over DCR when present; DCR stays the fallback when it is
+absent. There is deliberately no literal secret field — a secret enters only
+as a variable name, the same `env`-style discipline everything else follows.
+See docs/mcp-oauth-matrix.md for which providers are open to registration and
+which are not, and for the distribution rule: examples, docs, and seed data
+ship placeholders only, and only provider-**published** identifiers may ever
+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

package/docs/mcp-oauth-matrix.md

@@ -0,0 +1,140 @@
+# Remote MCP providers — how OAuth identity works, and where Trellis can help
+
+`trellis mcp auth <name>` can only complete an authorization-code grant if it
+is allowed to *have* a client identity. Whether it may is entirely the
+provider's decision, and that decision splits remote MCP providers into two
+families. This page records which family each known provider is in, what
+evidence that rests on, and what Trellis does in each case.
+
+Read alongside docs/architecture.md §"Static header auth vs. real OAuth",
+which covers the *other* shape — a long-lived bearer token or API key in a
+`headers` field — and why Trellis builds for both.
+
+## The two families
+
+**DCR-open.** The provider implements RFC 7591 Dynamic Client Registration.
+Trellis POSTs its own metadata, receives a `client_id`, and holds its own
+identity per installation. Nothing a user has to supply; nothing Trellis has
+to distribute. This already works: it is what `trellis mcp auth` has done
+since `trellis-mcp-gateway-hosting`.
+
+**Allowlist.** The provider refuses registration — either by not advertising a
+`registration_endpoint`, or by answering it with `unauthorized_client` — and
+requires clients to be pre-registered with the provider. There is no
+self-service path: the user obtains a `client_id` out of band and supplies it.
+That is what the `auth.client_id` / `auth.client_secret_env` fields exist for
+(trellis-mcp-oauth-static-client design.md D1–D3).
+
+The 2026-07-28 MCP authorization spec moved in the allowlist direction,
+downgrading Dynamic Client Registration from a MUST to a MAY in favour of
+pre-registration. Expect the second family to grow; the mechanism, not the
+per-provider list, is what Trellis commits to.
+
+## Matrix
+
+| Provider | Family | What identifies the client | Evidence | Confidence |
+|---|---|---|---|---|
+| Sentry | DCR-open | `client_id` from DCR | Local successful grant against the real server; secondary sources describing its DCR endpoint | Medium — see the note below |
+| Supabase | DCR-open | `client_id` from DCR | Same | Medium |
+| Morphix | DCR-open | `client_id` from DCR | Same | Medium |
+| GitHub | DCR-open | `client_id` from DCR | Same | Medium |
+| Notion | DCR-open | `client_id` from DCR | Same | Medium |
+| Linear | DCR-open | `client_id` from DCR | Same | Medium |
+| Cloudflare | DCR-open | `client_id` from DCR | Same | Medium |
+| Figma | Allowlist | Provider-published `client_id`, supplied by the user | Registration refused with `unauthorized_client` — observed directly, and the reason this change exists | High |
+
+**On confidence.** "High" means the behavior was observed directly against the
+live provider and the failure (or success) is reproducible from this
+repository's own test fixtures. "Medium" means the status rests on a working
+local grant plus secondary sources rather than a first-party policy statement —
+the *observed* behavior is solid, but a provider is free to change its
+registration policy at any time, and none of these have published a
+contractual commitment either way. Sentry is explicitly in this bucket
+(trellis-mcp-oauth-static-client design.md D6): the local grant proves
+registration works today, not that it will next quarter.
+
+Treat the whole table as a snapshot of observed behavior, not as provider
+policy. `trellis mcp auth` reports the actual failure when a row goes stale —
+see "When a provider refuses" below.
+
+## What actually identifies a client
+
+There is no magic header and no provider-specific handshake. Any OAuth 2.0
+authorization server that speaks the MCP authorization profile identifies a
+client by a combination of:
+
+- **`client_id`** — the identity itself. Public by design for a public client:
+  it travels in the browser URL on every authorization (`?client_id=...`), so
+  it is visible to the user, their browser history, and any proxy in between.
+  Its security rests on the *other* factors here, never on its secrecy.
+- **Exact `redirect_uri` match** — registered with the client and required to
+  match byte-for-byte. This is why Trellis's loopback callback is what it is:
+  `http://127.0.0.1:<port>/callback`, with the port chosen by the OS at bind
+  time. A pre-registered client whose provider pins one specific port is the
+  one case where a fixed `callbackPort` is needed.
+- **PKCE (RFC 7636, `S256`)** — the proof that whoever redeems the code is
+  whoever started the flow. The verifier never travels through the browser;
+  only its SHA-256 challenge does. Trellis's fake Authorization Server in the
+  test suite *enforces* this rather than rubber-stamping it, so the tests
+  cannot pass for a client that gets PKCE wrong.
+- **`resource` parameter** — binds the grant to the MCP server it was issued
+  for, so a token minted for one server is not replayable against another.
+
+Nothing in that list is a secret for a public client, which is exactly why
+`client_id` is a plain literal in canonical YAML and `client_secret_env` — the
+one field that *is* a credential — is a variable NAME resolved through
+`secrets.policy.yaml` and never a value (design.md D2).
+
+## When a provider refuses
+
+`trellis mcp auth <name>` tries pre-registered metadata first, then DCR. When
+both are unavailable it fails with the remediation rather than a bare status
+code:
+
+```
+"figma": dynamic client registration was refused (unauthorized_client) —
+register a client with the provider and set auth.client_id (plus
+auth.client_secret_env if the provider requires a secret) under this server in
+~/.trellis/mcp/servers.yaml
+```
+
+The fix is then two commands:
+
+```sh
+trellis mcp set figma --auth oauth --client-id <provider-published-id>
+trellis mcp auth figma
+```
+
+The id comes from the provider. Trellis does not ship one, look one up for
+you, or read another client's stored credentials to borrow an identity —
+that last option is rejected structurally, not just by policy (design.md D5:
+borrowing a refresh token makes both clients fight over rotation, and reading
+another tool's credential store would mean decrypting files Trellis does not
+own).
+
+## Distribution boundary
+
+Trellis is open source. What it distributes is a mechanism — the schema field,
+the flow, the tests. It does not distribute an identity.
+
+A user who obtains a `client_id` and pastes it into their own
+`~/.trellis/mcp/servers.yaml` is making their own decision under the provider's
+terms, in the same position as anyone running `mcp-remote
+--static-oauth-client-info`. Trellis shipping that same id in
+`schema/servers.example.yaml`, in this page, or in seed data would instead make
+the project itself the distributor of a whitelist-bypass tool. So:
+
+- Examples and docs use placeholders only — see the commented block in
+  `schema/servers.example.yaml`.
+- Only provider-**published** identifiers may ever be pre-filled. None exist
+  today, so nothing is pre-filled.
+- A literal that matches `reject_patterns` is refused at load and at write, so
+  a pasted credential cannot quietly become part of the canonical source.
+
+## See also
+
+- docs/architecture.md §"Static header auth vs. real OAuth" — the other shape.
+- `schema/servers.example.yaml` — the object form, with placeholders.
+- trellis-mcp-oauth-static-client design.md — D1 (field shape), D2 (literal vs.
+  name), D3 (metadata wins over DCR), D4 (distribution boundary), D5 (no token
+  borrowing), D6 (this matrix's confidence notes).

package/docs/research.md

@@ -216,6 +216,17 @@ 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.
 
+The same reference-not-value rule is what shapes OAuth client metadata
+(trellis-mcp-oauth-static-client). A public client's `client_id` is published
+by design — it rides in the browser URL on every authorization — so it is a
+plain literal, comparable to how `mcp-remote --static-oauth-client-info` and
+`claude mcp add --client-id` already treat it. A `client_secret` is the
+opposite kind of thing, so it enters only as `client_secret_env`, a variable
+NAME resolved through this same machinery; there is deliberately no literal
+secret field. Which providers accept an unregistered client at all is a
+per-provider question — see docs/mcp-oauth-matrix.md, including its note that
+that matrix records observed behavior, not provider policy.
+
 ## pi coding agent — the one place we write real code, not config generation
 
 Reverse-engineered directly from the installed binary

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-trellis",
-  "version": "0.9.0",
+  "version": "0.10.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",
@@ -23,7 +23,9 @@
   "files": [
     "dist",
     "schema",
-    "docs"
+    "docs/*.md",
+    "docs/assets/brand-v3",
+    "docs/assets/poster-series-v3"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json && node scripts/build-pi-bridge.mjs",

package/schema/servers.example.yaml

@@ -118,6 +118,24 @@ servers:
     # Explicit OAuth classification keeps this server direct when an Agent
     # uses gateway mode. Trellis never infers OAuth from a URL or 401.
     # auth: oauth
+    #
+    # Object form (trellis-mcp-oauth-static-client): for a provider that
+    # rejects Dynamic Client Registration (Figma does — `unauthorized_client`)
+    # and requires a pre-registered client. `kind: oauth` is the only
+    # discriminator and the only required key; a bare `auth: oauth` above and
+    # a metadata-less `{ kind: oauth }` are exactly equivalent.
+    #   - `client_id` is a PUBLIC literal by design — fine to commit. Use the
+    #     identifier the PROVIDER published for this client; a self-registered
+    #     one from your own account only if you accept managing it.
+    #   - `client_secret_env` is a variable NAME, resolved through
+    #     secrets.policy.yaml at `trellis mcp auth` time — never a secret
+    #     value, and never a literal secret field (there is none).
+    # Placeholders below on purpose: only provider-published identifiers may
+    # ever be pre-filled in a distribution artifact.
+    # auth:
+    #   kind: oauth
+    #   client_id: "<provider-published-client-id>"
+    #   client_secret_env: FIGMA_CLIENT_SECRET
 
   # Example of a private/agent-specific server: only Claude Code has a use
   # for this one, so the other three agents never see it defined at all.

package/docs/video/README.md

@@ -1,76 +0,0 @@
-# Trellis 分享视频 · 素材与录制清单
-
-> 本目录（`docs/video/`）在 `.gitignore` 中，所有内容只存在于本地，
-> 不会进入开源仓库。
-
-## 自动生成视频
-
-```bash
-node docs/video/generate-video.mjs   # 输出 docs/video/trellis-demo-video.mp4
-```
-
-一条命令完成：重置沙盒 → 真实跑一遍 CLI 并捕获输出 → 渲染终端帧与卡片
-（qlmanage）→ 系统 TTS 生成中文口播（Ting-Ting Enhanced）→ ffmpeg 合成
-1920×1080 mp4。改口播文案直接编辑脚本里的 `blocks[].narration`；终端帧
-内容来自真实命令输出，无需手改。依赖：ffmpeg（`brew install ffmpeg`）、
-macOS 自带的 qlmanage/sips/say/afinfo。
-
-## 演示沙盒（不碰真实配置）
-
-```bash
-bash scripts/video-demo-setup.sh        # 生成/重置演示环境到 /tmp/trellis-demo-home
-export HOME=/tmp/trellis-demo-home      # 之后所有 trellis 命令都在沙盒里运行
-```
-
-沙盒内容：Claude Code（1 份指令 + 2 个 Skill + 2 个 MCP 服务器）、
-Codex（config.toml + 1 个 MCP 服务器）。每次重录前重跑 setup 脚本即可
-回到初始状态。已验证全流程可跑通：`init → onboard --dry-run → onboard →
-doctor → rollback`。
-
-录制用命令（已跳过交互选择，流程不打断）：
-
-```bash
-trellis init
-trellis onboard --dry-run --agent claude-code --manage codex
-trellis onboard --agent claude-code --manage codex
-trellis doctor
-trellis rollback
-```
-
-## 终端与录屏设置
-
-| 项 | 建议 |
-|---|---|
-| 终端主题 | 浅色（手机端观看对比度更好） |
-| 字号 | 20–24pt，观众多用手机看 |
-| 提示符 | `export PS1='$ '`，干净无干扰 |
-| 窗口 | 1280×720 或 1440×810 逻辑分辨率 |
-| 录屏 | Kap / QuickTime；每条 take 前 `clear` |
-| 导出 | 横屏 1920×1080（B 站/YouTube）；竖屏 1080×1920（视频号/小红书）则后期裁切，注意命令别超出安全区 |
-
-## 分镜与素材对照
-
-| 场景 | 画面 | 素材 |
-|---|---|---|
-| 1 开场 | 终端/编辑器随意状态 | 现场录 |
-| 2 痛点 | `ls ~/.claude` `ls ~/.codex`（真实目录，只读） | 现场录 |
-| 3 方案 | 海报全屏 | [`../assets/poster-series-v3/agent-trellis-poster-v3-unified-zh.png`](../assets/poster-series-v3/agent-trellis-poster-v3-unified-zh.png) |
-| 4 演示 | 终端实录 | 沙盒命令（见上） |
-| 5 设计点 | README Design principles 滚动 | github.com/paul-leo/Trellis |
-| 6 收尾 | GitHub 仓库首页 + Star 按钮停留 2 秒 | 同上 |
-
-## 其他可用素材
-
-- 封面图/片尾卡：[`../assets/poster-series-v3/agent-trellis-poster-v3-horizontal-zh.png`](../assets/poster-series-v3/agent-trellis-poster-v3-horizontal-zh.png)
-- Logo 叠层（角标）：[`../assets/brand-v3/trellis-mark-v3-a.svg`](../assets/brand-v3/trellis-mark-v3-a.svg)
-- 口播逐字稿：[voiceover.zh-CN.md](voiceover.zh-CN.md)
-- 场景大纲：[outline.zh-CN.md](outline.zh-CN.md)
-- 60 秒极简版：见 [outline.zh-CN.md](outline.zh-CN.md) 末尾
-
-## 录制前 Checklist
-
-- [ ] 重跑 `bash scripts/video-demo-setup.sh` 重置沙盒
-- [ ] `export HOME=/tmp/trellis-demo-home && export PS1='$ ' && clear`
-- [ ] 终端字号调大，关闭通知（勿扰模式）
-- [ ] 预演一遍场景 4，确认输出与口播一致
-- [ ] 麦克风电平测试 5 秒

package/docs/video/build/segments/01-opening.txt

@@ -1,3 +0,0 @@
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/01-opening-0.png'
-duration 11.053
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/01-opening-0.png'

package/docs/video/build/segments/02-pain.txt

@@ -1,5 +0,0 @@
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/02-pain-1.png'
-duration 2.172
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/02-pain-2.png'
-duration 5.068
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/02-pain-2.png'

package/docs/video/build/segments/03-solution.txt

@@ -1,3 +0,0 @@
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/03-solution-3.png'
-duration 6.482
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/03-solution-3.png'

package/docs/video/build/segments/04-install.txt

@@ -1,3 +0,0 @@
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/04-install-4.png'
-duration 2.407
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/04-install-4.png'

package/docs/video/build/segments/04-setup.txt

@@ -1,3 +0,0 @@
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/04-setup-4.png'
-duration 4.131
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/04-setup-4.png'

package/docs/video/build/segments/05-dryrun.txt

@@ -1,3 +0,0 @@
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/05-dryrun-6.png'
-duration 7.031
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/05-dryrun-6.png'

package/docs/video/build/segments/05-init.txt

@@ -1,3 +0,0 @@
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/05-init-5.png'
-duration 6.587
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/05-init-5.png'

package/docs/video/build/segments/05-interactive.txt

@@ -1,5 +0,0 @@
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/05-interactive-5.png'
-duration 1.952
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/05-interactive-6.png'
-duration 4.556
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/05-interactive-6.png'

package/docs/video/build/segments/06-dryrun.txt

@@ -1,3 +0,0 @@
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/06-dryrun-6.png'
-duration 14.763
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/06-dryrun-6.png'

package/docs/video/build/segments/06-onboard.txt

@@ -1,5 +0,0 @@
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/06-onboard-7.png'
-duration 1.537
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/06-onboard-8.png'
-duration 3.587
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/06-onboard-8.png'

package/docs/video/build/segments/06-run.txt

@@ -1,3 +0,0 @@
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/06-run-7.png'
-duration 6.874
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/06-run-7.png'

package/docs/video/build/segments/07-onboard.txt

@@ -1,5 +0,0 @@
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/07-onboard-7.png'
-duration 2.195
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/07-onboard-8.png'
-duration 5.123
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/07-onboard-8.png'

package/docs/video/build/segments/07-verify.txt

@@ -1,5 +0,0 @@
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/07-verify-8.png'
-duration 1.184
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/07-verify-9.png'
-duration 2.764
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/07-verify-9.png'

package/docs/video/build/segments/08-closing.txt

@@ -1,3 +0,0 @@
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/08-closing-10.png'
-duration 9.591
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/08-closing-10.png'

package/docs/video/build/segments/08-doctor.txt

@@ -1,3 +0,0 @@
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/08-doctor-9.png'
-duration 5.620
-file '/Users/pengzai/www/Trellis/docs/video/build/frames/08-doctor-9.png'