switchroom 0.17.6 → 0.18.3

package/telegram-plugin/dist/server.js

@@ -23876,6 +23876,7 @@ function createIpcClient(options) {
     onInbound,
     onPermission,
     onStatus,
+    onConnect,
     log = () => {},
     reconnectDelayMs = 2000,
     maxReconnectDelayMs = 30000,
@@ -24011,6 +24012,13 @@ function createIpcClient(options) {
             sendRegister();
             startHeartbeat();
             log(`connected to ${socketPath}`);
+            if (onConnect) {
+              try {
+                onConnect();
+              } catch (err) {
+                log(`onConnect hook threw: ${err}`);
+              }
+            }
             resolve();
           },
           data(sock, data) {
@@ -24232,10 +24240,52 @@ var init_permission_rule = __esm(() => {
   ]);
 });
 
+// bridge/permission-ledger.ts
+function createOutstandingPermissionLedger() {
+  const map2 = new Map;
+  return {
+    add(params) {
+      map2.set(params.request_id, params);
+    },
+    delete(requestId) {
+      map2.delete(requestId);
+    },
+    has(requestId) {
+      return map2.has(requestId);
+    },
+    all() {
+      return [...map2.values()];
+    },
+    get size() {
+      return map2.size;
+    }
+  };
+}
+
 // bridge/bridge.ts
 var exports_bridge = {};
 import { dirname as dirname3, join as join5 } from "path";
 import { homedir as homedir4 } from "os";
