polygram 0.12.0-rc.8 → 0.12.0

package/lib/rewind/execute.js

@@ -0,0 +1,89 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { buildFork } = require('./fork');
+
+// claude's transcript path for a session: ~/.claude/projects/<cwd '/'→'-'>/<id>.jsonl.
+// CRITICAL (Finding A): mangle the RAW cwd, EXACTLY as cli-process.js's resume check does
+// (`resolvedCwd.replace(/\//g,'-')`, no realpath). The fork is written to this path and the
+// resume pre-check looks for it at this path — if the two diverge (one realpaths a symlinked
+// cwd, the other doesn't) the resume misses the fork and claude starts a fresh empty session:
+// a SILENT full-context wipe. Keeping both raw keeps them in lockstep; a genuinely symlinked
+// cwd then fails cleanly at the read step (transcript unreadable) instead of wiping.
+function transcriptPathFor(cwd, sessionId) {
+  return path.join(os.homedir(), '.claude', 'projects', String(cwd).replace(/\//g, '-'), `${sessionId}.jsonl`);
+}
+
+/**
+ * The 0.13 /rewind executor (P2/P3). Forks the live session transcript to before the target
+ * message, points the session at the fork (so the next message resumes the rewound
+ * conversation), kills the live proc, and deletes the bot's now-orphaned outbound messages.
+ * Copy-only + fail-safe: a fork failure leaves the original session fully intact.
+ *
+ * @param {object} deps { db, pm, tg, bot, botName, logEvent, logger, buildForkImpl }
+ * @returns {(req) => Promise<{ok:boolean,error?:string,droppedCount?:number}>}
+ */
+function createRewindExecutor({ db, pm, tg, bot, botName = 'bot', logEvent = () => {}, logger = console, buildForkImpl = buildFork } = {}) {
+  // P3: delete the bot's own outbound messages sent after M (it can always delete its own).
+  async function deleteBotMessagesAfter({ chatId, threadId, afterMsgId }) {
+    let rows;
+    try {
+      const sql = `SELECT msg_id FROM messages WHERE chat_id = ? AND direction = 'out' AND status = 'sent' AND msg_id > ?`
+        + (threadId ? ` AND thread_id = ?` : ` AND thread_id IS NULL`) + ` ORDER BY msg_id`;
+      const params = threadId ? [String(chatId), Number(afterMsgId), String(threadId)] : [String(chatId), Number(afterMsgId)];
+      rows = db.raw.prepare(sql).all(...params);
+    } catch (e) { logger.error?.(`[${botName}] rewind cleanup query failed: ${e.message}`); return 0; }
+    let deleted = 0;
+    for (const r of rows || []) {
+      try {
+        await tg(bot, 'deleteMessage', { chat_id: chatId, message_id: r.msg_id }, { source: 'rewind-cleanup', botName });
+        deleted++;
+      } catch { /* already gone / older than 48h — Telegram won't delete; skip */ }
+    }
+    return deleted;
+  }
+
+  return async function executeRewind(req) {
+    const row = db.getSession(req.sessionKey);
+    if (!row || !row.claude_session_id || !row.cwd) {
+      return { ok: false, error: 'no live session to rewind' };
+    }
+    const transcriptPath = transcriptPathFor(row.cwd, row.claude_session_id);
+    const newId = crypto.randomUUID();
+
+    const fork = buildForkImpl({ transcriptPath, targetMsgId: req.target.msg_id, newSessionId: newId });
+    if (!fork.ok) return { ok: false, error: fork.error };   // original untouched
+
+    // Point the session at the fork → the next message lazy-resumes the rewound conversation.
+    try {
+      db.upsertSession({ ...row, claude_session_id: newId });
+    } catch (e) {
+      try { fs.unlinkSync(fork.forkPath); } catch {}
+      logger.error?.(`[${botName}] rewind id-swap failed: ${e.message}`);
+      return { ok: false, error: 'failed to record the rewind' };
+    }
+    // Drop the live proc (it holds the OLD session); next inbound message respawns on the fork.
+    // A kill failure (Finding E) is NOT silent: the DB already points at the fork, but the old
+    // proc may survive holding the old id (a two-transcript split), so surface a warning rather
+    // than report a clean success the operator would trust blindly.
+    let warning;
+    try { await pm.kill(req.sessionKey, 'rewind'); }
+    catch (e) {
+      warning = 'the previous session may still be running — send a new message to confirm the rewind took';
+      logger.error?.(`[${botName}] rewind kill: ${e.message}`);
+      logEvent('rewind-kill-failed', { session_key: req.sessionKey, error: e.message });
+    }
+
+    let droppedCount = 0;
+    try { droppedCount = await deleteBotMessagesAfter({ chatId: req.chatId, threadId: req.threadId, afterMsgId: req.target.msg_id }); }
+    catch (e) { logger.error?.(`[${botName}] rewind cleanup failed: ${e.message}`); }
+
+    logEvent('rewind-executed', { session_key: req.sessionKey, new_id: newId, target_msg_id: req.target.msg_id, dropped_turns: fork.droppedTurns });
+    return { ok: true, droppedCount, ...(warning && { warning }) };
+  };
+}
+
+module.exports = { createRewindExecutor, transcriptPathFor };

package/lib/rewind/fork.js

@@ -0,0 +1,112 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Build a rewound FORK of a claude session transcript (0.13 /rewind P2; the mechanism P0.6
+ * validated). Keep the prefix up to — not including — the user turn carrying `targetMsgId`,
+ * rewrite the in-file `sessionId` to `newSessionId` on every line, and write a new
+ * `<newSessionId>.jsonl` next to the original (mode 0o600). NEVER touches the original.
+ *
+ * Fail-safe by construction — any anomaly returns `{ ok:false, error }`, never a partial/
+ * corrupt fork:
+ *   - transcript unreadable / not valid JSONL
+ *   - target not found (scrolled out OR compacted away — the locate-miss IS the compaction
+ *     guard: a target older than a compaction boundary no longer carries its msg_id wrapper)
+ *   - target is already the conversation start
+ *   - the cut point is mid-tool-call (a tool_use in the prefix without its tool_result)
+ *
+ * A clean prefix needs no `parentUuid` reconciliation — a prefix of a backward-linked chain
+ * is self-consistent (verified in the P0.6 spike).
+ *
+ * @param {object} args
+ * @param {string} args.transcriptPath
+ * @param {string|number} args.targetMsgId — TG msg_id of the user message to rewind to.
+ * @param {string} args.newSessionId
+ * @param {object} [io] { fsImpl } — inject a fake fs for tests.
+ * @returns {{ ok:true, forkPath:string, droppedTurns:number } | { ok:false, error:string }}
+ */
+function buildFork({ transcriptPath, targetMsgId, newSessionId }, { fsImpl = fs } = {}) {
+  if (!transcriptPath || !newSessionId || targetMsgId == null) {
+    return { ok: false, error: 'buildFork: transcriptPath, targetMsgId, newSessionId required' };
+  }
+  let raw;
+  try { raw = fsImpl.readFileSync(transcriptPath, 'utf8'); }
+  catch (e) { return { ok: false, error: `transcript unreadable: ${e.code || e.message}` }; }
+
+  const lines = String(raw).split('\n').filter((l) => l.trim());
+  let objs;
+  try { objs = lines.map((l) => JSON.parse(l)); }
+  catch { return { ok: false, error: 'transcript is not valid JSONL' }; }
+
+  // The channel wrapper lives in the user turn's content as a PLAIN string (the parsed value,
+  // not JSON-escaped) — search that, not JSON.stringify (which escapes the inner quotes).
+  const contentText = (o) => {
+    const c = o && o.message ? o.message.content : null;
+    if (typeof c === 'string') return c;
+    if (Array.isArray(c)) return c.map((b) => (b && b.type === 'text' ? b.text : '')).join(' ');
+    return '';
+  };
+  // Match the channel ENVELOPE's OWN msg_id — never a `<reply_to msg_id="X">` echoed inside a
+  // later turn's body (Finding B: silent-failure-hunter). In the parsed content only the outer
+  // bridge envelope keeps an unescaped `<channel …>`; the inner reply_to/telegram tags are
+  // escaped to `&lt;…&gt;`. The envelope's own closing `>` stops `[^>]*` before any embedded
+  // reply_to, so this matches the envelope whose msg_id IS the target and nothing else. Without
+  // this anchor, a target compacted away while a later turn still quotes it in reply_to would
+  // false-match the reply turn → a silent cut at the WRONG point, defeating the not-found guard.
+  const escapeRe = (s) => String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const targetRe = new RegExp(`<channel[^>]*\\bmsg_id="${escapeRe(targetMsgId)}"`);
+  const isChannelUser = (o) => o && o.type === 'user' && /<channel[^>]*\bmsg_id="/.test(contentText(o));
+  const cutIdx = objs.findIndex((o) => o && o.type === 'user' && targetRe.test(contentText(o)));
+  if (cutIdx < 0) {
+    return { ok: false, error: "couldn't find that message in the conversation (it may have scrolled out of memory)" };
+  }
+
+  const prefix = objs.slice(0, cutIdx);
+  if (!prefix.some(isChannelUser)) {
+    return { ok: false, error: "that's already the start of the conversation" };
+  }
+
+  // Clean-boundary check: no tool_use in the prefix left without its matching tool_result.
+  const openTools = new Set();
+  for (const o of prefix) {
+    const blocks = Array.isArray(o.message?.content) ? o.message.content : [];
+    for (const b of blocks) {
+      if (b && b.type === 'tool_use' && b.id) openTools.add(b.id);
+      if (b && b.type === 'tool_result' && b.tool_use_id) openTools.delete(b.tool_use_id);
+    }
+  }
+  if (openTools.size > 0) {
+    return { ok: false, error: 'that point is mid-tool-call — pick the message just before or after' };
+  }
+
+  // Rewrite sessionId on EVERY kept line (the resume id must match the filename + in-file id,
+  // else claude's ghost-session guard drops it and starts fresh = a silent full wipe).
+  const forked = prefix.map((o) => {
+    if (o && typeof o === 'object' && 'sessionId' in o) o.sessionId = newSessionId;
+    return JSON.stringify(o);
+  });
+
+  const dir = path.dirname(transcriptPath);
+  const forkPath = path.join(dir, `${newSessionId}.jsonl`);
+  // Atomic write (Finding C): a direct write to the live resume path can leave a TRUNCATED
+  // <id>.jsonl if interrupted (disk-full, crash, signal) — which claude then resumes as
+  // partial/empty context, or whose half-line trips the ghost-session guard into a full wipe.
+  // Write a temp sibling, then rename (atomic on the same fs) so the resume path only ever sees
+  // a complete file. The temp is a dotfile (won't match claude's `<sessionId>.jsonl` glob) and
+  // is cleaned on failure; a crash between write and rename leaves only a harmless orphan dot-tmp.
+  const tmpPath = path.join(dir, `.${newSessionId}.jsonl.tmp`);
+  try {
+    fsImpl.writeFileSync(tmpPath, forked.join('\n') + '\n', { mode: 0o600 });
+    fsImpl.renameSync(tmpPath, forkPath);
+  } catch (e) {
+    try { fsImpl.unlinkSync(tmpPath); } catch { /* nothing to clean */ }
+    return { ok: false, error: `couldn't write the fork: ${e.code || e.message}` };
+  }
+
+  const droppedTurns = objs.slice(cutIdx).filter(isChannelUser).length;
+  return { ok: true, forkPath, droppedTurns };
+}
+
+module.exports = { buildFork };

package/lib/rewind/rewind.js

@@ -0,0 +1,174 @@
+'use strict';
+
+/**
+ * `/rewind` command — P1 (0.13). Reply to a message with `/rewind` to rewind the
+ * conversation to just before it. P1 ships the plumbing: detect → gate (operator +
+ * message-ownership, per the 2026-06-09 security review) → defer to turn-end → confirm.
+ * The actual transcript fork is the **injected `executeRewind`** — P2 provides the real
+ * one (see docs/0.13-rewind-design.md, B-safe). P0.6 proved the fork mechanism works.
+ *
+ * Scope boundary the confirmation states out loud: a rewind reverts the CONVERSATION,
+ * not real-world side-effects (Drive files, Sheets, emails already created persist).
+ */
+
+// `/rewind` or `/rewind@botname`, alone on the line (no args).
+const REWIND_RE = /^\/rewind(?:@\w+)?\s*$/i;
+
+// Backstop for a deferred rewind whose proc emits neither 'idle' nor 'close'. Above the 30-min
+// absolute turn cap so a legitimately long in-flight turn finishes (emitting 'idle') first.
+const DEFER_TIMEOUT_MS = 31 * 60 * 1000;
+
+function isRewindCommand(text) {
+  return REWIND_RE.test(String(text || '').trim());
+}
+
+/**
+ * Validate a `/rewind` request. Returns { ok, reason }. Gate order:
+ *   1. must reply-to a message (the rewind target M)
+ *   2. the chat must be rewind-SAFE — a DM or an isolate-topics group. A shared (non-isolated)
+ *      group runs ONE session across all topics, so a rewind there would blast every topic and
+ *      user; refuse it. (Caller computes `rewindSafe`.)
+ *   3. access policy: the operator/admin is always allowed; any *paired* user is allowed ONLY
+ *      when the chat opted in with `rewindAccess: 'paired'`. Default ('operator') is operator-only
+ *      — NOT "any paired user" (the security-review degradation when operatorUserId was unset).
+ *   4. M must be the sender's OWN message or one of the bot's own bubbles — never another user's
+ *      (else an allowed user could rewind to anyone's message).
+ *
+ * @param {object} a
+ * @param {object} a.msg
+ * @param {string} a.botUsername
+ * @param {boolean} a.rewindSafe          chat is a DM OR an isolateTopics group (caller computes)
+ * @param {boolean} a.isOperatorIdentity  sender is operatorUserId or the admin user (caller computes)
+ * @param {boolean} a.paired              sender has a live pairing in this chat
+ * @param {'operator'|'paired'} [a.accessMode='operator']
+ */
+function gateRewindRequest({ msg, botUsername, rewindSafe, isOperatorIdentity, paired, accessMode = 'operator' } = {}) {
+  const reply = msg?.reply_to_message;
+  if (!reply) return { ok: false, reason: 'reply to the message you want to rewind to, then send /rewind' };
+  if (!rewindSafe) {
+    return { ok: false, reason: "rewind isn't available in a shared group chat — turn on per-topic isolation (isolateTopics) so a rewind only affects one topic, not everyone" };
+  }
+  const allowed = !!isOperatorIdentity || (accessMode === 'paired' && !!paired);
+  if (!allowed) {
+    return { ok: false, reason: accessMode === 'paired' ? 'only paired members can rewind this chat' : 'only the operator can rewind this chat' };
+  }
+  const fromId = reply.from?.id;
+  const isBotMsg = !!botUsername && reply.from?.username === botUsername;
+  const isOwnMsg = fromId != null && msg.from?.id != null && Number(fromId) === Number(msg.from.id);
+  if (!isBotMsg && !isOwnMsg) {
+    return { ok: false, reason: 'you can only rewind to your own messages or mine' };
+  }
+  return { ok: true };
+}
+
+function previewOf(text) {
+  const first = String(text || '').split('\n')[0].trim();
+  return first.length > 60 ? `${first.slice(0, 57)}…` : (first || '(no text)');
+}
+
+/**
+ * @param {object} deps
+ * @param {object} deps.pm           — ProcessManager (uses pm.get(sessionKey) + proc 'idle')
+ * @param {Function} deps.tg         — tg(bot, method, params, meta) sender
+ * @param {object} deps.bot
+ * @param {string} deps.botName
+ * @param {(req) => Promise<{ok:boolean,error?:string,droppedCount?:number}>} deps.executeRewind
+ *        — the transcript fork (P2). Injected; P1 wires a stub.
+ * @param {Function} [deps.logEvent]
+ * @param {object} [deps.logger]
+ */
+function createRewindHandler({ pm, tg, bot, botName = 'bot', executeRewind, logEvent = () => {}, logger = console } = {}) {
+  if (typeof executeRewind !== 'function') throw new TypeError('createRewindHandler: executeRewind required');
+
+  function ack(chatId, threadId, text) {
+    return tg(bot, 'sendMessage', { chat_id: chatId, text, ...(threadId && { message_thread_id: threadId }) },
+      { source: 'rewind', botName })
+      .catch((e) => logger.error?.(`[${botName}] rewind ack failed: ${e.message}`));
+  }
+
+  async function run(req) {
+    let result;
+    try {
+      result = await executeRewind(req);
+    } catch (e) {
+      logger.error?.(`[${botName}] rewind execute threw for ${req.sessionKey}: ${e.message}`);
+      result = { ok: false, error: e.message };
+    }
+    if (result && result.ok) {
+      const n = result.droppedCount;
+      await ack(req.chatId, req.threadId,
+        `⏪ Rewound to: «${previewOf(req.target.text)}»` + (n != null ? ` — ${n} message(s) dropped.` : '.') +
+        (result.warning ? `\n⚠️ ${result.warning}` : '') +
+        `\nNote: anything I already created (files, Sheets, emails) still exists — say the word to reverse it.`);
+      logEvent('rewind-done', { session_key: req.sessionKey, target_msg_id: req.target.msg_id });
+    } else {
+      await ack(req.chatId, req.threadId, `↩️ couldn't rewind — ${(result && result.error) || 'unknown error'}`);
+      logEvent('rewind-failed', { session_key: req.sessionKey, target_msg_id: req.target.msg_id, error: result && result.error });
+    }
+  }
+
+  // Defer to turn-end: a rewind kills+resumes the session, so it must never run mid-turn. If a
+  // turn is in flight, run on the proc's next 'idle'. If the proc is torn down first — 'close'
+  // or 'session-reset' (kill / LRU evict / bridge disconnect / model change), none of which
+  // emit 'idle' — tell the operator instead of leaving them hanging after the "queued" ack
+  // (Finding D). DEFER_TIMEOUT_MS backstops a proc that somehow emits neither (it sits above
+  // the 30-min absolute turn cap, so a legitimately long turn still completes first).
+  function schedule(req) {
+    const proc = pm && typeof pm.get === 'function' ? pm.get(req.sessionKey) : null;
+    if (proc && proc.inFlight) {
+      let settled = false;
+      const cleanup = () => {
+        clearTimeout(timer);
+        proc.removeListener('idle', onIdle);
+        proc.removeListener('close', onDead);
+        proc.removeListener('session-reset', onDead);
+      };
+      const onIdle = () => { if (settled) return; settled = true; cleanup(); run(req).catch(() => {}); };
+      const onDead = () => {
+        if (settled) return; settled = true; cleanup();
+        ack(req.chatId, req.threadId, "↩️ couldn't rewind — the session ended before the turn finished. Reply /rewind again.");
+        logEvent('rewind-deferred-lost', { session_key: req.sessionKey, target_msg_id: req.target.msg_id });
+      };
+      const timer = setTimeout(() => {
+        if (settled) return; settled = true; cleanup();
+        ack(req.chatId, req.threadId, "↩️ couldn't rewind — timed out waiting for the current turn to finish. Reply /rewind again.");
+        logEvent('rewind-deferred-timeout', { session_key: req.sessionKey, target_msg_id: req.target.msg_id });
+      }, DEFER_TIMEOUT_MS);
+      if (timer.unref) timer.unref();
+      proc.once('idle', onIdle);
+      proc.once('close', onDead);
+      proc.once('session-reset', onDead);
+      return 'deferred';
+    }
+    setImmediate(() => { run(req).catch(() => {}); });
+    return 'now';
+  }
+
+  /**
+   * Dispatcher hook. Returns { consumed }. Consumes any `/rewind` (valid → queued, invalid →
+   * the operator is told why) so it never starts a normal turn.
+   */
+  async function tryConsume({ sessionKey, chatId, threadId = null, msg, cleanText, botUsername, rewindSafe, isOperatorIdentity, paired, accessMode }) {
+    if (!isRewindCommand(cleanText)) return { consumed: false };
+    const gate = gateRewindRequest({ msg, botUsername, rewindSafe, isOperatorIdentity, paired, accessMode });
+    if (!gate.ok) {
+      await ack(chatId, threadId, `↩️ ${gate.reason}`);
+      return { consumed: true };
+    }
+    const reply = msg.reply_to_message;
+    const req = {
+      sessionKey, chatId, threadId,
+      target: { msg_id: reply.message_id, text: reply.text || reply.caption || '', ts: reply.date },
+    };
+    const when = schedule(req);
+    await ack(chatId, threadId, when === 'deferred'
+      ? '⏳ Rewind queued — I’ll run it the moment the current turn finishes.'
+      : '⏪ Rewinding…');
+    logEvent('rewind-requested', { session_key: sessionKey, target_msg_id: req.target.msg_id, when });
+    return { consumed: true };
+  }
+
+  return { tryConsume };
+}
+
+module.exports = { isRewindCommand, gateRewindRequest, previewOf, createRewindHandler };