polygram 0.12.0-rc.12 → 0.12.0-rc.13

package/config.example.json

@@ -72,7 +72,9 @@
       "effort": "medium",
       "cwd": "/Users/you/admin-agent",
       "timeout": 600,
-      "_comment_maxFileBytes": "OPTIONAL per-chat (or per-topic; topic wins) file-size cap in BYTES. There is NO fixed default — the default is backend-derived: cloud Telegram = 50MB send / 20MB receive; with a local Bot API server (bot.apiRoot set) = 2GB both ways. This key only LOWERS that ceiling for this chat (Telegram rejects anything above the backend limit regardless); omit it to use the full backend default. To set one, add e.g. \"maxFileBytes\": 104857600 (=100MB) — only meaningful when apiRoot is set, since cloud already clamps to 50/20MB."
+      "_comment_maxFileBytes": "OPTIONAL per-chat (or per-topic; topic wins) file-size cap in BYTES. There is NO fixed default — the default is backend-derived: cloud Telegram = 50MB send / 20MB receive; with a local Bot API server (bot.apiRoot set) = 2GB both ways. This key only LOWERS that ceiling for this chat (Telegram rejects anything above the backend limit regardless); omit it to use the full backend default. To set one, add e.g. \"maxFileBytes\": 104857600 (=100MB) — only meaningful when apiRoot is set, since cloud already clamps to 50/20MB.",
+      "_comment_compactionWarnings": "OPTIONAL per-chat (or per-topic; topic wins). CLI/channels backend (pm:'cli') only. Default OFF. When ON, polygram warns the chat as Claude's context fills so you can /compact on your terms BEFORE an auto-compaction interrupts a turn (auto-compaction detaches the channels MCP bridge mid-turn — see docs/0.12.0-compaction-warnings.md). Two forms: `true` (enable at the 75% default threshold) or `{ \"enabled\": true, \"thresholdPct\": 80 }` (custom 1-99 threshold). Proactive: at the threshold it posts 'context ~N% full, run /compact or /new at a break'. Reactive backstop: when claude auto-compacts anyway it posts 'compacting now, resend if quiet'. Manual /compact never warns. Requires the bot to allow /compact + /new commands.",
+      "compactionWarnings": true
     },
 
     "-1000000000001": {

package/lib/compaction-warn.js

@@ -0,0 +1,59 @@
+/**
+ * compaction-warn — per-chat config resolution + warn-once state for the
+ * compaction warning (0.12.0-rc.13).
+ *
+ * The warning is OFF by default. A chat (or topic) opts in via
+ * `compactionWarnings`:
+ *   true                                   → enabled, default threshold
+ *   { enabled: true, thresholdPct: 80 }    → enabled, custom threshold
+ *   false / absent / object w/o enabled    → off
+ *
+ * `thresholdPct` is the context-fill % at which the PROACTIVE warning fires
+ * (propose /compact before claude auto-compacts mid-turn). Default 75 — below
+ * claude's own auto-compact threshold so the user gets a window to act.
+ */
+
+'use strict';
+
+const DEFAULT_THRESHOLD_PCT = 75;
+
+/**
+ * @param {object|undefined} cfg  resolved topic/chat config (getTopicConfig result)
+ * @returns {{enabled: boolean, thresholdPct: number}}
+ */
+function resolveCompactionWarnConfig(cfg) {
+  const raw = cfg?.compactionWarnings;
+  const off = { enabled: false, thresholdPct: DEFAULT_THRESHOLD_PCT };
+
+  if (raw === true) return { enabled: true, thresholdPct: DEFAULT_THRESHOLD_PCT };
+  if (raw && typeof raw === 'object' && raw.enabled === true) {
+    const t = Number(raw.thresholdPct);
+    const thresholdPct = (Number.isFinite(t) && t > 0 && t < 100) ? t : DEFAULT_THRESHOLD_PCT;
+    return { enabled: true, thresholdPct };
+  }
+  return off;
+}
+
+/**
+ * Per-session "have we already warned on this climb?" state. Warn ONCE per
+ * session until reset — without this the proactive warning would re-fire on
+ * every turn-end while the context stays high. Reset on a successful
+ * compaction (PostCompact → context dropped) or a fresh session so the next
+ * climb can warn again. Mirrors the autoResumeTracker shape.
+ */
+function createCompactionWarnTracker() {
+  const warned = new Set();
+  return {
+    shouldWarn(sessionKey) { return !warned.has(sessionKey); },
+    markWarned(sessionKey) { warned.add(sessionKey); },
+    reset(sessionKey) { warned.delete(sessionKey); },
+    resetAll() { warned.clear(); },
+    _size() { return warned.size; },
+  };
+}
+
+module.exports = {
+  resolveCompactionWarnConfig,
+  createCompactionWarnTracker,
+  DEFAULT_THRESHOLD_PCT,
+};

package/lib/context-usage.js

@@ -0,0 +1,93 @@
+/**
+ * context-usage — read live context occupancy from a Claude Code session
+ * transcript (JSONL).
+ *
+ * Used by the per-chat compaction warning (0.12.0-rc.13). polygram has no
+ * usage payload on the channels/CLI backend (hook events carry none — see
+ * the rc.13 spike), so the only source of "how full is the context" is the
+ * transcript itself. We read it ONCE per turn-end (Stop hook), not on a
+ * poll loop, so a single streamed pass is fine.
+ *
+ * What "occupancy" means: Claude's own context-% / auto-compact threshold is
+ * measured against what's fed INTO the model each turn —
+ *   input_tokens + cache_read_input_tokens + cache_creation_input_tokens
+ * (cache_read dominates once the conversation is warm). output_tokens is the
+ * reply, not context, so it's excluded.
+ *
+ * We take the LAST main-thread (non-sidechain) assistant frame with a usage
+ * block. Subagents write to their own agent_transcript_path so sidechain
+ * frames don't normally appear here, but we skip them defensively: a format
+ * change that inlined a subagent's large usage would otherwise spike the
+ * parent's apparent context and trigger a false "you're full" warning.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const readline = require('node:readline');
+
+// Standard Claude context window (sonnet/opus, non-beta). The warning is a
+// heuristic ("you're getting full"), so an approximate denominator is fine;
+// callers can pass a different window for 1M-beta sessions.
+const DEFAULT_WINDOW_TOKENS = 200_000;
+
+/**
+ * @param {string} transcriptPath
+ * @returns {Promise<{inputTokens:number, cacheReadTokens:number, cacheCreationTokens:number, total:number} | null>}
+ *   null when the path is falsy/unreadable or no usable usage frame exists.
+ */
+async function readContextTokens(transcriptPath) {
+  if (!transcriptPath) return null;
+
+  let stream;
+  try {
+    stream = fs.createReadStream(transcriptPath, { encoding: 'utf8' });
+  } catch {
+    return null;
+  }
+
+  return new Promise((resolve) => {
+    let last = null;
+    // Resolve only once — error and close can both fire.
+    let done = false;
+    const finish = (v) => { if (!done) { done = true; resolve(v); } };
+
+    stream.on('error', () => finish(null));
+
+    const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+    // readline forwards the input stream's 'error' (e.g. ENOENT on open) to
+    // the interface; without this handler that re-emit is unhandled and
+    // crashes the process even though we resolved null on the stream error.
+    rl.on('error', () => finish(null));
+    rl.on('line', (line) => {
+      if (!line) return;
+      let o;
+      try { o = JSON.parse(line); } catch { return; }  // skip partial/non-JSON lines
+      if (!o || o.type !== 'assistant' || o.isSidechain === true) return;
+      const u = o.message?.usage;
+      if (!u) return;
+      const inputTokens = Number(u.input_tokens) || 0;
+      const cacheReadTokens = Number(u.cache_read_input_tokens) || 0;
+      const cacheCreationTokens = Number(u.cache_creation_input_tokens) || 0;
+      const total = inputTokens + cacheReadTokens + cacheCreationTokens;
+      if (total > 0) last = { inputTokens, cacheReadTokens, cacheCreationTokens, total };
+    });
+    rl.on('close', () => finish(last));
+  });
+}
+
+/**
+ * Fraction (0..1) of the context window currently occupied. Clamps to 0 on
+ * non-positive / non-finite inputs so callers never see NaN/Infinity.
+ *
+ * @param {number} totalTokens
+ * @param {number} [windowTokens=DEFAULT_WINDOW_TOKENS]
+ * @returns {number}
+ */
+function contextPct(totalTokens, windowTokens = DEFAULT_WINDOW_TOKENS) {
+  if (!Number.isFinite(totalTokens) || totalTokens <= 0) return 0;
+  if (!Number.isFinite(windowTokens) || windowTokens <= 0) return 0;
+  return totalTokens / windowTokens;
+}
+
+module.exports = { readContextTokens, contextPct, DEFAULT_WINDOW_TOKENS };

package/lib/process/cli-process.js

@@ -53,6 +53,8 @@ const { createHookTail } = require('./hook-event-tail');
 // /private/tmp drift — one of the original Music-topic failures).
 const { DEFAULT_ATTACHMENT_BASE } = require('./channels-tool-dispatcher');
 const { resolveFileCaps } = require('../attachments');
+const { resolveCompactionWarnConfig } = require('../compaction-warn');
+const { readContextTokens, contextPct } = require('../context-usage');
 const { runStartupGate } = require('../tmux/startup-gate');
 const { POLYGRAM_DISPLAY_HINT } = require('../telegram/display-hint');
 
@@ -520,6 +522,14 @@ class CliProcess extends Process {
       override: _capOverride,
     }).outBytes;
 
