@vanillagreen/pi-claude-bridge 1.8.0 → 1.9.0

package/README.md

@@ -11,13 +11,14 @@ Forked from [`elidickinson/pi-claude-bridge`](https://github.com/elidickinson/pi
 
 ## Highlights
 
-- `claude-bridge/claude-fable-5`, Sonnet 5, Opus 4.8, Opus 4.7, Sonnet 4.6, and Haiku in `/model`.
+- `claude-bridge/claude-fable-5`, Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, Sonnet 5, Sonnet 4.6, and Haiku in `/model`. `/model opus` selects Opus 5; older Opus releases stay selectable by full ID.
 - Pi tool calls run on Pi; Claude Code handles reasoning.
 - Tool-use turns block until Pi-delivered tool results reach Claude Code, including persistent subagent panes.
 - Session continuity across normal turns, `/compact`, tree navigation, and abort recovery.
 - Thinking-level forwarding with summarized Opus thinking display.
 - Optional Claude effort overrides (`xhigh` → `max` for Opus 4.8).
 - MCP isolation and Claude cloud-MCP suppression to keep tokens lean.
+- Optional access to your Claude account's connectors — Gmail, Calendar, Drive, Slack, Jira, Confluence — read-only by default.
 - Opt-in forwarding of `APPEND_SYSTEM.md` and recognized Pi prompt hooks.
 
 ## Install
@@ -86,7 +87,7 @@ Project settings in `.pi/settings.json` apply only after Pi marks the workspace
 | Model effort overrides | JSON object mapping model IDs to Claude Code efforts, e.g. `{"claude-opus-4-8":"max"}`. Per-model entries beat the global force setting. |
 | Claude executable path | Explicit `claude` binary path; empty auto-detects. |
 
-Pi 0.80.6 and newer expose native `max` thinking. Fable 5 bridge metadata forwards both `xhigh` and `max`; **Force Claude effort** and **Model effort overrides** remain available when one bridge model needs a different fixed effort. For example, to force only Opus 4.8 to `max`:
+Pi 0.80.6 and newer expose native `max` thinking. Fable 5, Opus 5, and Sonnet 5 bridge metadata forward both `xhigh` and `max`; the generic bridge fallback also maps `max` directly. **Force Claude effort** and **Model effort overrides** remain available when one bridge model needs a different fixed effort. For example, to force only Opus 4.8 to `max`:
 
 ```json
 {"claude-opus-4-8":"max"}
@@ -96,11 +97,39 @@ Keys may be bare model IDs (`claude-opus-4-8`), `claude-bridge/<id>`, or `*` for
 
 ### Connectors
 
-The bridge can expose the authenticated Claude account's claude.ai cloud MCP connectors (Gmail, Google Calendar, Google Drive) to the model. These are low-level `provider` options (set in `settings.json` under the extension-manager config, or via env). Off by default so Pi owns tool execution.
+Turn this on and the model can use whatever your Claude account already has connected — the same connectors you use in the Claude app, now inside Pi:
 
-| Option (`provider.*`) | Env var | Values | Default | What it does |
+- **Gmail** — search mail, read threads and messages.
+- **Google Calendar** — check calendars and events.
+- **Google Drive** — find and read files.
+- **Slack** — search and read channels, threads, canvases, and people.
+- **Jira and Confluence** — search and read issues, pages, and spaces.
+- Anything else on the account (Figma, org-specific connectors) works the same way — nothing to configure per connector.
+
+Sessions are **read-only** by default: the model can look things up, but cannot send, post, or change anything unless you explicitly turn writes on below.
+
+Extension-manager settings use flat package-scoped keys:
+
+```json
+{
+  "vstack": {
+    "extensionManager": {
+      "config": {
+        "@vanillagreen/pi-claude-bridge": {
+          "enableConnectors": true,
+          "connectorWriteMode": "deny"
+        }
+      }
+    }
+  }
+}
+```
+
+Legacy `.pi/claude-bridge.json` configuration keeps these options nested under `provider`. Environment variables work with either format. Connectors remain off by default so Pi owns tool execution.
+
+| Extension-manager key | Env var | Values | Default | What it does |
 | --- | --- | --- | --- | --- |
-| `enableConnectors` | `CLAUDE_BRIDGE_ENABLE_CONNECTORS` | `true`/`false` | off | Expose the account's Gmail/Calendar/Drive connectors to the model (env OR config enables). |
+| `enableConnectors` | `CLAUDE_BRIDGE_ENABLE_CONNECTORS` | `true`/`false` | off | Expose the account's connectors to the model (env OR config enables). |
 | `connectorWriteMode` | `CLAUDE_BRIDGE_CONNECTOR_WRITE` | `deny`/`allow` | `deny` | When connectors are enabled, whether their WRITE tools are exposed. |
 
 For both, the env var wins over config. `connectorWriteMode` only matters when connectors are enabled. Any value other than exactly `allow` is treated as `deny` (fail-closed).
@@ -108,7 +137,7 @@ For both, the env var wins over config. `connectorWriteMode` only matters when c
 With `connectorWriteMode: "deny"` (the default), connector sessions are **read-only**: search/read/fetch/list tools stay available, but mutating tools (Gmail `create_draft`/labels, Calendar `create_event`/`update_event`/`delete_event`/`respond_to_event`, Drive `create_file`/`copy_file`) are denied. Enforcement is two-layered:
 
 - **Model context:** the known write tools are passed as `disallowedTools` (exact tool ids), so the model does not see them. (Note: the CLI's MCP permission matcher only supports exact tool names or a whole-server `mcp__server__*` glob — partial tool-segment globs are inert — so exact ids are what actually removes today's writes.)
-- **Runtime:** a `PreToolUse` hook blocks any connector tool classified as a write at call time, regardless of permission mode. Classification is **fail-closed** — a tool on a connector namespace is a write unless its verb is a known read prefix (`list_`, `search_`, `get_`, `read_`, `fetch_`, …). This covers not-yet-known write tools (e.g. a future Gmail `send_message` or Drive `delete_file`) that the static id list can't enumerate.
+- **Runtime:** a `PreToolUse` hook blocks any connector tool classified as a write at call time, regardless of permission mode. Classification is **fail-closed** and covers the whole `mcp__claude_ai_<Server>__` space — a tool there is a write unless its name *begins* with a known read verb (`list`, `search`, `get`, `read`, `fetch`, …). The verb is matched as a word across naming styles, since connector servers differ: `search_threads` (Gmail), `slack_read_channel` (Slack, server-prefixed), `getJiraIssue` (Atlassian, camelCase) are all reads; a leading word that merely repeats the server name is skipped first. A name that opens with a read verb but also names a mutation (`getOrCreateChannel`) is a write, and so is a name that does not parse as `<server>__<tool>`. This covers both not-yet-known write tools (e.g. a future Gmail `send_message` or Drive `delete_file`) and connectors beyond the Google trio: claude.ai connectors attach account-wide, so a Slack/Atlassian/org-custom connector is visible in a connector session, and its writes are denied by the same rule.
 
 Set `allow` only for a one-shot write-executor session that has already obtained explicit user approval — never for an interactive connector chat.
 
@@ -118,16 +147,37 @@ Set `allow` only for a one-shot write-executor session that has already obtained
 
 Host apps that embed the bridge and own every config dir explicitly can set `CLAUDE_BRIDGE_ISOLATED=1` in the bridge process env. Isolated mode disables every cwd/home discovery fallback so nothing outside the host-owned dirs is read:
 
-- no cwd-ancestor `AGENTS.md` walk — instructions come only from `<PI_CODING_AGENT_DIR>/AGENTS.md`;
+- no `AGENTS.md` discovery, including cwd ancestors and the shared `<PI_CODING_AGENT_DIR>/AGENTS.md`;
+- no extension-manager overlay from `<PI_CODING_AGENT_DIR>/settings.json`;
 - no project `.pi/settings.json` / `.pi/claude-bridge.json` reads (even for trusted projects);
 - no project `.pi/APPEND_SYSTEM.md`;
 - no `$PATH` search for the `claude` executable — the host either pins `pathToClaudeCodeExecutable` or gets the Claude Agent SDK's bundled default.
 
-Config, logs, and `AGENTS.md` all resolve under `PI_CODING_AGENT_DIR`. Normal pi CLI usage (flag unset) is unchanged.
+Bridge settings come only from the authoritative `<PI_CODING_AGENT_DIR>/claude-bridge.json`; logs still resolve under `PI_CODING_AGENT_DIR`. Normal Pi CLI usage (flag unset) is unchanged.
+
+### Fable 5 and Opus 5 caveat
+
+The bridge registers `claude-bridge/claude-fable-5`, `claude-bridge/claude-opus-5`, `claude-bridge/claude-sonnet-5`, and `claude-bridge/claude-opus-4-8` even when Pi's Anthropic model registry has not shipped those entries yet. Fable 5 and Opus 5 both run classifiers that can decline a turn, so for each of them the bridge asks Claude Code to use Opus 4.8 as the availability fallback and preserves Claude Code's content-safety fallback events so Pi labels rerouted turns as Opus 4.8. Content-safety fallback still depends on Claude Code's own Fable 5 support; use Claude Code 2.1.170 or newer, and set `ANTHROPIC_DEFAULT_FABLE_MODEL` / `ANTHROPIC_DEFAULT_OPUS_MODEL` yourself when routing provider-specific model IDs through Bedrock, Vertex, or Foundry.
 
-### Fable 5 caveat
+## Connector inventory
+
+`/claude-bridge:connectors` lists the Claude account's installed claude.ai connectors by asking the account, not the model.
+
+The older way to answer "does this account have Slack?" was a capability probe: a model turn that enumerated connectors via `ToolSearch`. A search returns what the search surfaced — a lower bound — and nothing in the result said so, so an account with Slack attached could produce an inventory without Slack and no failure signal (vstack#838). This command calls the account's connector list endpoint instead, so the answer is complete by construction.
+
+`listAccountConnectors()` is the programmatic form for host apps. Import it from the package's `./connector-inventory` entry point:
+
+```ts
+import { listAccountConnectors, resolveClaudeOAuth } from "@vanillagreen/pi-claude-bridge/connector-inventory";
+```
+
+Consuming apps that regenerate their vendored `package.json` with a closed exports map (`{".": "./bundle/index.js"}`) cannot reach that subpath — Node rejects every unlisted subpath *and* deep path under such a map. The same functions are therefore re-exported from the package root, which is the path those manifests allow:
+
+```ts
+import { listAccountConnectors } from "@vanillagreen/pi-claude-bridge";
+```
 
-The bridge registers `claude-bridge/claude-fable-5`, `claude-bridge/claude-sonnet-5`, and `claude-bridge/claude-opus-4-8` even when Pi's Anthropic model registry has not shipped those entries yet. For Fable 5, the bridge asks Claude Code to use Opus 4.8 as the availability fallback and preserves Claude Code's content-safety fallback events so Pi labels rerouted turns as Opus 4.8. Content-safety fallback still depends on Claude Code's own Fable 5 support; use Claude Code 2.1.170 or newer, and set `ANTHROPIC_DEFAULT_FABLE_MODEL` / `ANTHROPIC_DEFAULT_OPUS_MODEL` yourself when routing provider-specific model IDs through Bedrock, Vertex, or Foundry.
+The dedicated entry point is a separate build output. It cannot come from `bundle/index.js`, which exports only pi's extension registration and is tree-shaken against what `index.ts` itself calls — `connectorServerNamespace` was dropped from it entirely for that reason. `tests/unit-connector-inventory-artifact.mjs` loads the built artifact rather than `src/` so a source change without a rebuild fails. It returns a discriminated result: on success `{ ok: true, complete: true, connectors }`, and on any transport or protocol failure `{ ok: false, reason }`. An account with no connectors is a successful empty list; a failure is never reported as an empty inventory. Credentials resolve from `CLAUDE_CONFIG_DIR` before `$HOME`, so a host running one sidecar per Claude account reads the right account.
 
 ## Extra usage and rate limits
 

package/bundle/connector-inventory.js

@@ -0,0 +1,137 @@
+// src/connector-inventory.ts
+var CONNECTOR_NS_PREFIX = "mcp__claude_ai_";
+var DEFAULT_API_BASE = "https://api.anthropic.com";
+var OAUTH_BETA_HEADER = "oauth-2025-04-20";
+function connectorServerNamespace(connectorName) {
+  return `${CONNECTOR_NS_PREFIX}${connectorName.trim().replace(/\s+/g, "_")}__`;
+}
+function credentialCandidatePaths(env = process.env) {
+  const roots = [];
+  const configDir = env.CLAUDE_CONFIG_DIR?.trim();
+  if (configDir) roots.push(configDir);
+  const home = env.HOME?.trim();
+  if (home) roots.push(`${home}/.claude`, home);
+  const seen = /* @__PURE__ */ new Set();
+  const paths = [];
+  for (const root of roots) {
+    for (const name of [".credentials.json", ".claude.json"]) {
+      const p = `${root}/${name}`;
+      if (!seen.has(p)) {
+        seen.add(p);
+        paths.push(p);
+      }
+    }
+  }
+  return paths;
+}
+function resolveClaudeOAuth(readFile, env = process.env) {
+  let accessToken;
+  let organizationUuid;
+  for (const path of credentialCandidatePaths(env)) {
+    const raw = readFile(path);
+    if (!raw) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      continue;
+    }
+    accessToken ??= nonEmptyString(parsed?.claudeAiOauth?.accessToken);
+    organizationUuid ??= nonEmptyString(parsed?.oauthAccount?.organizationUuid);
+    if (accessToken && organizationUuid) break;
+  }
+  if (!accessToken || !organizationUuid) return void 0;
+  return { accessToken, organizationUuid };
+}
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function connectorsListUrl(organizationUuid, apiBase = DEFAULT_API_BASE) {
+  return `${trimTrailingSlashes(apiBase)}/api/oauth/organizations/${encodeURIComponent(organizationUuid)}/mcp/connectors/list`;
+}
+function trimTrailingSlashes(value) {
+  let end = value.length;
+  while (end > 0 && value.charCodeAt(end - 1) === 47) end--;
+  return value.slice(0, end);
+}
+async function listAccountConnectors(deps) {
+  const { credentials, apiBase, signal } = deps;
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  const url = connectorsListUrl(credentials.organizationUuid, apiBase);
+  const fail = (reason) => ({ ok: false, complete: false, reason: redactSecret(reason, credentials.accessToken) });
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      method: "POST",
+      headers: {
+        "Authorization": `Bearer ${credentials.accessToken}`,
+        "anthropic-beta": OAUTH_BETA_HEADER,
+        "Content-Type": "application/json"
+      },
+      body: "{}",
+      signal
+    });
+  } catch (error) {
+    return fail(`connector list request failed: ${errorText(error)}`);
+  }
+  let bodyText;
+  try {
+    bodyText = await response.text();
+  } catch (error) {
+    return fail(`connector list response unreadable: ${errorText(error)}`);
+  }
+  if (!response.ok) {
+    return fail(`connector list returned HTTP ${response.status}${apiErrorSuffix(bodyText)}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(bodyText);
+  } catch {
+    return fail("connector list returned a non-JSON body");
+  }
+  if (!Array.isArray(parsed?.results)) {
+    return fail("connector list response had no results array");
+  }
+  const connectors = [];
+  for (const raw of parsed.results) {
+    const entry = raw;
+    const name = nonEmptyString(entry?.name);
+    if (!name) {
+      return fail("connector list contained an entry with no name");
+    }
+    connectors.push({
+      name,
+      installedServerId: nonEmptyString(entry?.installedServerId),
+      directoryUuid: nonEmptyString(entry?.directoryUuid),
+      description: nonEmptyString(entry?.description),
+      isAuthless: typeof entry?.isAuthless === "boolean" ? entry.isAuthless : void 0
+    });
+  }
+  return { ok: true, complete: true, connectors };
+}
+function apiErrorSuffix(bodyText) {
+  try {
+    const message = JSON.parse(bodyText)?.error?.message;
+    return typeof message === "string" && message.trim() ? ` (${message.trim()})` : "";
+  } catch {
+    return "";
+  }
+}
+function redactSecret(text, secret) {
+  if (!secret || secret.length < 8) return text;
+  let out = text;
+  for (const form of /* @__PURE__ */ new Set([secret, encodeURIComponent(secret)])) {
+    out = out.split(form).join("[redacted]");
+  }
+  return out;
+}
+function errorText(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+export {
+  connectorServerNamespace,
+  connectorsListUrl,
+  credentialCandidatePaths,
+  listAccountConnectors,
+  resolveClaudeOAuth
+};