agent-trellis 0.13.0 → 0.14.1

package/dist/adapters/pi.d.ts

@@ -3,22 +3,61 @@
  * symlinked to canonical `agents.md` — specifically `AGENTS.md`, not
  * `AGENTS.override.md` (design.md D3, trellis-sync-p1: pi checks the
  * override name first, and Trellis's managed file is the baseline, not an
- * override of something else). pi has no native MCP client (docs/research.md),
- * so MCP access is delivered as a single symlinked bridge extension
- * instead of native config (trellis-pi-mcp-bridge-p4) — a different
- * mechanism from every other agent's config-generation adapter, but the
- * same symlink create/repair/remove machinery as skills/instructions.
+ * override of something else).
+ *
+ * MCP delivery is version-gated (trellis-pi-native-mcp-migration):
+ *
+ * - pi >= 1.1.0 has a native MCP client, so `trellis mcp sync` merges
+ *   Trellis-managed entries into `~/.pi/agent/mcp.json` through the shared
+ *   `planJsonMcp`/`applyJsonMcp` machinery (ownership ledger, conflict
+ *   detection, user entries preserved) with the pi-shaped renderer from
+ *   `piMcp.ts`. Gateway route → the single `trellis` runtime entry;
+ *   agent-owned OAuth servers → bare `{url}` entries the user authorizes
+ *   with `pi mcp login`.
+ * - Older pis (or an unprobeable version) keep the legacy delivery: a
+ *   single symlinked bridge extension (`dist/pi-bridge/bundle.js`,
+ *   trellis-pi-mcp-bridge-p4). The version gate never moves a machine
+ *   FROM the bridge TO native until the mcp.json write succeeds — the
+ *   bridge-removal item rides along in the same plan, ordered after the
+ *   config write, and is withheld entirely when any write conflicts
+ *   (design.md D3: the two deliveries may never be active at once, every
+ *   tool would register twice).
  */
 import type { AdapterPlanItem, AdapterProbeResult, AdapterVerifyResult, TrellisAdapter } from "../core/adapter.js";
 import type { CanonicalSource } from "../core/types.js";
-import type { BackupSession } from "../lib/backup.js";
+import { type BackupSession } from "../lib/backup.js";
 export declare class PiAdapter implements TrellisAdapter {
     private readonly homeDir;
+    /** Test seam: the version gate must not depend on whatever pi happens
+     * to be installed on the machine running the tests. */
+    private readonly versionProbe;
     readonly name = "pi";
     readonly id: "pi";
-    constructor(homeDir?: string);
+    constructor(homeDir?: string, 
+    /** Test seam: the version gate must not depend on whatever pi happens
+     * to be installed on the machine running the tests. */
+    versionProbe?: () => string | undefined);
     probe(): Promise<AdapterProbeResult>;
     plan(canonical: CanonicalSource): Promise<AdapterPlanItem[]>;
+    /**
+     * Native-delivery plan (design.md D1/D3). The write items come from the
+     * shared JSON machinery unchanged; the bridge-removal item is appended
+     * last and re-cast to kind "mcp" so it travels through `trellis mcp
+     * sync` — the same command that writes mcp.json — never through bare
+     * `trellis sync`. That is what makes the migration atomic from the
+     * user's point of view: the config lands and the bridge leaves in one
+     * apply, and a bare skills/instructions sync can neither remove the
+     * bridge early nor resurrect it afterwards.
+     */
+    private planNativeMcp;
+    /**
+     * Removal ownership for the bridge, mirroring `planSymlinks`' rule: the
+     * raw readlink target must resolve under this installation's
+     * `dist/pi-bridge/` directory, or be a byte-identical bundle at the
+     * Trellis artifact shape left by a previous install root. Anything else
+     * is the user's and stays.
+     */
+    private isOwnedBridgeSymlink;
     apply(plan: AdapterPlanItem[], backup: BackupSession): Promise<void>;
     verify(canonical: CanonicalSource): Promise<AdapterVerifyResult>;
 }

package/dist/adapters/pi.js

