switchroom 0.15.37 → 0.15.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchroom",
-  "version": "0.15.37",
+  "version": "0.15.39",
   "description": "Run Claude Code 24/7 on your Claude Pro/Max subscription over Telegram. Open-source alternative to OpenClaw and NanoClaw — no API keys.",
   "type": "module",
   "bin": {

package/profiles/_base/cron-session.sh.hbs

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Tier-1 cheap cron SESSION launcher — docs/rfcs/cheap-cron-sessions.md §2.2.
+# Tier-1 cheap cron SESSION launcher — reference/rfcs/cheap-cron-sessions.md §2.2.
 #
 # A SECOND interactive `claude` (no -p — compliance pillar 3) in the agent
 # container, dedicated to cheap cron fires. It registers to the SAME gateway

package/profiles/_base/start.sh.hbs

@@ -164,7 +164,7 @@ if [ "$SWITCHROOM_RUNTIME" = "docker" ] && [ -z "$SWITCHROOM_DOCKER_TMUX_INNER"
   fi
 
 {{#if cronSessionEnabled}}
-  # 4) cheap cron SESSION (Tier 1, docs/rfcs/cheap-cron-sessions.md §2.2).
+  # 4) cheap cron SESSION (Tier 1, reference/rfcs/cheap-cron-sessions.md §2.2).
   #    A SECOND interactive claude (no -p) dedicated to context:fresh cron
   #    fires, registering to the gateway as the cron-suffixed bridge. This
   #    block is rendered ONLY for an agent that has a Tier-1 cron entry; for

package/profiles/default/CLAUDE.md.hbs

@@ -28,6 +28,8 @@ You are operating in the **{{topicName}}** {{#if topicEmoji}}{{topicEmoji}} {{/i
 - Prefer `trash` over `rm` when available (recoverable beats gone forever).
 - Safe to do freely: read files, explore, organize, search the web, check calendars, work within this workspace.
 - Ask first: sending emails, tweets, public posts, anything that leaves the machine, anything you're uncertain about.
+- **Batch foreseeable approvals; don't drip surprises.** When you can already see that several actions will each need the user's approval, tell them up front which approvals are coming and why. Request independent ones together so they can decide once; for dependent ones (one's input comes from another), say what you're doing first and what approval comes next — a permission card should never arrive out of the blue.
+- **A timed-out approval isn't a denial.** If a request came back denied only because the user was away (a timeout, not an explicit "no"), don't silently abandon it. When they're back, remind them it's still pending and re-offer it if they still want it.
 
 ## Execution Bias
 

package/skills/switchroom-manage/SKILL.md

@@ -38,7 +38,7 @@ When the user says "add a new agent", "add an agent to my switchroom setup", or
 
 ### Anthropic accounts (one OAuth, many agents)
 
-The auth model treats the Anthropic account as the unit of authentication: one OAuth flow per account, then every agent in the fleet inherits the fleet-wide active account. The `switchroom-auth-broker` daemon owns the refresh loop and is the sole writer of every `credentials.json`. See `docs/auth.md` for the operator guide and `reference/share-auth-across-the-fleet.md` for the design.
+The auth model treats the Anthropic account as the unit of authentication: one OAuth flow per account, then every agent in the fleet inherits the fleet-wide active account. The `switchroom-auth-broker` daemon owns the refresh loop and is the sole writer of every `credentials.json`. See `docs/auth.md` for the operator guide and `reference/jobs/share-auth-across-the-fleet.md` for the design.
 
 **Bootstrap flow when the user wants to share one Pro/Max subscription across agents:**
 

package/skills/switchroom-runtime/SKILL.md

@@ -145,7 +145,7 @@ Doubled `!!` (typo / emphasis) reaches you verbatim. Empty `!` gets a "Send your
 
 ## "status?" / "still there?" — UX-failure signal
 
-**Trigger:** the user sends a short, low-content message asking whether you're alive — "status?", "still there?", "any update?", "you working?". The progress card and stream-reply pattern exist precisely so the user never has to ask. When you see one of those messages, treat it as a defect signal: something about the in-flight turn made the user feel uncertain. The product expectation (per `reference/know-what-my-agent-is-doing.md`) is that this rate trends to zero.
+**Trigger:** the user sends a short, low-content message asking whether you're alive — "status?", "still there?", "any update?", "you working?". The progress card and stream-reply pattern exist precisely so the user never has to ask. When you see one of those messages, treat it as a defect signal: something about the in-flight turn made the user feel uncertain. The product expectation (per `reference/jobs/know-what-my-agent-is-doing.md`) is that this rate trends to zero.
 
 Your response should:
 

package/telegram-plugin/answer-stream.ts

@@ -11,7 +11,7 @@ import {
  * Answer-lane incremental streaming for long Telegram replies.
  *
  * This module implements the "narrative" liveness layer described in
- * `reference/know-what-my-agent-is-doing.md`:
+ * `reference/jobs/know-what-my-agent-is-doing.md`:
  *
  *   ambient     → 👀 ack reaction
  *   structured  → progress card (existing, via stream-reply-handler.ts lane:'progress')

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'
 
@@ -544,7 +545,17 @@ const TOOL_SCHEMAS = [
   },
 ]
 
-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 ─────────────────────────────────────────
 
@@ -691,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