polygram 0.9.0 → 0.10.0-rc.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "polygram",
-  "version": "0.9.0",
+  "version": "0.10.0-rc.1",
   "description": "Telegram integration for Claude Code that preserves the OpenClaw per-chat session model. Migration target for OpenClaw users. Multi-bot, multi-chat, per-topic isolation; SQLite transcripts; inline-keyboard approvals. Bundles /polygram:status|logs|pair-code|approvals admin commands plus history (transcript queries) and polygram-send (out-of-turn IPC sends with file-upload validation) skills.",
   "keywords": [
     "telegram",

package/lib/db.js

@@ -19,7 +19,7 @@ const Database = require('better-sqlite3');
 // SCHEMA_VERSION; the early-return on line ~42 then skipped the
 // migration loop on any DB already at user_version=8 → turn_metrics
 // table never created → INSERT prepare at startup crashed polygram.
-const SCHEMA_VERSION = 10;
+const SCHEMA_VERSION = 11;
 
 // Sentinel `error` value for outbound rows whose API call may or may not
 // have reached Telegram. markStalePending writes it; hasOutboundReplyTo
@@ -118,10 +118,10 @@ function wrap(db) {
   const upsertSessionStmt = db.prepare(`
     INSERT INTO sessions (
       session_key, chat_id, thread_id, claude_session_id,
-      agent, cwd, model, effort, created_ts, last_active_ts
+      agent, cwd, model, effort, pm_backend, created_ts, last_active_ts
     ) VALUES (
       @session_key, @chat_id, @thread_id, @claude_session_id,
-      @agent, @cwd, @model, @effort, @ts, @ts
+      @agent, @cwd, @model, @effort, @pm_backend, @ts, @ts
     )
     ON CONFLICT(session_key) DO UPDATE SET
       chat_id = excluded.chat_id,
@@ -131,12 +131,14 @@ function wrap(db) {
       cwd = excluded.cwd,
       model = excluded.model,
       effort = excluded.effort,
+      pm_backend = excluded.pm_backend,
       last_active_ts = excluded.last_active_ts
   `);
 
   const getSessionStmt = db.prepare(`SELECT * FROM sessions WHERE session_key = ?`);
   const touchSessionStmt = db.prepare(`UPDATE sessions SET last_active_ts = ? WHERE session_key = ?`);
   const clearSessionIdStmt = db.prepare(`DELETE FROM sessions WHERE session_key = ?`);
+  const setSessionBackendStmt = db.prepare(`UPDATE sessions SET pm_backend = ? WHERE session_key = ?`);
 
   const getMessageStmt = db.prepare(`
     SELECT * FROM messages WHERE chat_id = ? AND msg_id = ?
@@ -291,6 +293,8 @@ function wrap(db) {
         cwd: row.cwd || null,
         model: row.model || null,
         effort: row.effort || null,
+        // 0.10.0: pm_backend defaults to 'sdk' if caller doesn't set it.
+        pm_backend: row.pm_backend || 'sdk',
         ts: row.ts || Date.now(),
       });
     },
@@ -307,6 +311,13 @@ function wrap(db) {
       return clearSessionIdStmt.run(sessionKey);
     },
 
+    // 0.10.0: backend reassignment without resetting other session fields.
+    // Used when ProcessManager spawns a Process with a different backend
+    // than the persisted row says (drift event fires too).
+    setSessionBackend(sessionKey, backend) {
+      return setSessionBackendStmt.run(backend, sessionKey);
+    },
+
     getMessage(chatId, msgId) {
       return getMessageStmt.get(String(chatId), msgId);
     },

package/lib/handlers/slash-commands.js

@@ -52,18 +52,24 @@ function createSlashCommands({
     } = ctx;
     const botAllowsCommands = !!config.bot?.allowConfigCommands;
 
-    // /context
+    // /context — route through pm.getContextUsage(sessionKey) so the
+    // call works for both SDK and tmux backends (the latter computes
+    // from JSONL message.usage). Pre-0.10.0-P0.2 this reached into
+    // entry.query.getContextUsage directly, which silently said "No
+    // active session yet" on tmux even when the chat was alive.
     if (botAllowsCommands && text === '/context') {
-      const entry = pm.get(sessionKey);
-      const q = entry?.query;
-      if (!q || typeof q.getContextUsage !== 'function') {
+      if (!pm.has(sessionKey)) {
         await sendReply('📚 No active session yet — send a message first, then /context.');
         return true;
       }
       try {
-        const u = await q.getContextUsage();
+        const u = await pm.getContextUsage(sessionKey);
         await sendReply(formatContextReply(u));
       } catch (err) {
+        if (err?.code === 'UNSUPPORTED_OPERATION' || err?.code === 'NOT_IMPLEMENTED_YET') {
+          await sendReply('📚 Context info not available yet — send a message first, then /context.');
+          return true;
+        }
         logger.error?.(`[${label}] /context failed: ${err.message}`);
         await sendReply(`📚 Couldn't fetch context info: ${err.message}`);
       }
@@ -99,16 +105,20 @@ function createSlashCommands({
           resumed_session_id: savedSessionId,
         });
       }
-      if (!entry?.inputController?.push) {
-        await sendReply('🗜️ Session not ready for /compact (no input controller).');
+      if (!entry || typeof entry.fireUserMessage !== 'function') {
+        await sendReply('🗜️ Session not ready for /compact.');
         return true;
       }
       try {
-        entry.inputController.push({
-          type: 'user',
-          message: { role: 'user', content: text },
-          parent_tool_use_id: null,
-        });
+        // 0.10.0 P0.3 fix: route through Process.fireUserMessage so
+        // SDK (push to inputController) and tmux (paste to TUI) both
+        // handle the slash command. Pre-0.10.0-P0.3 reached into
+        // entry.inputController.push directly — broken on tmux.
+        const ok = entry.fireUserMessage(text);
+        if (!ok) {
+          await sendReply('🗜️ Session not ready for /compact.');
+          return true;
+        }
         logEvent('compact-command', {
           chat_id: chatId, thread_id: threadIdStr, session_key: sessionKey,
           text_len: text.length,

package/lib/model-costs.js

@@ -0,0 +1,60 @@
+/**
+ * Anthropic Claude API price rates per million tokens.
+ *
+ * Used by TmuxProcess to compute `cost_usd` per turn, since the
+ * per-session JSON log only carries token counts, not cost. SDK
+ * backend doesn't need this — Anthropic's claude-agent-sdk reports
+ * `total_cost_usd` directly in the result event.
+ *
+ * **Update reminder:** these rates can change. Last verified
+ * 2026-05-15 against https://www.anthropic.com/pricing. When rates
+ * shift, update the table here and bump the comment date.
+ *
+ * If a model isn't in the table, the `default` rates apply (Sonnet
+ * 4.6 today). Adding a new model is a 5-line PR.
+ */
+
+'use strict';
+
+// Per-million-token rates ($ USD). Cache-read and cache-creation
+// follow Anthropic's prompt-caching pricing — read is ~10% of normal
+// input; 1-hour creation is ~125% of normal input.
+const MODEL_COSTS = {
+  // Claude Sonnet 4.6
+  'claude-sonnet-4-6': { input: 3, output: 15, cacheRead: 0.30, cacheCreation: 3.75 },
+  // Claude Haiku 4.5 (date-suffixed model names map here via the
+  // `.replace(/-\d{8}$/, '')` strip in computeCostUsd; no need for
+  // a duplicate entry per snapshot).
+  'claude-haiku-4-5': { input: 0.80, output: 4, cacheRead: 0.08, cacheCreation: 1 },
+  // Claude Opus 4.7 (1M context)
+  'claude-opus-4-7': { input: 15, output: 75, cacheRead: 1.50, cacheCreation: 18.75 },
+  // Default fallback — Sonnet rates (safest mid-tier estimate).
+  default: { input: 3, output: 15, cacheRead: 0.30, cacheCreation: 3.75 },
+};
+
+/**
+ * Compute USD cost from a token-usage snapshot.
+ *
+ * @param {object} usage  — { inputTokens, outputTokens, cacheReadTokens, cacheCreationTokens }
+ * @param {string|null} model  — e.g. 'claude-haiku-4-5-20251001'
+ * @returns {number} cost in USD; 0 if usage is missing
+ */
+function computeCostUsd(usage, model) {
+  if (!usage) return 0;
+  // Try exact match first; then prefix match (strip date suffix like -20251001).
+  let rate = MODEL_COSTS[model];
+  if (!rate && typeof model === 'string') {
+    const stripped = model.replace(/-\d{8}$/, '');
+    rate = MODEL_COSTS[stripped];
+  }
+  if (!rate) rate = MODEL_COSTS.default;
+  const M = 1_000_000;
+  return (
+    (usage.inputTokens || 0) * rate.input / M
+    + (usage.outputTokens || 0) * rate.output / M
+    + (usage.cacheReadTokens || 0) * rate.cacheRead / M
+    + (usage.cacheCreationTokens || 0) * rate.cacheCreation / M
+  );
+}
+
+module.exports = { computeCostUsd, MODEL_COSTS };

package/lib/process/factory.js

@@ -0,0 +1,102 @@
+/**
+ * Process factory — chooses + constructs the right Process subclass
+ * per session, based on chat / topic / bot config.
+ *
+ * Backends:
+ *   - 'sdk'  → SdkProcess  (default; long-lived SDK Query)
+ *   - 'tmux' → TmuxProcess (claude TUI hosted in a tmux session)
+ *
+ * Backend selection precedence:
+ *   topicConfig.pm > chatConfig.pm > config.bot.pm > 'sdk'
+ *
+ * The tmux backend requires a `tmuxRunner` + `botName` to be passed
+ * into createProcessFactory. If a tmux-routed chat is encountered
+ * without those wired, we log a loud warning and fall back to SDK so
+ * the daemon stays up (R2-F7 — never silent-fail config).
+ *
+ * @see docs/0.10.0-process-manager-abstraction-plan.md §6.4
+ */
+
+'use strict';
+
+const { SdkProcess } = require('./sdk-process');
+const { TmuxProcess } = require('./tmux-process');
+
+/**
+ * @param {object} opts
+ * @param {object} opts.config            — runtime config object
+ * @param {Function} opts.spawnFn          — buildSdkOptions (SDK backend only)
+ * @param {object} [opts.db]               — for SdkProcess._logEvent + clearSessionId
+ * @param {object} [opts.logger]
+ * @param {number} [opts.queueCap]
+ * @param {number} [opts.queryCloseTimeoutMs]
+ * @param {object} [opts.tmuxRunner]       — required when ANY chat routes to 'tmux'
+ * @param {string} [opts.botName]          — required when ANY chat routes to 'tmux'
+ * @param {object} [opts.pollScheduler]    — shared PollScheduler instance.
+ *   When provided, all TmuxProcess instances share ONE setInterval for
+ *   their polling loops (one timer regardless of how many in-flight
+ *   tmux chats). Falls back to per-instance setTimeout when omitted.
+ * @returns {Function} processFactory(sessionKey, ctx) → Process
+ */
+function createProcessFactory({
+  config,
+  spawnFn,
+  db = null,
+  logger = console,
+  queueCap,
+  queryCloseTimeoutMs,
+  tmuxRunner = null,
+  botName = null,
+  pollScheduler = null,
+} = {}) {
+  if (typeof spawnFn !== 'function') {
+    throw new TypeError('createProcessFactory: spawnFn required');
+  }
+
+  return function processFactory(sessionKey, ctx) {
+    const chatId = ctx?.chatId ?? null;
+    const threadId = ctx?.threadId ?? null;
+    const label = ctx?.label || sessionKey;
+
+    const choice = pickBackend({ config, chatId, threadId });
+
+    if (choice === 'tmux') {
+      if (!tmuxRunner || !botName) {
+        logger.warn?.(
+          `[${label}] config requests pm:'tmux' but tmuxRunner/botName not wired; ` +
+          `falling back to SdkProcess. Pass {tmuxRunner, botName} to createProcessFactory.`,
+        );
+      } else {
+        return new TmuxProcess({
+          sessionKey, chatId, threadId, label,
+          runner: tmuxRunner,
+          botName,
+          logger,
+          pollScheduler,
+        });
+      }
+    }
+
+    return new SdkProcess({
+      sessionKey, chatId, threadId, label,
+      spawnFn,
+      db,
+      logger,
+      queueCap,
+      queryCloseTimeoutMs,
+    });
+  };
+}
+
+/**
+ * Per-chat / per-topic backend choice. Phase 1 always returned 'sdk'.
+ * Phase 2 honors topicConfig.pm / chatConfig.pm / config.bot.pm.
+ */
+function pickBackend({ config, chatId, threadId }) {
+  if (!chatId) return 'sdk';
+  const chatCfg = config?.chats?.[chatId];
+  const topicCfg = threadId && chatCfg?.topics?.[threadId];
+  return topicCfg?.pm || chatCfg?.pm || config?.bot?.pm || 'sdk';
+}
+
+module.exports = { createProcessFactory, pickBackend };

package/lib/process/process.js

@@ -0,0 +1,193 @@
+/**
+ * Abstract Process — one running Claude session, regardless of backend.
+ *
+ * Subclasses ship per backend:
+ *   - SdkProcess  (lib/process/sdk-process.js)  — long-lived
+ *                  @anthropic-ai/claude-agent-sdk Query
+ *   - TmuxProcess (lib/process/tmux-process.js) — claude TUI hosted
+ *                  inside a tmux session (Phase 2)
+ *
+ * State machine: spawned → ready → (turn-in-flight | idle) ↔ closed.
+ *
+ * Public surface mirrors what polygram's handleMessage, slash-commands,
+ * autosteer, edit-correction etc. already call on the current SDK pm.
+ * Callers don't branch on subclass.
+ *
+ * Optional methods come in two flavors per the v3 audit:
+ *   - Async ones MAY throw UnsupportedOperationError. Callers `await` +
+ *     try/catch around them.
+ *   - Sync HOT-PATH ones (drainQueue, injectUserMessage) return a
+ *     sentinel value, NEVER throw. Per R1-F1: autosteer's call site
+ *     has no try/catch — a throw would crash the message handler.
+ *
+ * Weighted LRU: each Process advertises its `cost`. The pm evicts
+ * to keep Σ cost ≤ budget rather than count ≤ cap. SDK Process cost=1,
+ * TmuxProcess cost=3 (per Phase 0 F-spike-2: tmux ~545MB vs SDK ~50MB
+ * per session).
+ *
+ * Phase 0 spike findings — `docs/0.10.0-phase0-spike-findings.md`.
+ * Spec — `docs/0.10.0-process-manager-abstraction-plan.md`.
+ */
+
+'use strict';
+
+const EventEmitter = require('events');
+
+class UnsupportedOperationError extends Error {
+  constructor(method, backend) {
+    super(`Operation ${method} not supported by ${backend} backend`);
+    this.name = 'UnsupportedOperationError';
+    this.code = 'UNSUPPORTED_OPERATION';
+    this.method = method;
+    this.backend = backend;
+  }
+}
+
+class Process extends EventEmitter {
+  /**
+   * @param {object} opts
+   * @param {string} opts.sessionKey      polygram session key
+   * @param {string|null} opts.chatId
+   * @param {string|null} opts.threadId
+   * @param {string} opts.label           human-readable for logs
+   */
+  constructor({ sessionKey, chatId, threadId, label } = {}) {
+    super();
+    if (typeof sessionKey !== 'string' || sessionKey.length === 0) {
+      throw new TypeError('Process: sessionKey (string) required');
+    }
+    // Identity — immutable after construction
+    this.sessionKey = sessionKey;
+    this.chatId = chatId == null ? null : String(chatId);
+    this.threadId = threadId == null ? null : String(threadId);
+    this.label = label || `${this.chatId || ''}${this.threadId ? '/' + this.threadId : ''}` || sessionKey;
+    // backend identifier — subclass overrides
+    this.backend = 'abstract';
+
+    // Mutable state
+    this.closed = false;
+    this.inFlight = false;
+    this.pendingQueue = [];
+    this.claudeSessionId = null;
+  }
+
+  /**
+   * Cost weight for LRU eviction (per Phase 0 F-spike-2).
+   * Subclass overrides. Defaults to 1 (SDK-equivalent).
+   */
+  get cost() {
+    return 1;
+  }
+
+  // ─── REQUIRED methods — subclass MUST override ─────────────────────
+
+  /**
+   * Cold-spawn this process. Wire up internals; mark ready when
+   * the underlying claude session is responsive.
+   *
+   * @param {object} opts — backend-specific. Typically includes:
+   *   existingSessionId  — for --resume continuity
+   *   model, effort, cwd, chatConfig, botName  — spawn params
+   */
+  async start(_opts) {
+    throw new Error(`${this.constructor.name}.start() must be overridden`);
+  }
+
+  /**
+   * Send a user turn. Resolves with a PmSendResult on completion.
+   *
+   * @param {string} prompt
+   * @param {object} [opts]
+   * @returns {Promise<PmSendResult>}
+   */
+  async send(_prompt, _opts) {
+    throw new Error(`${this.constructor.name}.send() must be overridden`);
+  }
+
+  /**
+   * Close cleanly. Returns when fully torn down.
+   * Idempotent.
+   *
+   * @param {string} [reason]
+   */
+  async kill(_reason) {
+    throw new Error(`${this.constructor.name}.kill() must be overridden`);
+  }
+
+  // ─── OPTIONAL async methods — caller awaits + try/catch ────────────
+
+  async interrupt() {
+    throw new UnsupportedOperationError('interrupt', this.backend);
+  }
+  async setModel(_model) {
+    throw new UnsupportedOperationError('setModel', this.backend);
+  }
+  async applyFlagSettings(_settings) {
+    throw new UnsupportedOperationError('applyFlagSettings', this.backend);
+  }
+  async setPermissionMode(_mode) {
+    throw new UnsupportedOperationError('setPermissionMode', this.backend);
+  }
+  async resetSession(_opts) {
+    throw new UnsupportedOperationError('resetSession', this.backend);
+  }
+  async getContextUsage() {
+    throw new UnsupportedOperationError('getContextUsage', this.backend);
+  }
+
+  // ─── OPTIONAL sync HOT-PATH methods — never throw (R1-F1) ──────────
+
+  /**
+   * Reject all pending turns with the supplied error code.
+   * Used by /stop, daemon shutdown, /new.
+   *
+   * @param {string} [_code='INTERRUPTED']
+   * @returns {number} count of pendings drained
+   */
+  drainQueue(_code = 'INTERRUPTED') {
+    return 0;
+  }
+
+  /**
+   * Inject a user message into the in-flight turn (autosteer +
+   * edit-correction). Returns false if the backend can't inject
+   * right now (e.g. no live turn) — caller falls through to normal
+   * pm.send queue path.
+   *
+   * @returns {boolean}
+   */
+  injectUserMessage(_opts) {
+    return false;
+  }
+
+  /**
+   * Push priority='now' style steer (rare; legacy of OpenClaw shape).
+   * Hot-path-safe.
+   *
+   * @returns {boolean}
+   */
+  steer(_text, _opts) {
+    return false;
+  }
+
+  /**
+   * Fire-and-forget user-message injection regardless of inFlight
+   * state. Used by polygram's slash-command paths (/compact, /reload
+   * etc) where we want to send a user-shaped message into the
+   * underlying claude session BUT NOT wait for the turn to complete.
+   *
+   * Differs from `injectUserMessage` (which is for mid-stream fold and
+   * requires inFlight on tmux) and `send` (which blocks until turn
+   * completion). Default returns false; subclasses override.
+   *
+   * @returns {boolean} true if message was queued/pasted
+   */
+  fireUserMessage(_text) {
+    return false;
+  }
+}
+
+module.exports = {
+  Process,
+  UnsupportedOperationError,
+};