switchroom 0.15.13 → 0.15.14

package/telegram-plugin/gateway/gateway.ts

@@ -363,6 +363,7 @@ import type {
   PtyPartialForward,
   InboundMessage,
   InjectInboundMessage,
+  SendOutboundMessage,
   QuotaWallDetectedMessage,
   PermissionEvent,
 } from './ipc-protocol.js'
@@ -6546,6 +6547,10 @@ const ipcServer: IpcServer = createIpcServer({
       process.stderr.write(
         `telegram gateway: cron fire fell back to main session (no cron bridge) agent=${msg.agentName} prompt_key=${promptKey}\n`,
       )
+      // #2307 Tier-1 observability: a climbing counter means the cron session is
+      // down (registered then died, or never came up) — the Tier-1 saving is
+      // lost for this fire. Surfaced via the unified runtime-metrics fan-out.
+      emitRuntimeMetric({ kind: 'cron_fell_back_to_main', agent: msg.agentName, prompt_key: promptKey })
     }
     // Status-silent (§2.4): a cron fire delivered to the CRON session must NOT
     // set the MAIN agent's currentTurn. But a fire that LANDED on the main
@@ -6564,6 +6569,47 @@ const ipcServer: IpcServer = createIpcServer({
     }
   },
 
+  // #2307 Tier-0 action tier — a MODEL-FREE outbound post. The agent-scheduler
+  // fires this for a `kind: action` `telegram-message`; the gateway posts the
+  // (already-substituted) text to the agent's OWN chat with NO model: no
+  // inject_inbound, no session wake, no currentTurn mutation. Two fences:
+  //   1. agentName must match this gateway's own SWITCHROOM_AGENT_NAME.
+  //   2. chatId must be an allowlisted chat for this agent (assertAllowedChat).
+  // An action carries no chat target of its own — the scheduler supplies the
+  // agent's own chat — so 2 is belt-and-braces against a malformed/foreign id.
+  onSendOutbound(_client: IpcClient, msg: SendOutboundMessage) {
+    const self = process.env.SWITCHROOM_AGENT_NAME
+    if (self && msg.agentName !== self) {
+      process.stderr.write(
+        `telegram gateway: send_outbound rejected — agent mismatch (${msg.agentName} != ${self})\n`,
+      )
+      return
+    }
+    try {
+      assertAllowedChat(msg.chatId)
+    } catch (err) {
+      process.stderr.write(
+        `telegram gateway: send_outbound rejected — ${(err as Error).message}\n`,
+      )
+      return
+    }
+    const threadId = msg.threadId
+    const parseMode = msg.parseMode === 'text' ? undefined : 'HTML'
+    // allow-raw-bot-api: wrapped in swallowingApiCall (retry policy); thread-aware send.
+    // General topic (thread 1) sends omit message_thread_id per the outbound convention.
+    void swallowingApiCall(
+      () =>
+        bot.api.sendMessage(msg.chatId, msg.text, {
+          ...(parseMode ? { parse_mode: parseMode } : {}),
+          ...(threadId != null && threadId !== 1 ? { message_thread_id: threadId } : {}),
+        }),
+      { chat_id: msg.chatId, verb: 'cron-action-send', ...(threadId != null ? { threadId } : {}) },
+    )
+    process.stderr.write(
+      `telegram gateway: send_outbound agent=${msg.agentName} chat=${msg.chatId} thread=${threadId ?? '-'} len=${msg.text.length}\n`,
+    )
+  },
+
   // The wedge-watchdog detected claude's /rate-limit-options weekly-quota menu
   // (a TUI wall that never produced a 429, so the inference-path auto-fallback
   // never fired). Trigger the SAME fleet auto-fallback the 429 path uses,

package/telegram-plugin/gateway/ipc-protocol.ts

@@ -413,6 +413,35 @@ export interface QuotaWallDetectedMessage {
   resetAt?: number;
 }
 
+/**
+ * #2307 (Tier-0 action tier) — a MODEL-FREE outbound post. Sent by the
+ * in-agent scheduler when a `kind: action` cron's `telegram-message` fires:
+ * the gateway posts `text` to the agent's OWN chat with no model involvement
+ * (NO `inject_inbound`, NO session wake, NO `currentTurn` mutation). This is
+ * the deliberate counterpart to `inject_inbound` — the one ClientToGateway
+ * verb that produces an outbound WITHOUT a turn.
+ *
+ * Trust model: same as `inject_inbound` — the socket is per-agent inside the
+ * container, only that-UID processes can connect. `agentName` is validated
+ * server-side, and the gateway FENCES `chatId` to the agent's own configured
+ * chat (DM allowlist / forum_chat_id) and rejects a foreign chat — an action
+ * can never post elsewhere (the action spec carries no chat target; the
+ * scheduler supplies the agent's own).
+ */
+export interface SendOutboundMessage {
+  type: "send_outbound";
+  /** Target agent — gateway verifies it matches its own SWITCHROOM_AGENT_NAME. */
+  agentName: string;
+  /** Agent's own chat id (fenced server-side against the agent's config). */
+  chatId: string;
+  /** Forum topic thread id (General/unset omitted; 1 is stripped on send). */
+  threadId?: number;
+  /** Message body — already substitution-resolved by the action engine. */
+  text: string;
+  /** Telegram parse mode. Defaults to HTML. */
+  parseMode?: "html" | "text";
+}
+
 export type ClientToGateway =
   | RegisterMessage
   | ToolCallMessage
@@ -428,4 +457,5 @@ export type ClientToGateway =
   | RequestMs365ApprovalMessage
   | RequestConfigApprovalMessage
   | RequestConfigFinalizeMessage
-  | QuotaWallDetectedMessage;
+  | QuotaWallDetectedMessage
+  | SendOutboundMessage;

package/telegram-plugin/gateway/ipc-server.ts

@@ -4,6 +4,7 @@ import type {
   GatewayToClient,
   HeartbeatMessage,
   InjectInboundMessage,
+  SendOutboundMessage,
   QuotaWallDetectedMessage,
   OperatorEventForward,
   PermissionRequestForward,
@@ -45,6 +46,15 @@ export interface IpcServerOptions {
    * inline scheduler simply ignore inject_inbound messages.
    */
   onInjectInbound?: (client: IpcClient, msg: InjectInboundMessage) => void;
+  /**
+   * #2307 Tier-0 action tier — a model-free outbound post. Invoked when the
+   * agent-scheduler sibling fires a `kind: action` `telegram-message`. The
+   * handler is expected to post `msg.text` to `msg.chatId` (fenced to the
+   * agent's own chat) via the locked bot — with NO model, NO inject_inbound,
+   * NO session wake. Optional: gateways that don't run the inline scheduler
+   * ignore it.
+   */
+  onSendOutbound?: (client: IpcClient, msg: SendOutboundMessage) => void;
   /**
    * The autoaccept-poll wedge-watchdog detected claude's `/rate-limit-options`
    * weekly-quota menu (no 429 ever reached the gateway). Handler is expected to
@@ -246,6 +256,21 @@ export function validateClientMessage(msg: unknown): msg is ClientToGateway {
         && typeof inb.meta === "object"
         && inb.meta !== null;
     }
+    case "send_outbound": {
+      // #2307 Tier-0 action tier — a model-free outbound post. Validate the
+      // wire shape; the gateway handler fences chatId to the agent's own chat.
+      if (typeof m.agentName !== "string"
+        || !AGENT_NAME_RE.test(m.agentName as string)) return false;
+      if (typeof m.chatId !== "string" || (m.chatId as string).length === 0) return false;
+      // text non-empty and bounded — Telegram caps a message at 4096 chars;
+      // reject over-long here (defense in depth against a malformed payload).
+      if (typeof m.text !== "string" || (m.text as string).length === 0
+        || (m.text as string).length > 4096) return false;
+      if (m.threadId !== undefined
+        && (typeof m.threadId !== "number" || !Number.isInteger(m.threadId as number))) return false;
+      if (m.parseMode !== undefined && m.parseMode !== "html" && m.parseMode !== "text") return false;
+      return true;
+    }
     case "quota_wall_detected": {
       // wedge-watchdog detected the /rate-limit-options weekly-quota menu.
       if (typeof m.agentName !== "string"
@@ -335,6 +360,7 @@ export function createIpcServer(options: IpcServerOptions): IpcServer {
     onOperatorEvent,
     onPtyPartial,
     onInjectInbound,
+    onSendOutbound,
     onQuotaWallDetected,
     onRequestDriveApproval,
     onRequestMs365Approval,
@@ -444,6 +470,9 @@ export function createIpcServer(options: IpcServerOptions): IpcServer {
       case "inject_inbound":
         if (onInjectInbound) onInjectInbound(client, msg as InjectInboundMessage);
         break;
+      case "send_outbound":
+        if (onSendOutbound) onSendOutbound(client, msg as SendOutboundMessage);
+        break;
       case "quota_wall_detected":
         if (onQuotaWallDetected) onQuotaWallDetected(client, msg as QuotaWallDetectedMessage);
         break;

package/telegram-plugin/runtime-metrics.ts

@@ -137,6 +137,20 @@ export type RuntimeMetricEvent =
       // executeReply scrub site. The two new sites close that gap.
       site: 'reply' | 'edit_message' | 'progress_update' | 'answer_stream' | 'stream_reply' | 'turn_flush'
     }
+  /**
+   * #2307 Tier-1: a cron fire routed to the `<agent>-cron` cheap session
+   * (meta.session=cron) fell back to the MAIN session because the cron bridge
+   * wasn't registered (wedged boot, crashed session, or hot-added cron with no
+   * live session yet). Each occurrence means the Tier-1 saving was NOT realised
+   * for that fire — a climbing counter is the runtime signal that a cron
+   * session is down (the doctor check catches a permanently-wedged one at boot;
+   * this catches a session that registered then died).
+   */
+  | {
+      kind: 'cron_fell_back_to_main'
+      agent: string
+      prompt_key: string
+    }
 
 /**
  * The JSONL sink lives under the runtime state dir so it's per-agent

package/telegram-plugin/tests/bridge-liveness-override.test.ts

@@ -0,0 +1,21 @@
+/**
+ * #2307 Tier-1 — the cron-session bridge writes its liveness file to a DISTINCT
+ * path so a live `<agent>-cron` bridge can't mask a dead MAIN bridge in the
+ * dashboard/doctor probe (RISK #2). The bridge is an IIFE (can't instantiate
+ * in-process), so this pins the wiring by source-read: the liveness file path
+ * honours `SWITCHROOM_BRIDGE_ALIVE_PATH`, falling back to the canonical
+ * STATE_DIR/.bridge-alive (unchanged for the main bridge).
+ */
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+const bridgeSrc = readFileSync(resolve(__dirname, "..", "bridge", "bridge.ts"), "utf-8");
+
+describe("bridge liveness path override (#2307 Tier-1)", () => {
+  it("honours SWITCHROOM_BRIDGE_ALIVE_PATH, falling back to STATE_DIR/.bridge-alive", () => {
+    expect(bridgeSrc).toMatch(
+      /livenessFilePath:\s*process\.env\.SWITCHROOM_BRIDGE_ALIVE_PATH\s*\?\?\s*join\(STATE_DIR,\s*["']\.bridge-alive["']\)/,
+    );
+  });
+});

package/telegram-plugin/tests/ipc-server-validate-send-outbound.test.ts

@@ -0,0 +1,54 @@
+/**
+ * Validation contract for the `send_outbound` IPC verb (#2307 Tier-0 action
+ * tier) — the MODEL-FREE outbound the agent-scheduler sends for a `kind: action`
+ * telegram-message. A rogue process on the same UDS must not inject a malformed
+ * payload: agentName required + name-shaped, chatId + text required non-empty,
+ * threadId (optional) an integer, parseMode (optional) html|text.
+ */
+import { describe, it, expect } from "vitest";
+import { validateClientMessage } from "../gateway/ipc-server.js";
+
+const base = { type: "send_outbound", agentName: "clerk", chatId: "12345", text: "Daily heartbeat" };
+
+describe("validateClientMessage — send_outbound", () => {
+  it("accepts a well-formed minimal message", () => {
+    expect(validateClientMessage(base)).toBe(true);
+  });
+
+  it("accepts threadId + parseMode", () => {
+    expect(validateClientMessage({ ...base, threadId: 7, parseMode: "html" })).toBe(true);
+    expect(validateClientMessage({ ...base, threadId: 1, parseMode: "text" })).toBe(true);
+  });
+
+  it("rejects a missing / non-string / malformed agentName", () => {
+    expect(validateClientMessage({ ...base, agentName: undefined })).toBe(false);
+    expect(validateClientMessage({ ...base, agentName: 123 })).toBe(false);
+    expect(validateClientMessage({ ...base, agentName: "" })).toBe(false);
+    expect(validateClientMessage({ ...base, agentName: "../etc" })).toBe(false);
+    expect(validateClientMessage({ ...base, agentName: "Clerk UPPER" })).toBe(false);
+  });
+
+  it("rejects a missing / empty chatId", () => {
+    expect(validateClientMessage({ ...base, chatId: undefined })).toBe(false);
+    expect(validateClientMessage({ ...base, chatId: "" })).toBe(false);
+    expect(validateClientMessage({ ...base, chatId: 123 })).toBe(false);
+  });
+
+  it("rejects a missing / empty / over-long text", () => {
+    expect(validateClientMessage({ ...base, text: undefined })).toBe(false);
+    expect(validateClientMessage({ ...base, text: "" })).toBe(false);
+    expect(validateClientMessage({ ...base, text: 5 })).toBe(false);
+    expect(validateClientMessage({ ...base, text: "x".repeat(4096) })).toBe(true); // at the cap
+    expect(validateClientMessage({ ...base, text: "x".repeat(4097) })).toBe(false); // over Telegram's limit
+  });
+
+  it("rejects a non-integer threadId", () => {
+    expect(validateClientMessage({ ...base, threadId: 1.5 })).toBe(false);
+    expect(validateClientMessage({ ...base, threadId: "1" })).toBe(false);
+  });
+
+  it("rejects an unknown parseMode", () => {
+    expect(validateClientMessage({ ...base, parseMode: "markdown" })).toBe(false);
+    expect(validateClientMessage({ ...base, parseMode: 1 })).toBe(false);
+  });
+});

package/telegram-plugin/tests/runtime-metrics.test.ts

@@ -82,6 +82,15 @@ describe('runtime-metrics — JSONL sink', () => {
     expect(parsed.ended_via).toBe('reply')
   })
 
+  it('cron_fell_back_to_main carries agent + prompt_key (#2307 Tier-1)', () => {
+    emitRuntimeMetric({ kind: 'cron_fell_back_to_main', agent: 'clerk', prompt_key: 'abc123' })
+    const parsed = JSON.parse(readFileSync(metricsPath, 'utf-8').trim())
+    expect(parsed.kind).toBe('cron_fell_back_to_main')
+    expect(parsed.agent).toBe('clerk')
+    expect(parsed.prompt_key).toBe('abc123')
+    expect(typeof parsed.ts).toBe('number')
+  })
+
   it('appends — does not overwrite — across calls', () => {
     for (let i = 0; i < 5; i++) {
       emitRuntimeMetric({

package/telegram-plugin/tests/send-outbound-wiring.test.ts

@@ -0,0 +1,63 @@
+/**
+ * Structural wiring guard for the model-free `send_outbound` verb (#2307).
+ *
+ * The gateway handler lives in the createIpcServer({...}) IIFE block, which
+ * can't be imported in a unit test (same constraint as the inject_inbound /
+ * linear-activity wiring tests), so the load-bearing invariants are pinned by
+ * reading the source:
+ *   1. ipc-server routes `send_outbound` → onSendOutbound.
+ *   2. the gateway handler fences agent (agentName === self) AND chat
+ *      (assertAllowedChat) before sending.
+ *   3. it is MODEL-FREE: never markClaudeBusy / currentTurn / inject — a
+ *      send_outbound must not wake a turn (the whole point of Tier-0).
+ */
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+
+const gw = readFileSync(new URL("../gateway/gateway.ts", import.meta.url), "utf8");
+const ipcServer = readFileSync(new URL("../gateway/ipc-server.ts", import.meta.url), "utf8");
+
+describe("send_outbound — ipc-server routing", () => {
+  it("validates the verb and dispatches to onSendOutbound", () => {
+    expect(ipcServer).toMatch(/case "send_outbound":/);
+    expect(ipcServer).toMatch(/onSendOutbound\(client, msg as SendOutboundMessage\)/);
+    // the validator has a dedicated arm.
+    expect(ipcServer).toMatch(/case "send_outbound": \{/);
+  });
+});
+
+describe("send_outbound — gateway handler invariants", () => {
+  // Isolate the handler body for the assertions below.
+  const start = gw.indexOf("onSendOutbound(_client: IpcClient, msg: SendOutboundMessage)");
+  // Bound the slice at the START of the NEXT handler so the whole onSendOutbound
+  // body is covered regardless of how it grows (no fixed char window to outgrow),
+  // without bleeding into a sibling handler.
+  const next = gw.indexOf("onQuotaWallDetected(", start);
+  const handler = gw.slice(start, next > start ? next : start + 2600);
+
+  it("the handler exists", () => {
+    expect(start).toBeGreaterThan(0);
+  });
+
+  it("fences the agent (agentName must match this gateway's own)", () => {
+    expect(handler).toMatch(/msg\.agentName !== self/);
+  });
+
+  it("fences the chat to the agent's own allowlist (assertAllowedChat)", () => {
+    expect(handler).toMatch(/assertAllowedChat\(msg\.chatId\)/);
+  });
+
+  it("is MODEL-FREE — never wakes a turn (no markClaudeBusy / currentTurn / inject)", () => {
+    expect(handler).not.toMatch(/markClaudeBusy/);
+    expect(handler).not.toMatch(/currentTurn/);
+    expect(handler).not.toMatch(/sendToAgent/);
+    expect(handler).not.toMatch(/inject/i);
+  });
+
+  it("sends via the wrapped retry path (not a raw bot.api outside swallowingApiCall)", () => {
+    expect(handler).toMatch(/swallowingApiCall\(/);
+    expect(handler).toMatch(/bot\.api\.sendMessage\(msg\.chatId, msg\.text/);
+    // General topic (thread 1) is stripped on send, per the outbound convention.
+    expect(handler).toMatch(/threadId !== 1/);
+  });
+});