switchroom 0.15.36 → 0.15.38

package/telegram-plugin/bridge/bridge.ts

@@ -27,6 +27,7 @@ import {
   type PtyTailHandle,
 } from '../pty-tail.js'
 import { createIpcClient, type IpcClientHandle } from './ipc-client.js'
+import { buildEffectiveToolSchemas, LINEAR_ENV } from './tool-filter.js'
 import type { InboundMessage, PermissionEvent, StatusEvent } from '../gateway/ipc-protocol.js'
 import { matchesAllowRule } from '../permission-rule.js'
 
@@ -510,9 +511,51 @@ const TOOL_SCHEMAS = [
       required: ['title', 'body'],
     },
   },
+  {
+    name: 'linear_agent_setup',
+    description:
+      'Provision THIS agent as a Linear app actor (actor=app OAuth) from inside the container — the operator-approved in-container path that replaces the host-only `switchroom linear-agent setup` (which silently no-ops in a sandbox). Two steps. action="authorize_url": pass the OAuth app client_id + redirect_uri; returns the browser URL the operator opens to consent. action="complete": pass client_id, client_secret, redirect_uri, and the code from the redirect; exchanges it and stores the access token (linear/<agent>/token) + the durable refresh bundle (linear/<agent>/oauth) via the vault broker so the token auto-renews. Writing those NEW keys needs a write-grant — if the broker denies, the tool returns the exact vault_request_access calls to make (operator approves), then re-run "complete". After it stores the values, follow the returned guidance to config_propose_edit the linear_agent block + secrets[] ACL (also operator-approved) to make it durable. The client_secret and code are used in-process only — never stored in config or logged.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['authorize_url', 'complete'],
+          description: '"authorize_url" to get the browser consent URL; "complete" to exchange the code and store the credentials.',
+        },
+        client_id: {
+          type: 'string',
+          description: 'Linear OAuth app client id (from Linear → Settings → API → your agent app).',
+        },
+        redirect_uri: {
+          type: 'string',
+          description: 'The redirect URI registered on the Linear OAuth app (e.g. http://localhost:3000/callback). Must match exactly in both steps.',
+        },
+        client_secret: {
+          type: 'string',
+          description: 'Linear OAuth app client secret. Required for action="complete"; used in-process for the token exchange, never stored or logged.',
+        },
+        code: {
+          type: 'string',
+          description: 'The authorization code from the redirect URL (the `code=` query param). Required for action="complete"; single-use.',
+        },
+      },
+      required: ['action', 'client_id', 'redirect_uri'],
+    },
+  },
 ]
 
-mcp.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOL_SCHEMAS }))
+// Tool-surface right-sizing (P4): connection-gate linear_* + per-tool
+// alwaysLoad pins for the hot path. See tool-filter.ts for the rationale.
+// Computed once at startup — SWITCHROOM_TELEGRAM_LINEAR is fixed for the
+// process lifetime (set by the gateway in .mcp.json when Linear is wired).
+const EFFECTIVE_TOOL_SCHEMAS = buildEffectiveToolSchemas(TOOL_SCHEMAS, {
+  linearEnabled: process.env[LINEAR_ENV] === '1',
+})
+
+mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: EFFECTIVE_TOOL_SCHEMAS,
+}))
 
 // ─── MCP CallTool → IPC forward ─────────────────────────────────────────
 