+function flushOutstandingPermissionRequests() {
+  if (!permissionRearmEnabled)
+    return;
+  if (!ipc || !ipc.isConnected())
+    return;
+  const pending = outstandingPermissions.all();
+  if (pending.length === 0)
+    return;
+  process.stderr.write(`telegram bridge: re-sending ${pending.length} outstanding permission request(s) on gateway (re)connect
+`);
+  for (const p of pending) {
+    ipc.sendPermissionRequest({
+      type: "permission_request",
+      requestId: p.request_id,
+      toolName: p.tool_name,
+      description: p.description,
+      inputPreview: p.input_preview
+    });
+  }
+}
 function onInbound(msg) {
   mcp.notification({
     method: "notifications/claude/channel",
@@ -24252,6 +24302,7 @@ function onPermission(msg) {
   if (msg.rule) {
     sessionAllowRules.add(msg.rule);
   }
+  outstandingPermissions.delete(msg.requestId);
   mcp.notification({
     method: "notifications/claude/channel/permission",
     params: {
@@ -24305,6 +24356,7 @@ async function main() {
     onInbound,
     onPermission,
     onStatus,
+    onConnect: flushOutstandingPermissionRequests,
     log: (msg) => process.stderr.write(`telegram bridge: ipc: ${msg}
 `),
     livenessFilePath: process.env.SWITCHROOM_BRIDGE_ALIVE_PATH ?? join5(STATE_DIR, ".bridge-alive")
@@ -24318,7 +24370,7 @@ async function main() {
   }
   await mcp.connect(new StdioServerTransport);
 }
-var STATE_DIR, SOCKET_PATH, TOPIC_ID, AGENT_NAME, mcp, TOOL_SCHEMAS, EFFECTIVE_TOOL_SCHEMAS, sessionAllowRules, ipc = null, sessionTailEnabled, sessionTailHandle = null, ptyTailEnabled, ptyTailHandle = null;
+var STATE_DIR, SOCKET_PATH, TOPIC_ID, AGENT_NAME, mcp, TOOL_SCHEMAS, EFFECTIVE_TOOL_SCHEMAS, sessionAllowRules, outstandingPermissions, permissionRearmEnabled, ipc = null, sessionTailEnabled, sessionTailHandle = null, ptyTailEnabled, ptyTailHandle = null;
 var init_bridge = __esm(async () => {
   init_server2();
   init_stdio2();
@@ -24681,6 +24733,23 @@ var init_bridge = __esm(async () => {
         required: ["chat_id", "key"]
       }
     },
+    {
+      name: "mental_model_propose",
+      description: "Propose a Hindsight MENTAL MODEL for the operator to approve (agent-proposes \u2192 human-approves, hindsight Phase 5). Use this when \u2014 over real work \u2014 you notice a recurring, domain-specific question worth maintaining a standing, semantically-refreshed answer to from YOUR bank (e.g. a coach's `training-plan-state`, a lawyer's `open-matters`). You may PROPOSE but can NEVER self-approve: this renders a Telegram [Approve]/[Deny] card to the operator. On Approve the model is DECLARED \u2014 appended to your `memory.mental_models[]` in switchroom.yaml via the operator-approved config-edit path \u2014 and ensured in your bank (it then refreshes from your bank content). On Deny nothing is written. This is NOT for identity/'who is the user' (dedicated profile banks own that) and NOT a substitute for `retain` (store a fact) or `create_mental_model` where you already have direct Hindsight tools \u2014 it is the leashed, human-gated way to add a DURABLE declared model to your config. After firing this tool, END YOUR TURN cleanly \u2014 a fresh inbound arrives (`<channel source=\"mental_model_proposal_applied\">` / `mental_model_proposal_denied`) once the operator decides. Do NOT propose a model whose name is already declared (it is rejected), and do NOT spam (one card per proposal; the operator sees every one).",
+      inputSchema: {
+        type: "object",
+        properties: {
+          chat_id: { type: "string", description: "Chat to render the approval card in (use the chat_id of the user message that triggered the workflow)." },
+          name: { type: "string", description: "Stable model name \u2014 the idempotent-ensure identity key (lowercase kebab/snake, e.g. `training-plan-state`). Must be UNIQUE among your already-declared models or the proposal is rejected." },
+          source_query: { type: "string", description: `The reflection query the model answers, semantically refreshed from your bank content (e.g. "What is the athlete's current training plan, recent sessions, and open adjustments?"). Frame it as a DOMAIN question, never an identity question.` },
+          reason: { type: "string", description: 'REQUIRED in practice \u2014 one-line rationale rendered on the card (e.g. "I keep re-deriving the plan state every session; a standing model would save the lookup"). Omitting it renders "why: not provided" and the operator will usually Deny.' },
+          refresh_after_consolidation: { type: "boolean", description: "Refresh this model after each consolidation. Defaults OFF \u2014 refresh adds bounded background model-spend + timeout risk (RFC Phase 5). Only set true when the model genuinely needs to track fast-moving state." },
+          max_tokens: { type: "number", description: "Optional cap on the synthesized model's token size." },
+          message_thread_id: { type: "string", description: "Forum topic thread ID. Auto-applied from the last inbound message if not specified." }
+        },
+        required: ["chat_id", "name", "source_query"]
+      }
+    },
     {
       name: "linear_agent_activity",
       description: 'Emit a structured Linear AgentActivity against an agent session (#2298). Use this ONLY inside a turn that was woken by a Linear agent session (the inbound carries meta.source="linear" and meta.agent_session_id) \u2014 pass that agent_session_id back here. Linear renders activities as status chips + a timeline on the issue, so the human sees acknowledge \u2192 work \u2192 result. Emit a `thought` within ~10s of being woken so the session does not look dead, then `message`(s) as you make progress, and finally exactly one terminal `complete` (work done) or `error` (you could not proceed). body is required for thought/message/error and optional for complete. Resolves the agent\'s Linear app token from the vault; on VAULT-BROKER-DENIED it returns an error instructing you to vault_request_access for `linear/<agent>/token`.',
@@ -24804,6 +24873,8 @@ var init_bridge = __esm(async () => {
     }
   });
   sessionAllowRules = new Set;
+  outstandingPermissions = createOutstandingPermissionLedger();
+  permissionRearmEnabled = process.env.SWITCHROOM_PERMISSION_REARM !== "0";
   mcp.setNotificationHandler(exports_external.object({
     method: exports_external.literal("notifications/claude/channel/permission_request"),
     params: exports_external.object({
@@ -24825,9 +24896,22 @@ var init_bridge = __esm(async () => {
         return;
       }
     }
+    if (permissionRearmEnabled) {
+      outstandingPermissions.add({
+        request_id: params.request_id,
+        tool_name: params.tool_name,
+        description: params.description,
+        input_preview: params.input_preview
+      });
+    }
     if (!ipc || !ipc.isConnected()) {
-      process.stderr.write(`telegram bridge: permission_request received but not connected to gateway
+      if (permissionRearmEnabled) {
+        process.stderr.write(`telegram bridge: permission_request buffered (gateway offline), will re-send on reconnect ` + `request_id=${params.request_id}
+`);
+      } else {
+        process.stderr.write(`telegram bridge: permission_request received but not connected to gateway
 `);
+      }
       return;
     }
     ipc.sendPermissionRequest({

package/telegram-plugin/feed-heartbeat-climb.ts

@@ -0,0 +1,206 @@
+/**
+ * Deterministic silent-turn card climb — the framework owns "alive" and "for how
+ * long"; the model owns "what".
+ *
+ * Implements Phase 1 (the keystone) of `reference/rfcs/deterministic-turn-liveness.md`.
+ * Serves `reference/jobs/know-what-my-agent-is-doing.md` (outcome: at any moment
+ * during a turn the user can see the agent is alive and how long it has been
+ * working, without asking).
+ *
+ * ## The bug this closes
+ *
+ * On the 0-label path of `feedHeartbeatTick` (a turn that has surfaced NO tool
+ * label — a long single `Bash`, or only suppressed-by-design tools), the tick
+ * delegated to `openLivenessFeedIfDue`, whose WHEN-gate `shouldEarlyOpenLiveness`
+ * returns `false` the moment a card is already open (`activityMessageId != null`).
+ * Result: once the "Working…" card opened, the 0-label branch NEVER edited it
+ * again during a silent tool — the card froze on its opening elapsed while the
+ * agent was busy for tens of seconds. The only remaining signal was the ambient
+ * "stuck" reaction flip, which reads as *done*, not *working*.
+ *
+ * ## The fix
+ *
+ * Give the 0-label branch the SAME climbing-elapsed EDIT the labelled branch
+ * already performs: when a card is open and `mirrorLines` is empty, re-render the
+ * minimal "Working…" card with a fresh wall-clock elapsed on every heartbeat tick.
+ * The render is derived PURELY from `ageMs` (`now - turn.startedAt`), so a tool
+ * call blocked mid-flight — emitting nothing — cannot starve it. Worst-case gap
+ * between visible edits is one to two `FEED_HEARTBEAT_MIN_STALE_MS` windows
+ * (~6-12s), versus the observed ~50s freeze.
+ *
+ * This is a card EDIT, not a text send: it edits the card the chat already owns,
+ * and Telegram card edits do not push-notify — squarely the Ambient layer of
+ * `reference/rfcs/conversational-pacing.md`, crossing no invariant (no parallel
+ * surface, no mid-turn device buzz). When the model DOES narrate, its words land
+ * on the same card chronologically (`mirrorLines` becomes non-empty and the
+ * labelled-feed heartbeat takes over) — the climb fills only the gaps the model
+ * leaves and never overwrites narration.
+ *
+ * Kept as a small pure function so the guarantee can be proven at the transport
+ * boundary (Phase 4b regression test) rather than by grepping the gateway source.
+ */
+import {
+  renderActivityFeedWithNested,
+  formatStepSuffix,
+  type SessionActivityHeader,
+} from './tool-activity-summary.js'
+
+/** The minimal placeholder line the silent-turn card carries when no tool label
+ *  has surfaced. Matches `openLivenessFeedIfDue`'s open render so the climb edit
+ *  is a clean continuation of the placeholder the OPEN path produced. */
+export const SILENT_TURN_PLACEHOLDER = 'Working…'
+
+export interface SilentTurnClimbInput {
+  /** `turn.mirrorLines.length`. 0 ⇒ no tool label has surfaced this turn (pure
+   *  thinking / only suppressed tools) — the case this climb owns. >0 ⇒ a real
+   *  label drives the labelled-feed heartbeat, which owns the climb instead. */
+  mirrorLineCount: number
+  /** `turn.activityMessageId`. `null` ⇒ no card is open yet, so the OPEN path
+   *  (`openLivenessFeedIfDue`) owns this tick; non-null ⇒ a card is open and this
+   *  branch must keep it climbing (the exact freeze this fix closes). */
+  activityMessageId: number | null
+  /** `turn.labeledToolCount` — surfaced in the card header's tool count. */
+  labeledToolCount: number
+  /** `now - turn.startedAt`: wall-clock elapsed since turn start. The single
+   *  signal the model can never supply while blocked inside a tool. */
+  ageMs: number
+}
+
+/**
+ * The deterministic 0-label climb render. Returns the card body HTML to EDIT the
+ * already-open "Working…" card with a climbing wall-clock elapsed, or `null` when
+ * this branch must NOT edit:
+ *   - `mirrorLineCount > 0` — a tool label surfaced; the labelled-feed heartbeat
+ *     owns the climb (its edit cleanly replaces this placeholder).
+ *   - `activityMessageId == null` — no card is open yet; the OPEN path
+ *     (`openLivenessFeedIfDue`) owns this tick.
+ *
+ * The header's `elapsedMs` carries the climbing clock, so each tick's edit shows
+ * a higher "Working · Ns" than the last. Model-independent by construction: it
+ * reads only wall-clock `ageMs`.
+ */
+export function silentTurnClimbRender(input: SilentTurnClimbInput): string | null {
+  if (input.mirrorLineCount > 0) return null
+  if (input.activityMessageId == null) return null
+  const header: SessionActivityHeader = {
+    label: 'Agent',
+    elapsedMs: input.ageMs,
+    toolCount: input.labeledToolCount,
+    state: 'running',
+  }
+  // Single "step" whose start is the turn start, so `ageMs` IS the step's own
+  // elapsed. formatStepSuffix keeps the `→` line timer-free until STEP_TIMER_MIN_MS;
+  // the header total still climbs every tick — that is the visible clock.
+  return renderActivityFeedWithNested(
+    [SILENT_TURN_PLACEHOLDER],
+    [],
+    false,
+    formatStepSuffix(input.ageMs),
+    undefined,
+    header,
+  )
+}
+
+/**
+ * The per-turn view `runSilentTurnHeartbeatTick` reads — a structural subset of
+ * the gateway's `CurrentTurn`, kept transport-free so this module (and its test)
+ * never imports the gateway.
+ */
+export interface SilentTurnTickView {
+  /** `turn.mirrorLines.length` at tick time. */
+  mirrorLineCount: number
+  /** `turn.activityMessageId` at tick time (null ⇒ no card open yet). */
+  activityMessageId: number | null
+  /** `turn.labeledToolCount` — surfaced in the card header. */
+  labeledToolCount: number
+  /** `now - turn.startedAt` at tick time. */
+  ageMs: number
+  /** The labelled branch's stale floor (`FEED_HEARTBEAT_MIN_STALE_MS`). The
+   *  climb applies the SAME guard for symmetry: a turn younger than one stale
+   *  window is fresh (its card just opened ~1.2s in), so no climb edit yet.
+   *  Without this the climb relied on the tick interval == the stale window
+   *  (both 6s today) — an implicit coupling this guard makes explicit. */
+  minStaleMs: number
+}
+
+/**
+ * The gateway seams the tick drives, injected as thunks so THIS function — the
+ * shipped 0-label branch of `feedHeartbeatTick` — is directly executable in a
+ * test with spies at each seam. The gateway wires the real implementations
+ * (`openLivenessFeedIfDue`, `turn.activityPendingRender = …`, `cardDrainGate`,
+ * `ea.mayDrain`, `ea.openOrEditCard('liveness', …)`,
+ * `drainActivitySummary(turn, 'liveness')`); the wiring is pinned structurally
+ * in tests/feed-heartbeat-liveness-open.test.ts.
+ */
+export interface SilentTurnTickDeps {
+  /** The one shared OPEN path (`openLivenessFeedIfDue(turn)`). Owns the open;
+   *  the climb never opens (reply-is-last gating lives on the open path). */
+  openLivenessFeedIfDue: () => void
+  /** Stage the climb render (`turn.activityPendingRender = rendered`). */
+  setPendingRender: (rendered: string) => void
+  /** The centralized chatLock-serialized card-drain gate
+   *  (`cardDrainGate(turn, ea, run)`). */
+  cardDrainGate: (run: () => void) => void
+  /** The single-flight pure read (`ea.mayDrain(turn)`). */
+  mayDrain: () => boolean
+  /** The emission-authority façade routing (`ea.openOrEditCard('liveness', apply)`).
+   *  With a card open this only ever EDITs — Telegram edits don't push-notify. */
+  openOrEditCard: (apply: () => void) => void
+  /** The drain kick-off (`turn.activityInFlight = drainActivitySummary(turn,
+   *  'liveness')`) — the transport writer (sendMessage / editMessageText via
+   *  robustApiCall) lives behind this seam. */
+  drain: () => void
+}
+
+/**
+ * The REAL 0-label branch of `feedHeartbeatTick` (deterministic-turn-liveness.md
+ * Phase 1) — extracted here so the shipped decision logic is directly under
+ * outcome-based test (`tests/silent-turn-climb-transport.test.ts`); the gateway
+ * IIFE cannot be imported in-process, so the tick body lives in this module and
+ * the gateway calls it with its real deps.
+ *
+ * Returns true when the tick was handled by the 0-label path (the caller must
+ * stop — the labelled-feed heartbeat does not run), false when a tool label has
+ * surfaced (`mirrorLineCount > 0`) and the labelled branch owns the tick.
+ *
+ * Behaviour:
+ *   - no card open yet → delegate to the one shared OPEN path (never opens here);
+ *   - card open + turn younger than `minStaleMs` → fresh, no edit yet (the same
+ *     stale-guard the labelled branch applies to its step elapsed);
+ *   - card open + stale → stage the climbing "Working · Ns" render and EDIT it
+ *     through the same cardDrainGate → mayDrain → openOrEditCard → drain gate
+ *     sequence the labelled branch uses. Deterministic + framework-owned: reads
+ *     only wall-clock `ageMs`, so a blocked tool call cannot starve it.
+ */
+export function runSilentTurnHeartbeatTick(
+  view: SilentTurnTickView,
+  deps: SilentTurnTickDeps,
+): boolean {
+  if (view.mirrorLineCount !== 0) return false
+  if (view.activityMessageId == null) {
+    deps.openLivenessFeedIfDue()
+    return true
+  }
+  // Stale-guard (symmetry with the labelled branch's `elapsed <
+  // FEED_HEARTBEAT_MIN_STALE_MS` check): the 0-label "step" starts at turn
+  // start, so `ageMs` IS its elapsed. A younger turn's card just opened.
+  if (view.ageMs < view.minStaleMs) return true
+  const rendered = silentTurnClimbRender({
+    mirrorLineCount: view.mirrorLineCount,
+    activityMessageId: view.activityMessageId,
+    labeledToolCount: view.labeledToolCount,
+    ageMs: view.ageMs,
+  })
+  if (rendered == null) return true
+  deps.setPendingRender(rendered)
+  deps.cardDrainGate(() => {
+    if (deps.mayDrain()) {
+      // Maintains an already-open card (guarded above on activityMessageId !=
+      // null) → only ever EDITs. 'liveness' producer is correct.
+      deps.openOrEditCard(() => {
+        deps.drain()
+      })
+    }
+  })
+  return true
+}