+    // 0.12.0-rc.13: per-chat/topic compaction warning (default OFF). Same
+    // topic→chat precedence as the file cap above. When enabled, the channels
+    // backend warns the chat as context fills (propose /compact at a break)
+    // and on auto-compaction (the event that detaches the bridge mid-turn).
+    const _compactionWarnRaw = topicConfig?.compactionWarnings ?? opts.chatConfig?.compactionWarnings;
+    this.compactionWarn = resolveCompactionWarnConfig({ compactionWarnings: _compactionWarnRaw });
+    this._compactionWarned = false;  // proactive warn-once per climb; reset on PostCompact
+
     // Parity audit P8 + rc.8 fs-guard (2026-05-26 shumorobot Music topic):
     // `--session-id <id>` creates a NEW claude session with that id;
     // `--resume <id>` resumes the EXISTING conversation. Lazy-respawn after
@@ -1738,6 +1748,38 @@ class CliProcess extends Process {
           lastAssistantMessage: ev.lastAssistantMessage,
           backend: this.backend,
         });
+        // 0.12.0-rc.13 proactive compaction warning: on turn-end, if enabled
+        // for this chat and not already warned this climb, sample context
+        // occupancy from the transcript and warn (propose /compact) BEFORE
+        // claude auto-compacts mid-turn and detaches the bridge. Fire-and-
+        // forget — transcript IO must never block the stop path.
+        if (this.compactionWarn?.enabled && !this._compactionWarned && ev.transcriptPath) {
+          this._maybeProactiveCompactionWarn(ev.transcriptPath);
+        }
+        return;
+
+      case 'PreCompact':
+        // 0.12.0-rc.13: auto-compaction is the event that detaches the
+        // channels MCP bridge mid-turn. Record it; and on the dangerous AUTO
+        // case (manual /compact is the user's own deliberate action — never
+        // nag), emit a reactive warning the chat layer posts. The proactive
+        // warning (on Stop) tries to PREVENT this; this is the backstop.
+        this._logEvent('cli-compaction-imminent', { trigger: ev.trigger });
+        if (this.compactionWarn?.enabled && ev.trigger === 'auto') {
+          this.emit('compaction-warn', {
+            kind: 'reactive',
+            trigger: 'auto',
+            sessionId: this.claudeSessionId,
+            backend: this.backend,
+          });
+        }
+        return;
+
+      case 'PostCompact':
+        // Context just dropped — re-arm the proactive warn-once so the next
+        // climb can warn again.
+        this._compactionWarned = false;
+        this._logEvent('cli-compaction-done', { trigger: ev.trigger });
         return;
 
       case 'Notification':