@@ -3,20 +3,39 @@
  * symlinked to canonical `agents.md` — specifically `AGENTS.md`, not
  * `AGENTS.override.md` (design.md D3, trellis-sync-p1: pi checks the
  * override name first, and Trellis's managed file is the baseline, not an
- * override of something else). pi has no native MCP client (docs/research.md),
- * so MCP access is delivered as a single symlinked bridge extension
- * instead of native config (trellis-pi-mcp-bridge-p4) — a different
- * mechanism from every other agent's config-generation adapter, but the
- * same symlink create/repair/remove machinery as skills/instructions.
+ * override of something else).
+ *
+ * MCP delivery is version-gated (trellis-pi-native-mcp-migration):
+ *
+ * - pi >= 1.1.0 has a native MCP client, so `trellis mcp sync` merges
+ *   Trellis-managed entries into `~/.pi/agent/mcp.json` through the shared
+ *   `planJsonMcp`/`applyJsonMcp` machinery (ownership ledger, conflict
+ *   detection, user entries preserved) with the pi-shaped renderer from
+ *   `piMcp.ts`. Gateway route → the single `trellis` runtime entry;
+ *   agent-owned OAuth servers → bare `{url}` entries the user authorizes
+ *   with `pi mcp login`.
+ * - Older pis (or an unprobeable version) keep the legacy delivery: a
+ *   single symlinked bridge extension (`dist/pi-bridge/bundle.js`,
+ *   trellis-pi-mcp-bridge-p4). The version gate never moves a machine
+ *   FROM the bridge TO native until the mcp.json write succeeds — the
+ *   bridge-removal item rides along in the same plan, ordered after the
+ *   config write, and is withheld entirely when any write conflicts
+ *   (design.md D3: the two deliveries may never be active at once, every
+ *   tool would register twice).
  */
+import { existsSync, lstatSync, readFileSync, readlinkSync } from "node:fs";
 import { dirname, join, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
-import { readFileSync } from "node:fs";
 import { isInScope } from "../core/adapter.js";
 import { usesNativeCapabilityDelivery } from "../core/types.js";
 import * as piProbe from "../probes/pi.js";
+import { probePiVersion } from "../probes/pi.js";
 import { applySymlinkPlan, planSymlinks } from "./symlinkPlan.js";
+import { applyJsonMcp, planJsonMcp } from "./jsonMcp.js";
+import { piRenderer, supportsNativeMcp } from "./piMcp.js";
+import { loadMcpOwnership, ownedByAgent, recordOwned, forgetOwned, saveMcpOwnership } from "../lib/mcpOwnership.js";
+import { currentLinkTarget } from "../lib/backup.js";
 const BRIDGE_SYMLINK_NAME = "trellis-mcp-bridge.js";
 /**
  * A source-checkout bridge can survive a switch to the packaged CLI. Adopt it
@@ -61,10 +80,15 @@ function resolveBridgeFile() {
 }
 export class PiAdapter {
     homeDir;
+    versionProbe;
     name = "pi";
     id = "pi";
-    constructor(homeDir = homedir()) {
+    constructor(homeDir = homedir(), 
+    /** Test seam: the version gate must not depend on whatever pi happens
+     * to be installed on the machine running the tests. */
+    versionProbe = probePiVersion) {
         this.homeDir = homeDir;
+        this.versionProbe = versionProbe;
     }
     async probe() {
         const snapshot = await piProbe.probe(this.homeDir);
@@ -88,6 +112,9 @@ export class PiAdapter {
             canonicalRoot,
             kind: "instructions",
         });
+        if (supportsNativeMcp(this.versionProbe())) {
+            return [...skillItems, ...instructionsItems, ...this.planNativeMcp(canonical)];
+        }
         const { file: bridgeFile, symlinkName } = resolveBridgeFile();
         const extensionItems = planSymlinks({
             rootDir: join(agentDir, "extensions"),
@@ -101,8 +128,104 @@ export class PiAdapter {
         });
         return [...skillItems, ...instructionsItems, ...extensionItems];
     }
