switchroom 0.17.6 → 0.18.3

package/skills/mental-model-curator/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: mental-model-curator
+description: >
+  Review the agent's OWN Hindsight memory bank with the most capable model and
+  PROPOSE well-formed mental models ("knowledge models") to the operator via the
+  approve/deny proposal card, instead of blindly creating them. Use to curate,
+  seed, or audit the standing models the agent maintains over its specialty.
+  Triggers on phrasings like: "curate mental models", "propose knowledge models",
+  "review my memory bank", "what standing models should I have", "bootstrap
+  mental models", "suggest mental models from my bank", "audit my mental models",
+  "what recurring questions do I keep re-deriving", and typos like "propose
+  knowlege models". Do NOT use for storing a single fact/preference/decision —
+  that is retain, not a mental model. Do NOT use for identity or "who is the
+  user" — that lives in profile banks, so never propose an identity model here
+  (the operator's review of the card, not any code guard, is the only gate — so
+  it's on you to honor).
+  Even when the operator directly asks you to CREATE one specific named model
+  whose shape you know, PROPOSE it through the approve/deny card — never call
+  create_mental_model directly (it is not pre-approved; the propose card is the
+  only sanctioned write path, Fix 1.2 / #2903).
+allowed-tools: mcp__hindsight__list_banks mcp__hindsight__get_bank_stats mcp__hindsight__list_mental_models mcp__hindsight__get_mental_model mcp__hindsight__reflect mcp__hindsight__recall mcp__switchroom-telegram__mental_model_propose
+---
+
+# mental-model-curator — Propose standing knowledge models from your own bank
+
+A **mental model** in Hindsight is a pre-computed semantic summary backed by
+reflection over the memory bank — a standing answer to a recurring DOMAIN
+question the agent keeps re-deriving (e.g. a coach's "current training plan,
+recent sessions, and open adjustments"). This skill's job is to use your most
+capable model to survey your OWN bank and PROPOSE a few well-earned models to
+the operator through the approve/deny card — never to bulk-create noise.
+
+You cannot self-approve. Every proposal renders a card the operator taps. Your
+job is to make each proposal so obviously right that a glance is enough.
+
+## Why propose instead of create
+
+You do NOT have direct `create_mental_model` access — it is deliberately not
+pre-approved (Fix 1.2 / #2903). Every mental-model write routes through
+`mcp__switchroom-telegram__mental_model_propose`, because a
+standing model is a persistent, always-in-context artifact with real cost
+(recall/reflect spend, and — if `refresh_after_consolidation` is on — invisible
+post-consolidation spend). A human should decide which of those the agent runs.
+Bulk self-creation is how banks fill with overlapping, stale, or wrong-fact
+models. Propose the few that are earned; let the operator ratify.
+
+## Modes
+
+- **Propose mode (default):** run the full workflow and fire proposal cards, one
+  at a time, up to the rate limit.
+- **Dry-run / preview mode:** when the user says "preview", "dry run", "just
+  show me the candidates", "what would you propose", or you're testing against an
+  unfamiliar bank — run steps 1–4, then OUTPUT the ranked candidate list as text
+  (name + source_query + one-line reason) and STOP. Do NOT call
+  `mental_model_propose` in this mode. This is the safe way to run against any
+  bank.
+
+## Workflow
+
+### 1. Identify the bank and check it's worth analyzing
+
+Resolve the session's bank (`mcp__hindsight__list_banks`, or the bank bound to
+this agent's session). Then pull `mcp__hindsight__get_bank_stats`.
+
+If the bank is **empty or thin**, STOP and report "not enough content to
+synthesize models yet — the bank needs more accumulated memories before standing
+models are meaningful." Synthesizing over an empty or thin bank produces
+confident noise: models with no grounding that read as authoritative. A handful
+of memories is not a domain. Do not propose against a thin bank, even in dry-run.
+
+### 2. Read what already exists (dedupe)
+
+Call `mcp__hindsight__list_mental_models`, and `get_mental_model` on each to read
+its `source_query`. Build a dedupe set of the questions already covered.
+
+The propose flow hard-rejects an EXACT-name duplicate before a card posts, but
+that is not enough — a near-duplicate under a fresh name is still waste. You must
+**semantically** dedupe: if a candidate's source_query asks substantially the
+same thing as an existing model (even reworded), drop it. Only propose genuinely
+new coverage.
+
+### 3. Survey recurring themes
+
+Use `mcp__hindsight__reflect` and `mcp__hindsight__recall` to find the DOMAIN
+questions this agent keeps re-deriving — the standing state of its specialty.
+Good prompts: "What questions do I repeatedly answer from scratch?", "What are
+the recurring themes in this bank?", "What standing state would I want summarized
+before every relevant turn?" Cluster the answers into candidate standing
+questions. Each cluster must be backed by memories the bank ACTUALLY holds — if
+you can't point to the underlying content, it's not a candidate.
+
+### 4. Frame each candidate correctly
+
+- **`source_query` must be a DOMAIN question**, never an identity / "who is the
+  user" question. Identity lives in dedicated profile banks; never propose an
+  identity-based model — the operator, not the platform, is the only gate, so
+  this is on you to honor (one previously caused a wrong-fact contradiction bug).
+  If a candidate is really "facts about the user", discard it.
+- **`refresh_after_consolidation` defaults OFF.** Only set it true when the model
+  genuinely tracks fast-moving state that must be current the moment memory
+  consolidates. It adds invisible post-consolidation spend and timeout risk, so
+  the default answer is off.
+- **Keep models tight.** recall/reflect tiers cap around ~1024 tokens; a model
+  that tries to summarize everything summarizes nothing. Set a modest `max_tokens`
+  if the default would overrun. Narrow, answerable source_queries beat broad ones.
+- **Few models per bank.** Each must be earned by content the bank holds. Quality
+  over quantity — a bank with three sharp models beats one with ten vague ones.
+
+### 5. Propose within limits
+
+Rank the surviving candidates by how much re-derivation they save and how well
+the bank supports them. Propose only the **top few**.
+
+**HARD LIMIT: 5 proposal cards per hour per agent (sliding window).** Batch and
+prioritize — never fire one card per cluster. If you have more than 5 worthwhile
+candidates, propose the best 5 and mention the rest in text for a later pass.
+
+Propose **one at a time**:
+
+```
+mcp__switchroom-telegram__mental_model_propose(
+  chat_id=<the current chat_id>,
+  name=<slug>,
+  source_query=<the domain question>,
+  reason=<CRISP one line — the operator sees this on the card and denies vague ones>,
+  ...  # refresh_after_consolidation / max_tokens only when justified above
+)
+```
+
+The `reason` is load-bearing: it's the one line the operator reads before
+tapping. "Tracks the athlete's current plan + open adjustments so I stop
+rebuilding it each session" earns a tap; "useful model" gets denied.
+
+After firing a card, **END THE TURN CLEANLY.** The flow resumes on its own via a
+synthetic inbound (`mental_model_proposal_applied` / `mental_model_proposal_denied`)
+when the operator taps. Do not loop, do not poll, do not fire the next card in the
+same turn. You cannot self-approve — that's by design.
+
+### 6. Scheduled-sweep note (future extension)
+
+Unattended cron proposing is **NOT supported today.** `mental_model_propose`
+needs a live turn with an operator present to tap the card — firing cards into an
+empty topic at 3am is useless and noisy. If invoked from a scheduled sweep,
+**STAGE** the ranked candidates (retain them, or hold them) and surface them on
+the next interactive turn instead of firing cards unattended. Treat live-turn,
+operator-present proposing as the only supported path for now.
+
+## Anti-patterns
+
+- ❌ Proposing against an empty or thin bank — synthesizes to noise.
+- ❌ An identity / "who is the user" source_query — forbidden; profile banks own that.
+- ❌ Ten near-duplicate models under different names — semantically dedupe first.
+- ❌ Firing a card per cluster — respect the 5/hour limit; propose the top few.
+- ❌ `refresh_after_consolidation: true` by default — it's an invisible cost; leave it off unless the model tracks fast-moving state.
+- ❌ A vague `reason` — the operator denies it and you've burned a slot.
+- ❌ Looping/polling after a proposal — end the turn; the resume inbound wakes you.
+
+## Output
+
+In propose mode: a short line naming what you proposed and that the operator's
+tap will resume the flow. In dry-run mode: the ranked candidate list (name +
+source_query + reason) and nothing fired.

package/telegram-plugin/auth-snapshot-format.ts

@@ -447,30 +447,27 @@ function pctCells(
 }
 
 /**
- * The Status cell: for a blocked account, when the binding window comes back
- * (`back <when>`); for a healthy/throttling account, when the soonest window
- * refills (`refills <when>`). `<when>` is the tz-aware absolute time (date shown
- * only when not today) plus the concise relative hint in parens.
+ * The per-window reset cell (`5h resets` / `7d resets`): the tz-aware absolute
+ * reset time for THAT specific window (date shown only when not today) plus the
+ * concise relative hint in parens — e.g. `1:20 PM (in 2h)`.
+ *
+ * Degrades in lockstep with `pctCells` so the percentage cell and its reset cell
+ * always agree: no quota → probe-failed message (or `—`); thin probe → `quota
+ * unknown`; missing reset on an otherwise-present window → `—`.
  */
-function statusCell(snap: AccountSnapshot, now: Date, tz: string): string {
+function windowResetCell(
+  snap: AccountSnapshot,
+  now: Date,
+  tz: string,
+  win: '5h' | '7d',
+): string {
   if (!snap.quota) {
-    return snap.quotaError ? `probe failed (${snap.quotaError})` : 'probe failed';
+    return snap.quotaError ? `probe failed (${snap.quotaError})` : '—';
   }
   if (isProbeThin(snap.quota)) return 'quota unknown';
-  const q = snap.quota;
-  const health = classifyHealth(snap, now);
-  if (health === 'blocked') {
-    const win = bindingWindow(q);
-    const reset = win === '5h' ? q.fiveHourResetAt : q.sevenDayResetAt;
-    if (!reset) return 'back — (reset unknown)';
-    return `back ${formatStatusTime(reset, now, tz)} (in ${formatRelative(reset, now)})`;
-  }
-  // healthy / throttling — show the soonest refill across both windows.
-  const fiveIn = q.fiveHourResetAt ? q.fiveHourResetAt.getTime() - now.getTime() : Infinity;
-  const sevenIn = q.sevenDayResetAt ? q.sevenDayResetAt.getTime() - now.getTime() : Infinity;
-  const soonest = fiveIn <= sevenIn ? q.fiveHourResetAt : q.sevenDayResetAt;
-  if (!soonest) return 'refills —';
-  return `refills ${formatStatusTime(soonest, now, tz)} (in ${formatRelative(soonest, now)})`;
+  const reset = win === '5h' ? snap.quota.fiveHourResetAt : snap.quota.sevenDayResetAt;
+  if (!reset) return '—';
+  return `${formatStatusTime(reset, now, tz)} (in ${formatRelative(reset, now)})`;
 }
 
 export function renderAuthSnapshotFormat2(
@@ -495,8 +492,8 @@ export function renderAuthSnapshotFormat2(
 
   if (ordered.length > 0) {
     lines.push('');
-    lines.push('| State | Account | 5h | 7d | Status |');
-    lines.push('| --- | --- | --- | --- | --- |');
+    lines.push('| State | Account | 5h | 5h resets | 7d | 7d resets |');
+    lines.push('| --- | --- | --- | --- | --- | --- |');
     for (const s of ordered) {
       const emoji = HEALTH_EMOJI[classifyHealth(s, now)];
       // Account cell: FULL email, never truncated; active gets a (active) suffix.
@@ -512,9 +509,10 @@ export function renderAuthSnapshotFormat2(
       // tableCell wrap around the finished span.
       const accountCell = `\`${codeSpanSafe(s.isActive ? `${label} (active)` : label)}\``;
       const { five, seven } = pctCells(s, now);
-      const status = statusCell(s, now, tz);
+      const fiveReset = windowResetCell(s, now, tz, '5h');
+      const sevenReset = windowResetCell(s, now, tz, '7d');
       lines.push(
-        `| ${emoji} | ${tableCell(accountCell)} | ${five} | ${seven} | ${tableCell(status)} |`,
+        `| ${emoji} | ${tableCell(accountCell)} | ${five} | ${tableCell(fiveReset)} | ${seven} | ${tableCell(sevenReset)} |`,
       );
     }
   }

package/telegram-plugin/bridge/bridge.ts

@@ -30,6 +30,7 @@ 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'
+import { createOutstandingPermissionLedger } from './permission-ledger.js'
 
 installPluginLogger()
 
@@ -417,6 +418,24 @@ const TOOL_SCHEMAS = [
       required: ['chat_id', 'key'],
     },
   },
+  {
+    name: 'mental_model_propose',
+    description:
+      "Propose a Hindsight MENTAL MODEL for the operator to approve (agent-proposes → human-approves, hindsight Phase 5). Use this when — over real work — 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 — appended to your `memory.mental_models[]` in switchroom.yaml via the operator-approved config-edit path — 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 — it is the leashed, human-gated way to add a DURABLE declared model to your config. After firing this tool, END YOUR TURN cleanly — 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 — 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 — 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 — 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:
@@ -582,6 +601,40 @@ mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
 // added by either is honoured by all.
 const sessionAllowRules = new Set<string>()
 
+// #2861: outstanding permission-request ledger. Every permission_request from
+// claude is recorded here and re-sent on each IPC (re)connect, so a request
+// that arrives while the gateway is down (or that the gateway lost across a
+// restart) is redelivered instead of dropped. Deleted in onPermission when a
+// verdict is delivered. Kill switch: SWITCHROOM_PERMISSION_REARM=0 reverts to
+// the legacy drop-when-disconnected behavior.
+const outstandingPermissions = createOutstandingPermissionLedger()
+const permissionRearmEnabled = process.env.SWITCHROOM_PERMISSION_REARM !== '0'
+
+/**
+ * Re-send every outstanding permission_request to the gateway. Called on each
+ * IPC (re)connect via the ipc-client onConnect hook. The gateway dedupes /
+ * re-arms them idempotently (gateway/permission-rearm.ts), so re-sending on
+ * every reconnect is safe. Never answers a card — re-transmits the question.
+ */
+function flushOutstandingPermissionRequests(): void {
+  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\n`,
+  )
+  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,
+    })
+  }
+}
+
 mcp.setNotificationHandler(
   z.object({
     method: z.literal('notifications/claude/channel/permission_request'),
@@ -615,8 +668,29 @@ mcp.setNotificationHandler(
         return
       }
     }
+    // #2861: record the request in the outstanding ledger BEFORE the connect
+    // check so it survives a disconnected gateway and is re-sent on reconnect.
+    // It's deleted in onPermission when the verdict is delivered.
+    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\n')
+      // BUFFER, don't drop (#2861 R2). The request is in the ledger; the
+      // onConnect flush re-sends it once the gateway is reachable. Falls back
+      // to the legacy drop only when re-arm is killed.
+      if (permissionRearmEnabled) {
+        process.stderr.write(
+          `telegram bridge: permission_request buffered (gateway offline), will re-send on reconnect ` +
+          `request_id=${params.request_id}\n`,
+        )
+      } else {
+        process.stderr.write('telegram bridge: permission_request received but not connected to gateway\n')
+      }
       return
     }
     ipc.sendPermissionRequest({
@@ -658,6 +732,9 @@ function onPermission(msg: PermissionEvent): void {
   if (msg.rule) {
     sessionAllowRules.add(msg.rule)
   }
+  // #2861: verdict delivered → drop the request from the outstanding ledger so
+  // a later reconnect doesn't re-send an already-resolved approval.
+  outstandingPermissions.delete(msg.requestId)
   mcp.notification({
     method: 'notifications/claude/channel/permission',
     params: {
@@ -836,6 +913,8 @@ async function main(): Promise<void> {
     onInbound,
     onPermission,
     onStatus,
+    // #2861: re-send outstanding permission requests on every (re)connect.
+    onConnect: flushOutstandingPermissionRequests,
     log: (msg) => process.stderr.write(`telegram bridge: ipc: ${msg}\n`),
     // #2307 Tier-1: the cron-session bridge shares the agent's STATE_DIR
     // (access.json / history / gateway.sock) but writes its liveness file to a

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

@@ -48,6 +48,14 @@ export interface IpcClientOptions {
   onInbound: (msg: InboundMessage) => void;
   onPermission: (msg: PermissionEvent) => void;
   onStatus: (msg: StatusEvent) => void;
+  /**
+   * Called every time the socket (re)connects and has registered — i.e. on
+   * the initial connect AND on each background reconnect. The bridge uses
+   * this to flush its outstanding permission-request ledger so approvals
+   * that arrived while the gateway was down are re-sent (#2861). Best-effort:
+   * a throw here is logged, never propagated into the socket open path.
+   */
+  onConnect?: () => void;
   log?: (msg: string) => void;
   reconnectDelayMs?: number;
   maxReconnectDelayMs?: number;
@@ -93,6 +101,7 @@ export function createIpcClient(options: IpcClientOptions): Promise<IpcClientHan
     onInbound,
     onPermission,
     onStatus,
+    onConnect,
     log = () => {},
     reconnectDelayMs = 2000,
     maxReconnectDelayMs = 30000,
@@ -237,6 +246,16 @@ export function createIpcClient(options: IpcClientOptions): Promise<IpcClientHan
             sendRegister();
             startHeartbeat();
             log(`connected to ${socketPath}`);
+            // Fire the (re)connect hook AFTER register + heartbeat so the
+            // bridge's ledger flush writes onto a live, registered socket.
+            // Best-effort: never let a callback throw abort the open path.
+            if (onConnect) {
+              try {
+                onConnect();
+              } catch (err) {
+                log(`onConnect hook threw: ${err}`);
+              }
+            }
             resolve();
           },
           data(sock, data) {

package/telegram-plugin/bridge/permission-ledger.ts

@@ -0,0 +1,61 @@
+/**
+ * Bridge-side outstanding permission-request ledger (#2861 / umbrella #2859).
+ *
+ * Problem it closes (R2): the bridge's `permission_request` handler used to
+ * DROP the request when the gateway IPC was down
+ * (`if (!ipc || !ipc.isConnected()) { log; return }`). claude stays suspended
+ * inside the MCP permission call, no card is ever posted, the turn wedges
+ * forever. There was no record of the ask to re-send once the gateway came
+ * back.
+ *
+ * Fix: every `permission_request` notification from claude is recorded here,
+ * keyed by request_id. When the IPC (re)connects, the bridge re-sends every
+ * outstanding request (the gateway dedupes / re-arms them idempotently — see
+ * `gateway/permission-rearm.ts`). An entry is deleted the moment a verdict is
+ * delivered back to claude (`onPermission`), so a resolved request is never
+ * re-sent.
+ *
+ * This never answers a card — it only re-transmits the QUESTION
+ * (no-self-escalation invariant). Pure in-memory bookkeeping: no model
+ * callsite, no I/O.
+ */
+
+/** The claude-side `permission_request` params the bridge forwards. */
+export interface OutstandingPermissionParams {
+  request_id: string
+  tool_name: string
+  description: string
+  input_preview: string
+}
+
+export interface OutstandingPermissionLedger {
+  /** Record a request. Idempotent on request_id (latest params win). */
+  add(params: OutstandingPermissionParams): void
+  /** Remove a request once its verdict has been delivered. */
+  delete(requestId: string): void
+  has(requestId: string): boolean
+  /** Snapshot of all outstanding requests (insertion order). */
+  all(): OutstandingPermissionParams[]
+  readonly size: number
+}
+
+export function createOutstandingPermissionLedger(): OutstandingPermissionLedger {
+  const map = new Map<string, OutstandingPermissionParams>()
+  return {
+    add(params) {
+      map.set(params.request_id, params)
+    },
+    delete(requestId) {
+      map.delete(requestId)
+    },
+    has(requestId) {
+      return map.has(requestId)
+    },
+    all() {
+      return [...map.values()]
+    },
+    get size() {
+      return map.size
+    },
+  }
+}