@@ -659,6 +702,12 @@ function onPermission(msg: PermissionEvent): void {
     params: {
       request_id: msg.requestId,
       behavior: msg.behavior,
+      // `message` (deny only) is rendered by claude's channel as
+      // "…the user said: ${message}". We use it to tell the model a deny was
+      // a TIMEOUT, not a human denial — so it doesn't retry the identical
+      // call and re-raise a duplicate card. Omitted → claude's default
+      // "Denied" (safe degradation).
+      ...(msg.message ? { message: msg.message } : {}),
     },
   }).catch((err) => {
     process.stderr.write(`telegram bridge: failed to deliver permission to Claude: ${err}\n`)

package/telegram-plugin/bridge/ipc-client.ts

@@ -26,7 +26,10 @@ export function validateGatewayMessage(msg: unknown): msg is GatewayToClient {
         && (m.behavior === "allow" || m.behavior === "deny")
         // `rule` is optional (only sent on "🔁 Always allow"); when present
         // it must be a non-empty string. #1138 wire extension.
-        && (m.rule === undefined || (typeof m.rule === "string" && m.rule.length > 0));
+        && (m.rule === undefined || (typeof m.rule === "string" && m.rule.length > 0))
+        // `message` is optional (deny only — the timeout-vs-denial reason);
+        // when present it must be a non-empty string.
+        && (m.message === undefined || (typeof m.message === "string" && m.message.length > 0));
     case "status":
       return typeof m.status === "string";
     case "tool_call_result":

package/telegram-plugin/bridge/tool-filter.ts

@@ -0,0 +1,77 @@
+/**
+ * Tool-surface right-sizing for the switchroom-telegram MCP server (P4).
+ *
+ * switchroom-telegram is the primary interface, so its tool schemas are
+ * always-loaded on EVERY agent, every turn (~8k tokens). Two reductions,
+ * both native to Claude Code tool-search (honored in 2.1.177; the MCP SDK
+ * preserves `_meta` on tools/list — @modelcontextprotocol/sdk ToolSchema
+ * has `_meta: z.record(...).optional()`):
+ *
+ *   A. Connection gating — linear_* tools are advertised only when the
+ *      agent has the Linear connection configured (the gateway sets
+ *      SWITCHROOM_TELEGRAM_LINEAR=1 from channels.telegram.linear_agent.
+ *      enabled). A non-Linear agent never carries their schema at all.
+ *
+ *   B. Per-tool deferral — the server is no longer pinned wholesale
+ *      (scaffold sets alwaysLoad:false). We pin ONLY the load-bearing hot
+ *      tools via `_meta["anthropic/alwaysLoad"]` so they never defer (the
+ *      reply path must never pay a ToolSearch round-trip before it can
+ *      answer); the ~14 cold tools defer and load on first use.
+ *
+ * Pure + side-effect free so it's unit-testable in isolation (bridge.ts
+ * has import-time side effects). Both reductions are non-destructive — every
+ * tool the agent is entitled to still works; cold ones just load on demand.
+ */
+
+/** Minimal shape we need from a tool schema. */
+export interface NamedTool {
+  name: string
+  [k: string]: unknown
+}
+
+/**
+ * Hot tools pinned loaded — must never defer. The reply path
+ * (reply/stream_reply) plus the frequently-used early-turn ops. Everything
+ * NOT in this set defers under tool-search.
+ */
+export const ALWAYS_LOAD_TOOLS: ReadonlySet<string> = new Set([
+  'reply',
+  'stream_reply',
+  'get_recent_messages',
+  'react',
+  'edit_message',
+  'send_typing',
+  'download_attachment',
+])
+
+/** Linear tools — advertised only when the Linear connection is configured. */
+export const LINEAR_TOOLS: ReadonlySet<string> = new Set([
+  'linear_agent_activity',
+  'linear_create_issue',
+  'linear_agent_setup',
+])
+
+/** The env var the gateway sets (per .mcp.json) when Linear is configured. */
+export const LINEAR_ENV = 'SWITCHROOM_TELEGRAM_LINEAR'
+
+export interface ToolFilterOpts {
+  /** True when the Linear connection is configured for this agent. */
+  linearEnabled: boolean
+}
+
+/**
+ * Apply connection gating (A) + per-tool deferral pins (B) to a tool list.
+ * Returns a NEW array; inputs are not mutated. Order is preserved.
+ */
+export function buildEffectiveToolSchemas<T extends NamedTool>(
+  schemas: ReadonlyArray<T>,
+  opts: ToolFilterOpts,
+): Array<T & { _meta?: { 'anthropic/alwaysLoad': true } }> {
+  return schemas
+    .filter((t) => opts.linearEnabled || !LINEAR_TOOLS.has(t.name))
+    .map((t) =>
+      ALWAYS_LOAD_TOOLS.has(t.name)
+        ? { ...t, _meta: { 'anthropic/alwaysLoad': true as const } }
+        : t,
+    )
+}

package/telegram-plugin/chat-lock.ts

@@ -41,7 +41,7 @@
  * autoRetry transformer; if two topics in the same chat both burst
  * past the limit, grammY backs off per the Retry-After header — same
  * worst-case behavior as the old per-chat lock, just hit differently.
- * See docs/rfcs/supergroup-mode.md and the
+ * See reference/rfcs/supergroup-mode.md and the
  * `tests/outbound-ordering.test.ts` 429-isolation row.
  */
 

package/telegram-plugin/credits-watch.ts

@@ -13,7 +13,7 @@
  * silently failed (stdout to /dev/null), and the user only noticed
  * hours later when they wondered why their morning brief never came.
  * Direct violation of the #1 product principle (silent failure is
- * the worst case — see reference/know-what-my-agent-is-doing.md).
+ * the worst case — see reference/jobs/know-what-my-agent-is-doing.md).
  *
  * This module is a pure decision layer. It reads the file, compares
  * against the last-notified state on disk, and tells the caller

package/telegram-plugin/dist/bridge/bridge.js

@@ -24211,7 +24211,7 @@ function validateGatewayMessage(msg) {
     case "inbound":
       return typeof m.chatId === "string" && typeof m.text === "string";
     case "permission":
-      return typeof m.requestId === "string" && (m.behavior === "allow" || m.behavior === "deny") && (m.rule === undefined || typeof m.rule === "string" && m.rule.length > 0);
+      return typeof m.requestId === "string" && (m.behavior === "allow" || m.behavior === "deny") && (m.rule === undefined || typeof m.rule === "string" && m.rule.length > 0) && (m.message === undefined || typeof m.message === "string" && m.message.length > 0);
     case "status":
       return typeof m.status === "string";
     case "tool_call_result":
@@ -24448,6 +24448,26 @@ function createIpcClient(options) {
   });
 }
 