+    /**
+     * Native-delivery plan (design.md D1/D3). The write items come from the
+     * shared JSON machinery unchanged; the bridge-removal item is appended
+     * last and re-cast to kind "mcp" so it travels through `trellis mcp
+     * sync` — the same command that writes mcp.json — never through bare
+     * `trellis sync`. That is what makes the migration atomic from the
+     * user's point of view: the config lands and the bridge leaves in one
+     * apply, and a bare skills/instructions sync can neither remove the
+     * bridge early nor resurrect it afterwards.
+     */
+    planNativeMcp(canonical) {
+        const agentDir = join(this.homeDir, ".pi", "agent");
+        const configPath = join(agentDir, "mcp.json");
+        const parsed = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf-8")) : undefined;
+        const ownership = ownedByAgent(loadMcpOwnership(this.homeDir), this.id);
+        const items = planJsonMcp({
+            configPath,
+            parsed,
+            mcp: canonical.mcp,
+            agentId: this.id,
+            managedAgents: canonical.managedAgents,
+            policy: canonical.secretsPolicy,
+            ownership,
+            render: piRenderer,
+        }).map((item) => {
+            // pi speaks stdio and streamable HTTP only — an sse server gets an
+            // honest conflict instead of an entry pi could never connect.
+            const write = item.mcpWrite;
+            if (write?.def.transport !== "sse")
+                return item;
+            return {
+                action: "conflict",
+                kind: "mcp",
+                target: item.target,
+                description: `MCP server "${write.name}" uses the sse transport, which pi does not support (stdio and streamable HTTP only) — no entry written to ${item.target}`,
+                remediation: "switch the server to streamable HTTP or stdio, or scope it away from pi",
+            };
+        });
+        const bridgePath = join(agentDir, "extensions", BRIDGE_SYMLINK_NAME);
+        const hasConflict = items.some((item) => item.action === "conflict");
+        if (!hasConflict && this.isOwnedBridgeSymlink(bridgePath)) {
+            items.push({
+                action: "remove",
+                kind: "mcp",
+                target: bridgePath,
+                description: `remove Trellis MCP bridge extension ${bridgePath} — pi >= 1.1.0 receives MCP natively via mcp.json`,
+            });
+        }
+        return items;
+    }
+    /**
+     * Removal ownership for the bridge, mirroring `planSymlinks`' rule: the
+     * raw readlink target must resolve under this installation's
+     * `dist/pi-bridge/` directory, or be a byte-identical bundle at the
+     * Trellis artifact shape left by a previous install root. Anything else
+     * is the user's and stays.
+     */
+    isOwnedBridgeSymlink(bridgePath) {
+        const stat = lstatSync(bridgePath, { throwIfNoEntry: false });
+        if (!stat?.isSymbolicLink())
+            return false;
+        const rawTarget = readlinkSync(bridgePath);
+        const { file } = resolveBridgeFile();
+        const bridgeRoot = dirname(file);
+        const resolved = rawTarget.startsWith(sep) ? rawTarget : join(dirname(bridgePath), rawTarget);
+        if (resolved === file || resolved.startsWith(bridgeRoot.endsWith(sep) ? bridgeRoot : `${bridgeRoot}${sep}`))
+            return true;
+        return isEquivalentTrellisBridge(resolved, file);
+    }
     async apply(plan, backup) {
-        await applySymlinkPlan(plan, backup);
+        await applySymlinkPlan(plan.filter((item) => item.kind !== "mcp"), backup);
+        // Real config writes carry mcpWrite/mcpRemove; the bridge-removal
+        // item is the only kind:"mcp" entry without either, and it must run
+        // strictly after the config write (design.md D3).
+        const mcpWrites = plan.filter((item) => item.kind === "mcp" && (item.mcpWrite || item.mcpRemove));
+        const bridgeRemovals = plan.filter((item) => item.kind === "mcp" && item.action === "remove" && !item.mcpWrite && !item.mcpRemove);
+        if (mcpWrites.length > 0) {
+            const configPath = mcpWrites[0].target;
+            const parsed = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf-8")) : undefined;
+            const merged = applyJsonMcp(parsed, mcpWrites, piRenderer);
+            backup.writeFile(configPath, `${JSON.stringify(merged, null, 2)}\n`);
+            let ownership = loadMcpOwnership(this.homeDir);
+            for (const item of mcpWrites) {
+                if (item.action === "create" && item.mcpWrite) {
+                    ownership = recordOwned(ownership, this.id, item.mcpWrite.name, piRenderer(item.mcpWrite.def, item.mcpWrite.name));
+                }
+                else if (item.action === "remove" && item.mcpRemove) {
+                    ownership = forgetOwned(ownership, this.id, item.mcpRemove.name);
+                }
+            }
+            saveMcpOwnership(this.homeDir, ownership);
+        }
+        for (const item of bridgeRemovals) {
+            const oldTarget = await currentLinkTarget(item.target);
+            if (oldTarget === undefined)
+                continue; // already gone — nothing to record
+            await backup.removeSymlink(item.target, oldTarget);
+        }
     }
     async verify(canonical) {
         const snapshot = await piProbe.probe(this.homeDir);
@@ -122,6 +245,26 @@ export class PiAdapter {
                 mismatches.push(`skill "${name}" is present on disk but not in canonical scope for pi`);
             }
         }