@@ -2320,6 +2362,37 @@ class CliProcess extends Process {
    * Extracted as a separate async method so unit tests can drive it
    * directly without waiting for the setInterval tick.
    */
+  /**
+   * 0.12.0-rc.13: proactive compaction warning. Read the transcript's current
+   * context occupancy and, if past the per-chat threshold, emit a
+   * 'compaction-warn' the chat layer turns into "you're ~N% full, run
+   * /compact" — giving the user a window to compact on their terms BEFORE
+   * claude auto-compacts mid-turn (which detaches the channels bridge). Warns
+   * once per climb (this._compactionWarned), re-armed on PostCompact.
+   * Fire-and-forget: swallows its own errors so transcript IO never breaks
+   * the turn-end path.
+   */
+  async _maybeProactiveCompactionWarn(transcriptPath) {
+    try {
+      if (!this.compactionWarn?.enabled || this._compactionWarned) return;
+      const usage = await readContextTokens(transcriptPath);
+      if (!usage) return;
+      const pct = contextPct(usage.total) * 100;
+      if (pct < this.compactionWarn.thresholdPct) return;
+      if (this._compactionWarned) return;   // re-check after the async gap
+      this._compactionWarned = true;
+      this.emit('compaction-warn', {
+        kind: 'proactive',
+        pct: Math.round(pct),
+        totalTokens: usage.total,
+        sessionId: this.claudeSessionId,
+        backend: this.backend,
+      });
+    } catch (err) {
+      this.logger.warn?.(`[${this.label}] compaction-warn sample failed: ${err.message}`);
+    }
+  }
+
   async _pollMidTurnDialogs() {
     if (this.closed) return;
     if (this.pendingTurns.size === 0) return;        // no work to do when idle

package/lib/process/hook-event-tail.js

@@ -51,6 +51,9 @@ const KNOWN_EVENT_NAMES = new Set([
   'SubagentStop',
   'Stop',
   'Notification',
+  // 0.12.0-rc.13: compaction lifecycle (carry `trigger` + custom_instructions).
+  'PreCompact',
+  'PostCompact',
 ]);
 
 /**
@@ -87,6 +90,10 @@ function normalizeHookEvent(raw) {
     prompt:              raw?.prompt ?? null,
     stopHookActive:      raw?.stop_hook_active ?? null,
     lastAssistantMessage: raw?.last_assistant_message ?? null,
+    // PreCompact/PostCompact payload: trigger distinguishes auto vs manual
+    // compaction; custom_instructions is the `/compact <hint>` text (manual).
+    trigger:             raw?.trigger ?? null,
+    customInstructions:  raw?.custom_instructions ?? null,
     receivedAtMs:        raw?.polygram_received_at_ms ?? null,
     raw,
   };

package/lib/process/hook-settings.js

@@ -44,6 +44,13 @@ const HOOK_EVENTS = [
   'SubagentStop',
   'Stop',
   'Notification',
+  // 0.12.0-rc.13: compaction lifecycle. PreCompact fires when claude is about
+  // to (auto-)compact — the moment that detaches the channels MCP bridge.
+  // PostCompact fires after, when context has dropped (used to re-arm the
+  // per-chat compaction warning). Both confirmed supported by the pinned CLI
+  // (2.1.142) and carry a `trigger: auto|manual` field.
+  'PreCompact',
+  'PostCompact',
 ];
 
 /**

package/lib/process-manager.js

@@ -41,6 +41,12 @@ const CALLBACK_TO_EVENT = {
   onAssistantMessageStart:      'assistant-message-start',
   onAutonomousAssistantMessage: 'autonomous-assistant-message',
   onCompactBoundary:            'compact-boundary',
+  // 0.12.0-rc.13: per-chat compaction warning. CliProcess emits
+  // 'compaction-warn' {kind:'proactive'|'reactive', pct?} when (proactive)
+  // context crosses the chat's threshold at turn-end, or (reactive) claude is
+  // auto-compacting now. The callback posts a chat message proposing /compact
+  // — opt-in per chat. See docs/0.12.0-file-send.md / lib/compaction-warn.js.
+  onCompactionWarn:             'compaction-warn',
   onQueueDrop:                  'queue-drop',
   onThinking:                   'thinking',
   // Tmux backend: TUI shows in-pane approval prompt. SDK backend

package/lib/sdk/callbacks.js

@@ -571,6 +571,42 @@ function createSdkCallbacks({
       }
     },
 
+    // 0.12.0-rc.13: per-chat compaction warning. CliProcess emits
+    // 'compaction-warn' when context crosses the chat's threshold at turn-end
+    // (proactive) or claude is auto-compacting now (reactive). Post a chat
+    // message proposing /compact so the user can compact on their terms BEFORE
+    // an auto-compaction interrupts a turn (and detaches the channels bridge).
+    // Opt-in per chat (lib/compaction-warn.js) — CliProcess only emits when
+    // enabled, so no extra config gate is needed here. Best-effort send.
+    onCompactionWarn: (sessionKey, payload /* , entry */) => {
+      try {
+        const chatId = getChatIdFromKey(sessionKey);
+        const threadIdRaw = getThreadIdFromKey(sessionKey);
+        const threadId = threadIdRaw ? parseInt(threadIdRaw, 10) : null;
+        const kind = payload?.kind === 'reactive' ? 'reactive' : 'proactive';
+        logEvent('compaction-warn', {
+          chat_id: chatId,
+          session_key: sessionKey,
+          kind,
+          pct: payload?.pct ?? null,
+          backend: payload?.backend ?? 'cli',
+        });
+        if (!bot) return;
+        const text = kind === 'reactive'
+          ? '🗜️ Auto-compacting now — context filled up. If this turn goes quiet, please resend. (Tip: running `/compact` at a natural break avoids mid-task compactions.)'
+          : `📚 Heads up — this chat's context is ~${payload?.pct ?? '?'}% full. To avoid an auto-compaction that can interrupt a turn, run \`/compact\` (optionally with a hint, e.g. \`/compact keep the recent decisions\`) at a natural break — or \`/new\` for a fresh start.`;
+        tg(bot, 'sendMessage', {
+          chat_id: chatId,
+          text,
+          ...(threadId ? { message_thread_id: threadId } : {}),
+        }, { source: 'compaction-warn', botName }).catch((err) => {
+          logger.error?.(`[${botName}] compaction-warn send failed: ${err.message}`);
+        });
+      } catch (err) {
+        logger.error?.(`[${botName}] compaction-warn handler: ${err.message}`);
+      }
+    },
+
     // 0.10.0 rc.42 #8: tmux backend hook-tail error observability.
     // Persistent failures of the hook ndjson tail degrade H3 idle-
     // ceiling accuracy and H4 Stop-synth coverage with no surface

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polygram",
-  "version": "0.12.0-rc.12",
+  "version": "0.12.0-rc.13",
   "description": "Telegram daemon for Claude Code that preserves the OpenClaw per-chat session model. Migration path for OpenClaw users moving to Claude Code.",
   "main": "lib/ipc/client.js",
   "bin": {