agent-trellis 0.12.0 → 0.14.0

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,28 @@ 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`.
+
+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
@@ -907,6 +929,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

@@ -49,11 +49,30 @@ 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. It exercises
-real browser CORS, PKCE callback, progress, cancellation, retry and owner
-confirmation without contacting a real provider or using personal credentials.
+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,89 @@
+# Scheduled OAuth renewal — `trellis mcp renew`
+
+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
+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 — 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
+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/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.12.0",
+  "version": "0.14.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",