+        if (supportsNativeMcp(this.versionProbe())) {
+            // Native mode drift: anything the plan still wants to change is by
+            // definition drift. The plan only ever names Trellis-owned entries
+            // (the ownership ledger gates removals), so user-authored servers
+            // can never surface here.
+            for (const item of this.planNativeMcp(canonical)) {
+                if (item.action === "create" && item.mcpWrite) {
+                    mismatches.push(`mcp.json entry "${item.mcpWrite.name}" is missing or differs from canonical — run trellis mcp sync`);
+                }
+                else if (item.action === "remove" && item.mcpRemove) {
+                    mismatches.push(`mcp.json entry "${item.mcpRemove.name}" is Trellis-owned but no longer in canonical — run trellis mcp sync`);
+                }
+                else if (item.action === "remove") {
+                    mismatches.push(`the Trellis MCP bridge extension is still installed but pi >= 1.1.0 uses native mcp.json — run trellis mcp sync`);
+                }
+                else if (item.action === "conflict") {
+                    mismatches.push(item.description);
+                }
+            }
+        }
         return mismatches.length === 0 ? { ok: true } : { ok: false, mismatches };
     }
 }

package/dist/adapters/piMcp.d.ts

@@ -0,0 +1,38 @@
+/**
+ * pi's native MCP config (pi >= 1.1.0) — the entry renderer and the
+ * version gate that chooses between it and the legacy bridge extension
+ * (openspec/changes/pi-native-mcp-migration design.md D1/D2).
+ *
+ * pi's mcp.json has no `type` discriminator: an entry is stdio when it
+ * carries `command`, streamable HTTP when it carries `url`. `${VAR}`
+ * references in `env`/`headers` values are expanded by pi at spawn
+ * (verified empirically against pi 1.1.0 on 2026-10-11), so the
+ * zero-plaintext rendering every other JSON agent relies on works
+ * unchanged. sse is not a pi transport — the adapter turns sse servers
+ * into conflict items rather than writing entries pi cannot connect.
+ */
+import type { McpServerDef } from "../core/types.js";
+/** The pi release that introduced the native MCP client (`pi mcp`,
+ * `~/.pi/agent/mcp.json`). */
+export declare const PI_NATIVE_MCP_SINCE = "1.1.0";
+/**
+ * Version gate (design.md D2): native delivery only when the probed
+ * version is known to understand mcp.json. Anything unparseable —
+ * including "binary not on PATH" (undefined) — falls back to the bridge,
+ * never the other way round: writing config a pi cannot read is worse
+ * than keeping a working bridge.
+ */
+export declare function supportsNativeMcp(version: string | undefined): boolean;
+/**
+ * pi-shaped rendering of a canonical server definition — the same shape
+ * `pi mcp add` writes (observed 2026-10-11): stdio as
+ * `{command, args, env?}`, http as `{url, headers?}`, no `type` field.
+ * `env` names render as `${VAR}` references exactly like the other JSON
+ * agents; OAuth `auth` metadata is Trellis-side routing information and is
+ * never rendered — with one exception: a declared `auth.client_name` becomes
+ * the entry's `oauth.clientName`, the field `pi mcp add --oauth-client-name`
+ * writes, so providers that gate dynamic client registration by client name
+ * (Figma) accept `pi mcp login`'s registration and later syncs compare equal
+ * instead of stripping the block (oauth-client-name design.md D2).
+ */
+export declare function piRenderer(def: McpServerDef, _name: string): Record<string, unknown>;

package/dist/adapters/piMcp.js