+// bridge/tool-filter.ts
+var ALWAYS_LOAD_TOOLS = new Set([
+  "reply",
+  "stream_reply",
+  "get_recent_messages",
+  "react",
+  "edit_message",
+  "send_typing",
+  "download_attachment"
+]);
+var LINEAR_TOOLS = new Set([
+  "linear_agent_activity",
+  "linear_create_issue",
+  "linear_agent_setup"
+]);
+var LINEAR_ENV = "SWITCHROOM_TELEGRAM_LINEAR";
+function buildEffectiveToolSchemas(schemas3, opts) {
+  return schemas3.filter((t) => opts.linearEnabled || !LINEAR_TOOLS.has(t.name)).map((t) => ALWAYS_LOAD_TOOLS.has(t.name) ? { ...t, _meta: { "anthropic/alwaysLoad": true } } : t);
+}
+
 // permission-rule.ts
 import { basename as basename2 } from "node:path";
 var FILE_TOOLS = new Set([
@@ -24987,9 +25007,45 @@ var TOOL_SCHEMAS = [
       },
       required: ["title", "body"]
     }
+  },
+  {
+    name: "linear_agent_setup",
+    description: 'Provision THIS agent as a Linear app actor (actor=app OAuth) from inside the container \u2014 the operator-approved in-container path that replaces the host-only `switchroom linear-agent setup` (which silently no-ops in a sandbox). Two steps. action="authorize_url": pass the OAuth app client_id + redirect_uri; returns the browser URL the operator opens to consent. action="complete": pass client_id, client_secret, redirect_uri, and the code from the redirect; exchanges it and stores the access token (linear/<agent>/token) + the durable refresh bundle (linear/<agent>/oauth) via the vault broker so the token auto-renews. Writing those NEW keys needs a write-grant \u2014 if the broker denies, the tool returns the exact vault_request_access calls to make (operator approves), then re-run "complete". After it stores the values, follow the returned guidance to config_propose_edit the linear_agent block + secrets[] ACL (also operator-approved) to make it durable. The client_secret and code are used in-process only \u2014 never stored in config or logged.',
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: {
+          type: "string",
+          enum: ["authorize_url", "complete"],
+          description: '"authorize_url" to get the browser consent URL; "complete" to exchange the code and store the credentials.'
+        },
+        client_id: {
+          type: "string",
+          description: "Linear OAuth app client id (from Linear \u2192 Settings \u2192 API \u2192 your agent app)."
+        },
+        redirect_uri: {
+          type: "string",
+          description: "The redirect URI registered on the Linear OAuth app (e.g. http://localhost:3000/callback). Must match exactly in both steps."
+        },
+        client_secret: {
+          type: "string",
+          description: 'Linear OAuth app client secret. Required for action="complete"; used in-process for the token exchange, never stored or logged.'
+        },
+        code: {
+          type: "string",
+          description: 'The authorization code from the redirect URL (the `code=` query param). Required for action="complete"; single-use.'
+        }
+      },
+      required: ["action", "client_id", "redirect_uri"]
+    }
   }
 ];
-mcp.setRequestHandler(ListToolsRequestSchema2, async () => ({ tools: TOOL_SCHEMAS }));
+var EFFECTIVE_TOOL_SCHEMAS = buildEffectiveToolSchemas(TOOL_SCHEMAS, {
+  linearEnabled: process.env[LINEAR_ENV] === "1"
+});
+mcp.setRequestHandler(ListToolsRequestSchema2, async () => ({
+  tools: EFFECTIVE_TOOL_SCHEMAS
+}));
 mcp.setRequestHandler(CallToolRequestSchema2, async (req) => {
   const tool = req.params.name;
   const args = req.params.arguments ?? {};
@@ -25077,7 +25133,8 @@ function onPermission(msg) {
     method: "notifications/claude/channel/permission",
     params: {
       request_id: msg.requestId,
-      behavior: msg.behavior
+      behavior: msg.behavior,
+      ...msg.message ? { message: msg.message } : {}
     }
   }).catch((err) => {
     process.stderr.write(`telegram bridge: failed to deliver permission to Claude: ${err}