@@ -0,0 +1,65 @@
+/**
+ * pi's native MCP config (pi >= 1.1.0) — the entry renderer and the
+ * version gate that chooses between it and the legacy bridge extension
+ * (openspec/changes/pi-native-mcp-migration design.md D1/D2).
+ *
+ * pi's mcp.json has no `type` discriminator: an entry is stdio when it
+ * carries `command`, streamable HTTP when it carries `url`. `${VAR}`
+ * references in `env`/`headers` values are expanded by pi at spawn
+ * (verified empirically against pi 1.1.0 on 2026-10-11), so the
+ * zero-plaintext rendering every other JSON agent relies on works
+ * unchanged. sse is not a pi transport — the adapter turns sse servers
+ * into conflict items rather than writing entries pi cannot connect.
+ */
+import { isOAuthAuth } from "../core/types.js";
+import { resolvedEnvTextMap } from "../lib/mcpMigrateRead.js";
+/** The pi release that introduced the native MCP client (`pi mcp`,
+ * `~/.pi/agent/mcp.json`). */
+export const PI_NATIVE_MCP_SINCE = "1.1.0";
+/**
+ * Version gate (design.md D2): native delivery only when the probed
+ * version is known to understand mcp.json. Anything unparseable —
+ * including "binary not on PATH" (undefined) — falls back to the bridge,
+ * never the other way round: writing config a pi cannot read is worse
+ * than keeping a working bridge.
+ */
+export function supportsNativeMcp(version) {
+    if (version === undefined)
+        return false;
+    const match = /^(\d+)\.(\d+)(?:\.(\d+))?/.exec(version.trim());
+    if (!match)
+        return false;
+    const major = Number(match[1]);
+    const minor = Number(match[2]);
+    return major > 1 || (major === 1 && minor >= 1);
+}
+/**
+ * pi-shaped rendering of a canonical server definition — the same shape
+ * `pi mcp add` writes (observed 2026-10-11): stdio as
+ * `{command, args, env?}`, http as `{url, headers?}`, no `type` field.
+ * `env` names render as `${VAR}` references exactly like the other JSON
+ * agents; OAuth `auth` metadata is Trellis-side routing information and is
+ * never rendered — with one exception: a declared `auth.client_name` becomes
+ * the entry's `oauth.clientName`, the field `pi mcp add --oauth-client-name`
+ * writes, so providers that gate dynamic client registration by client name
+ * (Figma) accept `pi mcp login`'s registration and later syncs compare equal
+ * instead of stripping the block (oauth-client-name design.md D2).
+ */
+export function piRenderer(def, _name) {
+    if (def.transport === "http" || def.transport === "sse") {
+        const entry = { url: def.url };
+        if (def.headers && Object.keys(def.headers).length > 0) {
+            entry.headers = def.headers;
+        }
+        if (isOAuthAuth(def.auth) && typeof def.auth === "object" && def.auth.clientName !== undefined) {
+            entry.oauth = { clientName: def.auth.clientName };
+        }
+        return entry;
+    }
+    const entry = { command: def.command, args: def.args ?? [] };
+    const env = resolvedEnvTextMap(def);
+    if (Object.keys(env).length > 0) {
+        entry.env = env;
+    }
+    return entry;
+}

package/dist/commands/mcp.js

@@ -111,6 +111,12 @@ export function printReport(report, dryRun) {
         for (const item of [...created, ...removed, ...conflicts]) {
             console.log(`   - [${item.action}] ${item.description}`);
         }
+        // pi does not watch mcp.json (verified 2026-10-11): without this hint
+        // a changed config silently only takes effect on the next pi launch
+        // (trellis-pi-native-mcp-migration design.md D5).
+        if (agent === "pi" && (created.length > 0 || removed.length > 0)) {
+            console.log("   pi does not watch mcp.json — restart pi or run /reload to pick up MCP changes");
+        }
     }
 }
 function serversYamlPath(homeDir) {

package/dist/core/canonical.d.ts

@@ -10,9 +10,10 @@ import type { BackupSession } from "../lib/backup.js";
  * The on-disk shape for one server entry — `static_env`/`env_aliases`
  * (snake_case, like every other multi-word key across `.trellis/*.yaml`)
  * are translated to `McpServerDef.staticEnv`/`envAliases` (camelCase)
- * below, and `auth`'s object form carries `client_id`/`client_secret_env`
- * the same way (trellis-mcp-static-env-and-disabled-servers,
- * trellis-migrate-env-var-alias, trellis-mcp-oauth-static-client).
+ * below, and `auth`'s object form carries `client_id`/`client_secret_env`/
+ * `client_name` the same way (trellis-mcp-static-env-and-disabled-servers,
+ * trellis-migrate-env-var-alias, trellis-mcp-oauth-static-client,
+ * oauth-client-name).
  */
 type McpServerDefYaml = Omit<McpServerDef, "staticEnv" | "envAliases" | "auth"> & {
     static_env?: Record<string, string>;
@@ -28,6 +29,7 @@ type McpAuthYaml = string | {
     owner?: unknown;
     client_id?: unknown;
     client_secret_env?: unknown;
+    client_name?: unknown;
 };
 /** Inverse of `fromServerDefYaml` (trellis-canonical-cli-crud) — strips
  * `undefined` fields so the written YAML never gets a literal `null`

package/dist/core/canonical.js

@@ -34,12 +34,12 @@ function fromAuthYaml(serverName, auth) {
     if (auth === "oauth")
         return "oauth";
     if (typeof auth !== "object" || auth === null) {
-        throw new Error(`mcp/servers.yaml: "${serverName}" auth must be the scalar "oauth" or { kind: oauth, client_id?, client_secret_env? }`);
+        throw new Error(`mcp/servers.yaml: "${serverName}" auth must be the scalar "oauth" or { kind: oauth, client_id?, client_secret_env?, client_name? }`);
     }
-    const { kind, owner, client_id, client_secret_env, ...extra } = auth;
+    const { kind, owner, client_id, client_secret_env, client_name, ...extra } = auth;
     const unknownKey = Object.keys(extra)[0];
     if (unknownKey !== undefined) {
-        throw new Error(`mcp/servers.yaml: "${serverName}" auth has unrecognized key "${unknownKey}" — expected kind, owner, client_id, client_secret_env`);
+        throw new Error(`mcp/servers.yaml: "${serverName}" auth has unrecognized key "${unknownKey}" — expected kind, owner, client_id, client_secret_env, client_name`);
     }
     if (kind !== "oauth") {
         throw new Error(`mcp/servers.yaml: "${serverName}" auth.kind must be "oauth" — kind is the only recognized discriminator`);
@@ -50,6 +50,9 @@ function fromAuthYaml(serverName, auth) {
     if (client_secret_env !== undefined && (typeof client_secret_env !== "string" || !isValidSecretVarName(client_secret_env))) {
         throw new Error(`mcp/servers.yaml: "${serverName}" auth.client_secret_env must be a variable NAME (e.g. FIGMA_CLIENT_SECRET), never a secret value`);
     }
+    if (client_name !== undefined && typeof client_name !== "string") {
+        throw new Error(`mcp/servers.yaml: "${serverName}" auth.client_name must be a string`);
+    }
     const out = { kind: "oauth" };
     if (owner !== undefined && owner !== "agent" && owner !== "trellis")
         throw new Error(`mcp/servers.yaml: "${serverName}" auth.owner must be agent or trellis`);
@@ -59,6 +62,8 @@ function fromAuthYaml(serverName, auth) {
         out.clientId = client_id;
     if (typeof client_secret_env === "string")
         out.clientSecretEnv = client_secret_env;
+    if (typeof client_name === "string")
+        out.clientName = client_name;
     return out;
 }
 /** Inverse of `fromServerDefYaml` (trellis-canonical-cli-crud) — strips
@@ -80,6 +85,7 @@ export function toServerDefYaml(def) {
                     ...(auth.owner !== undefined ? { owner: auth.owner } : {}),
                     ...(auth.clientId !== undefined ? { client_id: auth.clientId } : {}),
                     ...(auth.clientSecretEnv !== undefined ? { client_secret_env: auth.clientSecretEnv } : {}),
+                    ...(auth.clientName !== undefined ? { client_name: auth.clientName } : {}),
                 };
     }
     for (const key of Object.keys(out)) {

package/dist/core/types.d.ts

@@ -19,6 +19,10 @@ export interface McpAuthConfig {
     owner?: "agent" | "trellis";
     clientId?: string;
     clientSecretEnv?: string;
+    /** Self-asserted display name an Agent presents at dynamic client
+     * registration — for providers that gate DCR by client name (Figma).
+     * Public metadata, not a credential (oauth-client-name design.md D1). */
+    clientName?: string;
 }
 /** True when `auth` classifies the server as OAuth, in either form. Every
  * former `def.auth === "oauth"` check must go through this now that the

package/dist/pi-bridge/bundle.js

@@ -7948,12 +7948,12 @@ function fromServerDefYaml(serverName, def) {
 function fromAuthYaml(serverName, auth2) {
   if (auth2 === "oauth") return "oauth";
   if (typeof auth2 !== "object" || auth2 === null) {
-    throw new Error(`mcp/servers.yaml: "${serverName}" auth must be the scalar "oauth" or { kind: oauth, client_id?, client_secret_env? }`);
+    throw new Error(`mcp/servers.yaml: "${serverName}" auth must be the scalar "oauth" or { kind: oauth, client_id?, client_secret_env?, client_name? }`);
   }
-  const { kind, owner, client_id, client_secret_env, ...extra } = auth2;
+  const { kind, owner, client_id, client_secret_env, client_name, ...extra } = auth2;
   const unknownKey = Object.keys(extra)[0];
   if (unknownKey !== void 0) {
-    throw new Error(`mcp/servers.yaml: "${serverName}" auth has unrecognized key "${unknownKey}" \u2014 expected kind, owner, client_id, client_secret_env`);
+    throw new Error(`mcp/servers.yaml: "${serverName}" auth has unrecognized key "${unknownKey}" \u2014 expected kind, owner, client_id, client_secret_env, client_name`);
   }
   if (kind !== "oauth") {
     throw new Error(`mcp/servers.yaml: "${serverName}" auth.kind must be "oauth" \u2014 kind is the only recognized discriminator`);
@@ -7964,11 +7964,15 @@ function fromAuthYaml(serverName, auth2) {
   if (client_secret_env !== void 0 && (typeof client_secret_env !== "string" || !isValidSecretVarName(client_secret_env))) {
     throw new Error(`mcp/servers.yaml: "${serverName}" auth.client_secret_env must be a variable NAME (e.g. FIGMA_CLIENT_SECRET), never a secret value`);
   }
+  if (client_name !== void 0 && typeof client_name !== "string") {
+    throw new Error(`mcp/servers.yaml: "${serverName}" auth.client_name must be a string`);
+  }
   const out = { kind: "oauth" };
   if (owner !== void 0 && owner !== "agent" && owner !== "trellis") throw new Error(`mcp/servers.yaml: "${serverName}" auth.owner must be agent or trellis`);
   if (owner !== void 0) out.owner = owner;
   if (typeof client_id === "string") out.clientId = client_id;
   if (typeof client_secret_env === "string") out.clientSecretEnv = client_secret_env;
+  if (typeof client_name === "string") out.clientName = client_name;
   return out;
 }
 function trellisRoot(homeDir) {

package/dist/probes/pi.d.ts

@@ -5,10 +5,13 @@
  * and `dist/core/resource-loader.js` (`loadContextFileFromDir(resolvedAgentDir)`),
  * not by assumption. See design.md D5 (openspec/changes/trellis-doctor-p0).
  *
- * pi has no native MCP client (docs/research.md) — nothing to read or
- * probe, so `mcpServers` is always empty here. That's real information
- * (this is why P4 has to write a runtime bridge extension instead of
- * generating config), not an omission.
+ * pi >= 1.1.0 has a native MCP client (`~/.pi/agent/mcp.json`), which the
+ * adapter manages (trellis-pi-native-mcp-migration); the probe still
+ * reports `mcpServers: []` because server health is the runtime's job,
+ * not the probe's. `probePiVersion` is split out so the adapter's
+ * native-vs-bridge version gate shares exactly this exec and tests can
+ * inject a seam.
  */
 import type { AgentSnapshot } from "../core/types.js";
+export declare function probePiVersion(): string | undefined;
 export declare function probe(homeDir?: string): Promise<AgentSnapshot>;

package/dist/probes/pi.js

@@ -5,16 +5,26 @@
  * and `dist/core/resource-loader.js` (`loadContextFileFromDir(resolvedAgentDir)`),
  * not by assumption. See design.md D5 (openspec/changes/trellis-doctor-p0).
  *
- * pi has no native MCP client (docs/research.md) — nothing to read or
- * probe, so `mcpServers` is always empty here. That's real information
- * (this is why P4 has to write a runtime bridge extension instead of
- * generating config), not an omission.
+ * pi >= 1.1.0 has a native MCP client (`~/.pi/agent/mcp.json`), which the
+ * adapter manages (trellis-pi-native-mcp-migration); the probe still
+ * reports `mcpServers: []` because server health is the runtime's job,
+ * not the probe's. `probePiVersion` is split out so the adapter's
+ * native-vs-bridge version gate shares exactly this exec and tests can
+ * inject a seam.
  */
 import { execFileSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { pathRef, scanSkillRoot } from "../lib/probeCommon.js";
+export function probePiVersion() {
+    try {
+        return execFileSync("pi", ["--version"], { encoding: "utf-8", timeout: 5_000 }).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Priority order pi itself checks (`loadContextFileFromDir`), first match wins. */
 const INSTRUCTIONS_CANDIDATES = ["AGENTS.override.md", "AGENTS.md", "AGENTS.MD", "CLAUDE.md", "CLAUDE.MD"];
 export async function probe(homeDir = homedir()) {
@@ -25,13 +35,8 @@ export async function probe(homeDir = homedir()) {
     if (!present) {
         return { agent: "pi", present: false, skillRoots: [], mcpServers: [], diagnostics: [] };
     }
-    let version;
-    try {
-        version = execFileSync("pi", ["--version"], { encoding: "utf-8", timeout: 5_000 }).trim();
-    }
-    catch {
-        // config exists without the binary on PATH — unusual, still probeable
-    }
+    // config can exist without the binary on PATH — unusual, still probeable
+    const version = probePiVersion();
     const skillRoot = scanSkillRoot(skillsPath);
     let instructionsFile;
     for (const candidate of INSTRUCTIONS_CANDIDATES) {

package/docs/getting-started.md

@@ -291,6 +291,44 @@ that advertises `--prompt`, `--resume`, and `--output-format`. A desktop-only
 profile can still receive managed configuration; Trellis never launches the
 desktop application's private helper or bundled runtime path.
 
+## pi native MCP (pi ≥ 1.1.0)
+
+pi 1.1.0 added a native MCP client, and Trellis delivers to it the same way
+as every other JSON-config agent: `trellis mcp sync` merges Trellis-managed
+entries into `~/.pi/agent/mcp.json` — the single `trellis` edge entry in
+gateway mode, plus a bare `{url}` entry for each agent-owned OAuth server.
+Servers you added yourself (anything Trellis never wrote) are preserved
+untouched, and the legacy bridge extension (`~/.pi/agent/extensions/
+trellis-mcp-bridge.js`) is removed in the same run, after the config write.
+
+Two pi-specific behaviors to know:
+
+- pi does not watch `mcp.json`: after a sync that changed it, restart pi or
+  run `/reload` in an open session (sync prints this hint).
+- Agent-owned OAuth servers (e.g. `figma`) are authorized by pi itself:
+  run `pi mcp login <name>` once; the grant lives in pi's own token store
+  (`~/.pi/agent/mcp-auth.json`), and `trellis.mcp.status` reports them as
+  `agent-managed`.
+- Some providers (Figma, while in beta) gate OAuth dynamic client
+  registration by an allowlisted `client_name`, which rejects pi's default.
+  Declare the name canonically and pi registers under it:
+
+  ```yaml
+  figma:
+    transport: http
+    url: https://mcp.figma.com/mcp
+    auth:
+      kind: oauth
+      client_name: Claude Code
+  ```
+
+  Trellis then writes `oauth.clientName` into the pi entry — the same field
+  `pi mcp add --oauth-client-name` writes — so syncs converge instead of
+  stripping it.
+
+On pi older than 1.1.0 nothing changes: the bridge extension remains the
+delivery mechanism and `mcp.json` is never written.
+
 ## Trellis Runtime Skill
 
 `trellis-runtime` is the built-in operating guide that Trellis installs into

package/docs/mcp-oauth-renewal.md

@@ -1,6 +1,6 @@
 # Scheduled OAuth renewal — `trellis mcp renew`
 
-The gateway and the pi bridge already refresh OAuth tokens silently before
+The gateway/runtime edge already refreshes 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
@@ -17,7 +17,8 @@ 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
+renewed nor reported here — for pi ≥ 1.1.0 that client-side authorization is
+`pi mcp login <name>`, stored in pi's own `~/.pi/agent/mcp-auth.json`. 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

package/docs/research.md

@@ -236,10 +236,13 @@ Reverse-engineered directly from the installed binary
 - pi **natively discovers** `AGENTS.override.md`, `AGENTS.md`, `CLAUDE.md`
   (in that priority order) — instructions and `SKILL.md`-format skills need
   no adapter work at all.
-- pi has **no native MCP client**. The only `mcpServers` string in its bundle
-  belongs to the Google Gen AI SDK's Vertex tool-schema translator, which
-  explicitly throws `"mcpServers parameter is not supported"` — unrelated to
-  MCP proper.
+- pi **gained a native MCP client in 1.1.0** (`pi mcp add/list/login`,
+  `~/.pi/agent/mcp.json`, stdio + streamable HTTP, `${VAR}` expansion in
+  `env`/`headers`, OAuth into its own `mcp-auth.json` store) — Trellis delivers
+  to it natively (trellis-pi-native-mcp-migration). Before 1.1.0 the only
+  `mcpServers` string in its bundle belonged to the Google Gen AI SDK's Vertex
+  tool-schema translator, which explicitly throws `"mcpServers parameter is
+  not supported"` — that era is why the bridge extension below exists.
 - pi's capability surface is **extensions**: JS modules loaded via
   `--extension`/discovery, with a real API (`createExtension`,
   `registerTool`). Giving pi access to the same MCP servers every other agent

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-trellis",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "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",