switchroom 0.14.20 → 0.14.22

package/telegram-plugin/handoff-continuity.ts

@@ -1,206 +0,0 @@
-/**
- * Pure helpers for the session-handoff continuity line.
- *
- * On session start, the telegram plugin reads `$AGENT_DIR/.handoff-topic`
- * (written by the summarizer Stop hook). On the FIRST assistant reply
- * of the new session the plugin prepends a subtle one-liner:
- *
- *   ↩️ Picked up where we left off, <topic>
- *
- * The sidecar is consumed (read + deleted) so the line only fires once.
- * All helpers here are filesystem-only or env-only — no Telegram side
- * effects — which keeps them unit-testable in isolation.
- */
-
-import { readFileSync, unlinkSync, existsSync, writeFileSync, renameSync } from "node:fs";
-import { dirname, join } from "node:path";
-
-export const TOPIC_DISPLAY_MAX = 117;
-export const HANDOFF_TOPIC_FILENAME = ".handoff-topic";
-/**
- * Secondary sidecar written by the progress-card driver on every
- * successful turn_end. The file is overwritten each turn so it always
- * reflects the most-recent turn. Used as a fallback source for the
- * continuity line when the Stop-hook summarizer hasn't run yet (e.g.
- * crash, mid-session restart, summarizer failure). Deleted alongside
- * `.handoff-topic` in `consumeHandoffTopic`.
- */
-export const LAST_TURN_SUMMARY_FILENAME = ".last-turn-summary";
-
-export function resolveAgentDirFromEnv(): string | null {
-  const state = process.env.TELEGRAM_STATE_DIR;
-  if (!state || state.trim().length === 0) return null;
-  return dirname(state);
-}
-
-/**
- * Read the handoff topic file if present. Returns the trimmed first
- * non-empty line, truncated to TOPIC_DISPLAY_MAX with an ellipsis.
- * Missing, empty, or unreadable → null.
- */
-export function readHandoffTopic(agentDir: string): string | null {
-  const p = join(agentDir, HANDOFF_TOPIC_FILENAME);
-  if (!existsSync(p)) return null;
-  let raw: string;
-  try {
-    raw = readFileSync(p, "utf-8");
-  } catch {
-    return null;
-  }
-  const lines = raw.split(/\r?\n/).map((l) => l.trim()).filter((l) => l.length > 0);
-  if (lines.length === 0) return null;
-  let topic = lines[0];
-  if (topic.length > TOPIC_DISPLAY_MAX) {
-    topic = topic.slice(0, TOPIC_DISPLAY_MAX) + "…";
-  }
-  return topic;
-}
-
-/**
- * Read the per-turn summary file if present (written by the progress-
- * card driver on every turn_end). Returns the trimmed first non-empty
- * line, truncated like `readHandoffTopic`. The file is always
- * overwritten so it reflects the most-recent completed turn.
- */
-export function readLastTurnSummary(agentDir: string): string | null {
-  const p = join(agentDir, LAST_TURN_SUMMARY_FILENAME);
-  if (!existsSync(p)) return null;
-  let raw: string;
-  try {
-    raw = readFileSync(p, "utf-8");
-  } catch {
-    return null;
-  }
-  const lines = raw.split(/\r?\n/).map((l) => l.trim()).filter((l) => l.length > 0);
-  if (lines.length === 0) return null;
-  let topic = lines[0];
-  if (topic.length > TOPIC_DISPLAY_MAX) {
-    topic = topic.slice(0, TOPIC_DISPLAY_MAX) + "…";
-  }
-  return topic;
-}
-
-/**
- * Read + delete the topic file atomically (best-effort). A second call
- * returns null even if the first succeeded — the sidecar is one-shot.
- *
- * Fallback: if no `.handoff-topic` is present (summarizer didn't run,
- * crashed, or the session was restarted mid-loop), try the
- * `.last-turn-summary` sidecar written by the progress-card driver.
- * Both sidecars get removed on consume so the continuity line only
- * fires once per resume.
- */
-export function consumeHandoffTopic(agentDir: string): string | null {
-  const primary = readHandoffTopic(agentDir);
-  const primaryPath = join(agentDir, HANDOFF_TOPIC_FILENAME);
-  const fallbackPath = join(agentDir, LAST_TURN_SUMMARY_FILENAME);
-
-  // Always remove the per-turn summary when we consume — otherwise a
-  // later session restart would still see a stale entry even after the
-  // continuity line fired.
-  const removeFallback = (): void => {
-    try {
-      unlinkSync(fallbackPath);
-    } catch {
-      /* already gone */
-    }
-  };
-
-  if (primary !== null) {
-    try {
-      unlinkSync(primaryPath);
-    } catch {
-      /* already gone */
-    }
-    removeFallback();
-    return primary;
-  }
-
-  const fallback = readLastTurnSummary(agentDir);
-  if (fallback !== null) {
-    removeFallback();
-    return fallback;
-  }
-  return null;
-}
-
-/**
- * Atomically overwrite `.last-turn-summary` with a single-line summary.
- * Called by the progress-card driver on every turn_end. Best-effort: any
- * write failure is swallowed (logged by the caller if desired) — a
- * missing fallback file is recoverable, a half-written one is not.
- *
- * The summary is the natural plain-text signature of a completed turn:
- *   `<N tools, Ys> — <user request (truncated)>`
- * Callers should pass a pre-built line; this function handles only the
- * atomic write + first-line discipline.
- */
-export function writeLastTurnSummary(agentDir: string, summary: string): void {
-  const line = summary.split(/\r?\n/)[0]?.trim() ?? "";
-  if (line.length === 0) return;
-  const final = line.length > TOPIC_DISPLAY_MAX
-    ? line.slice(0, TOPIC_DISPLAY_MAX) + "…"
-    : line;
-  const p = join(agentDir, LAST_TURN_SUMMARY_FILENAME);
-  const tmp = `${p}.tmp-${process.pid}-${Date.now()}`;
-  try {
-    writeFileSync(tmp, final + "\n", "utf-8");
-    renameSync(tmp, p);
-  } catch {
-    /* best-effort — continuity line is purely cosmetic */
-  }
-}
-
-/**
- * Reads SWITCHROOM_HANDOFF_SHOW_LINE. Defaults to true when unset so users
- * opt out explicitly via switchroom.yaml rather than opt in.
- */
-export function shouldShowHandoffLine(): boolean {
-  const v = process.env.SWITCHROOM_HANDOFF_SHOW_LINE;
-  if (v === undefined) return true;
-  return v.toLowerCase() !== "false";
-}
-
-export type HandoffFormat = "html" | "markdownv2" | "text";
-
-/**
- * Format the continuity line for the requested outbound format. The
- * returned string already includes the trailing `\n\n` separator so the
- * caller can concatenate directly with the assistant's reply body.
- *
- * HTML: wraps in <i>…</i>. MarkdownV2: wraps in _…_ with escaping.
- * text: plain. All variants prefix the ↩️ emoji.
- */
-export function formatHandoffLine(
-  topic: string,
-  format: HandoffFormat,
-): string {
-  // Comma instead of em-dash: the framework-emitted prefix is
-  // concatenated AFTER scrubVoice runs on the model body (gateway.ts
-  // executeReply), so any em-dash here bypasses the v0.13.20 voice
-  // scrub. Replacing at the template source is one mechanical change
-  // that closes the dominant residual em-dash leak (16 of 17 dashed
-  // messages on test-harness were this template per 2026-05-24 audit).
-  const prefix = "↩️ Picked up where we left off, ";
-  if (format === "html") {
-    return `<i>${prefix}${escapeHtml(topic)}</i>\n\n`;
-  }
-  if (format === "markdownv2") {
-    const escaped = escapeMarkdownV2(topic);
-    const prefixEsc = escapeMarkdownV2(prefix);
-    return `_${prefixEsc}${escaped}_\n\n`;
-  }
-  return `${prefix}${topic}\n\n`;
-}
-
-function escapeHtml(s: string): string {
-  return s
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;");
-}
-
-const MDV2_SPECIALS = /[_*\[\]()~`>#+\-=|{}.!\\]/g;
-function escapeMarkdownV2(s: string): string {
-  return s.replace(MDV2_SPECIALS, (m) => "\\" + m);
-}

package/telegram-plugin/tests/handoff-continuity.test.ts

@@ -1,262 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
-import { mkdtempSync, rmSync, writeFileSync, existsSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import {
-  resolveAgentDirFromEnv,
-  readHandoffTopic,
-  consumeHandoffTopic,
-  shouldShowHandoffLine,
-  formatHandoffLine,
-  readLastTurnSummary,
-  writeLastTurnSummary,
-  TOPIC_DISPLAY_MAX,
-  HANDOFF_TOPIC_FILENAME,
-  LAST_TURN_SUMMARY_FILENAME,
-} from "../handoff-continuity.js";
-
-describe("resolveAgentDirFromEnv", () => {
-  const prior = process.env.TELEGRAM_STATE_DIR;
-  afterEach(() => {
-    if (prior === undefined) delete process.env.TELEGRAM_STATE_DIR;
-    else process.env.TELEGRAM_STATE_DIR = prior;
-  });
-
-  it("returns dirname of TELEGRAM_STATE_DIR", () => {
-    process.env.TELEGRAM_STATE_DIR = "/foo/bar/agent/telegram";
-    expect(resolveAgentDirFromEnv()).toBe("/foo/bar/agent");
-  });
-
-  it("returns null when env unset", () => {
-    delete process.env.TELEGRAM_STATE_DIR;
-    expect(resolveAgentDirFromEnv()).toBeNull();
-  });
-
-  it("returns null when env is empty string", () => {
-    process.env.TELEGRAM_STATE_DIR = "   ";
-    expect(resolveAgentDirFromEnv()).toBeNull();
-  });
-});
-
-describe("readHandoffTopic", () => {
-  let tmp: string;
-
-  beforeEach(() => {
-    tmp = mkdtempSync(join(tmpdir(), "handoff-topic-"));
-  });
-
-  afterEach(() => {
-    rmSync(tmp, { recursive: true, force: true });
-  });
-
-  it("returns null when the file is missing", () => {
-    expect(readHandoffTopic(tmp)).toBeNull();
-  });
-
-  it("returns null when the file is empty", () => {
-    writeFileSync(join(tmp, HANDOFF_TOPIC_FILENAME), "");
-    expect(readHandoffTopic(tmp)).toBeNull();
-  });
-
-  it("returns the trimmed single-line topic", () => {
-    writeFileSync(join(tmp, HANDOFF_TOPIC_FILENAME), "  debugging the plugin  ");
-    expect(readHandoffTopic(tmp)).toBe("debugging the plugin");
-  });
-
-  it("takes the first non-empty line when the file is multi-line", () => {
-    writeFileSync(join(tmp, HANDOFF_TOPIC_FILENAME), "\n\nfirst topic\nsecond\n");
-    expect(readHandoffTopic(tmp)).toBe("first topic");
-  });
-
-  it("truncates topics longer than the display max", () => {
-    writeFileSync(join(tmp, HANDOFF_TOPIC_FILENAME), "x".repeat(TOPIC_DISPLAY_MAX + 20));
-    const got = readHandoffTopic(tmp)!;
-    expect(got.endsWith("…")).toBe(true);
-    expect(got.length).toBe(TOPIC_DISPLAY_MAX + 1);
-  });
-});
-
-describe("consumeHandoffTopic", () => {
-  let tmp: string;
-
-  beforeEach(() => {
-    tmp = mkdtempSync(join(tmpdir(), "handoff-consume-"));
-  });
-
-  afterEach(() => {
-    rmSync(tmp, { recursive: true, force: true });
-  });
-
-  it("returns the topic and deletes the file", () => {
-    writeFileSync(join(tmp, HANDOFF_TOPIC_FILENAME), "once");
-    expect(consumeHandoffTopic(tmp)).toBe("once");
-    expect(existsSync(join(tmp, HANDOFF_TOPIC_FILENAME))).toBe(false);
-  });
-
-  it("returns null on the second call (one-shot)", () => {
-    writeFileSync(join(tmp, HANDOFF_TOPIC_FILENAME), "once");
-    expect(consumeHandoffTopic(tmp)).toBe("once");
-    expect(consumeHandoffTopic(tmp)).toBeNull();
-  });
-
-  it("returns null when the file is missing", () => {
-    expect(consumeHandoffTopic(tmp)).toBeNull();
-  });
-
-  it("falls back to .last-turn-summary when no .handoff-topic exists", () => {
-    writeFileSync(join(tmp, LAST_TURN_SUMMARY_FILENAME), "3 tools, 12s — fix the bug");
-    expect(consumeHandoffTopic(tmp)).toBe("3 tools, 12s — fix the bug");
-    // Fallback sidecar removed so a repeat call doesn't refire.
-    expect(existsSync(join(tmp, LAST_TURN_SUMMARY_FILENAME))).toBe(false);
-  });
-
-  it("prefers .handoff-topic when both files exist", () => {
-    writeFileSync(join(tmp, HANDOFF_TOPIC_FILENAME), "llm summary");
-    writeFileSync(join(tmp, LAST_TURN_SUMMARY_FILENAME), "card summary");
-    expect(consumeHandoffTopic(tmp)).toBe("llm summary");
-    // Both get removed so neither stays around to fire on a later restart.
-    expect(existsSync(join(tmp, HANDOFF_TOPIC_FILENAME))).toBe(false);
-    expect(existsSync(join(tmp, LAST_TURN_SUMMARY_FILENAME))).toBe(false);
-  });
-});
-
-describe("readLastTurnSummary", () => {
-  let tmp: string;
-
-  beforeEach(() => {
-    tmp = mkdtempSync(join(tmpdir(), "handoff-lastturn-"));
-  });
-
-  afterEach(() => {
-    rmSync(tmp, { recursive: true, force: true });
-  });
-
-  it("returns null when missing", () => {
-    expect(readLastTurnSummary(tmp)).toBeNull();
-  });
-
-  it("reads the first non-empty line", () => {
-    writeFileSync(join(tmp, LAST_TURN_SUMMARY_FILENAME), "\n5 tools, 47s — run evals\nmore\n");
-    expect(readLastTurnSummary(tmp)).toBe("5 tools, 47s — run evals");
-  });
-
-  it("truncates long summaries", () => {
-    writeFileSync(join(tmp, LAST_TURN_SUMMARY_FILENAME), "x".repeat(TOPIC_DISPLAY_MAX + 10));
-    const got = readLastTurnSummary(tmp)!;
-    expect(got.endsWith("…")).toBe(true);
-    expect(got.length).toBe(TOPIC_DISPLAY_MAX + 1);
-  });
-});
-
-describe("writeLastTurnSummary", () => {
-  let tmp: string;
-
-  beforeEach(() => {
-    tmp = mkdtempSync(join(tmpdir(), "handoff-write-"));
-  });
-
-  afterEach(() => {
-    rmSync(tmp, { recursive: true, force: true });
-  });
-
-  it("writes a round-trippable summary", () => {
-    writeLastTurnSummary(tmp, "7 tools, 02:04 — ship the progress card");
-    expect(readLastTurnSummary(tmp)).toBe("7 tools, 02:04 — ship the progress card");
-  });
-
-  it("overwrites on subsequent calls (always reflects the most-recent turn)", () => {
-    writeLastTurnSummary(tmp, "first turn");
-    writeLastTurnSummary(tmp, "second turn");
-    expect(readLastTurnSummary(tmp)).toBe("second turn");
-  });
-
-  it("writes only the first line even when input is multi-line", () => {
-    writeLastTurnSummary(tmp, "headline\nlots more context goes here\nstill more");
-    expect(readLastTurnSummary(tmp)).toBe("headline");
-  });
-
-  it("truncates over-long input at TOPIC_DISPLAY_MAX + ellipsis", () => {
-    writeLastTurnSummary(tmp, "x".repeat(TOPIC_DISPLAY_MAX + 50));
-    const got = readLastTurnSummary(tmp)!;
-    expect(got.length).toBe(TOPIC_DISPLAY_MAX + 1);
-    expect(got.endsWith("…")).toBe(true);
-  });
-
-  it("no-ops on empty / whitespace-only input (never writes an empty file)", () => {
-    writeLastTurnSummary(tmp, "   ");
-    expect(existsSync(join(tmp, LAST_TURN_SUMMARY_FILENAME))).toBe(false);
-  });
-});
-
-describe("shouldShowHandoffLine", () => {
-  const prior = process.env.SWITCHROOM_HANDOFF_SHOW_LINE;
-  afterEach(() => {
-    if (prior === undefined) delete process.env.SWITCHROOM_HANDOFF_SHOW_LINE;
-    else process.env.SWITCHROOM_HANDOFF_SHOW_LINE = prior;
-  });
-
-  it("defaults to true when unset", () => {
-    delete process.env.SWITCHROOM_HANDOFF_SHOW_LINE;
-    expect(shouldShowHandoffLine()).toBe(true);
-  });
-
-  it("returns true for 'true'", () => {
-    process.env.SWITCHROOM_HANDOFF_SHOW_LINE = "true";
-    expect(shouldShowHandoffLine()).toBe(true);
-  });
-
-  it("returns false for 'false' (case-insensitive)", () => {
-    process.env.SWITCHROOM_HANDOFF_SHOW_LINE = "FALSE";
-    expect(shouldShowHandoffLine()).toBe(false);
-  });
-
-  it("returns true for any other value (safe default)", () => {
-    process.env.SWITCHROOM_HANDOFF_SHOW_LINE = "yes";
-    expect(shouldShowHandoffLine()).toBe(true);
-  });
-});
-
-describe("formatHandoffLine", () => {
-  it("wraps the topic in italic HTML with the return emoji", () => {
-    const line = formatHandoffLine("fixing the bug", "html");
-    expect(line).toBe("<i>↩️ Picked up where we left off, fixing the bug</i>\n\n");
-  });
-
-  it("escapes HTML-unsafe chars in the topic", () => {
-    const line = formatHandoffLine("<script> & ok", "html");
-    expect(line).toContain("&lt;script&gt; &amp; ok");
-    expect(line).not.toContain("<script>");
-  });
-
-  it("produces MarkdownV2 italic with escaped specials", () => {
-    const line = formatHandoffLine("a.b (c)", "markdownv2");
-    expect(line.startsWith("_")).toBe(true);
-    expect(line.endsWith("_\n\n")).toBe(true);
-    expect(line).toContain("a\\.b");
-    expect(line).toContain("\\(c\\)");
-  });
-
-  it("produces plain text for 'text' format", () => {
-    const line = formatHandoffLine("simple", "text");
-    expect(line).toBe("↩️ Picked up where we left off, simple\n\n");
-  });
-
-  it("always ends with a blank-line separator", () => {
-    for (const fmt of ["html", "markdownv2", "text"] as const) {
-      expect(formatHandoffLine("t", fmt).endsWith("\n\n")).toBe(true);
-    }
-  });
-
-  // Regression guard: the handoff prefix was an em-dash bypass for the
-  // v0.13.20 voice scrubber (the framework prefix is concatenated AFTER
-  // scrubVoice runs in executeReply). Replacing the em-dash with a
-  // comma at the template source closes that leak. Pin it so a future
-  // operator who "fixes typography" doesn't re-introduce the dash.
-  it("does NOT contain an em-dash or en-dash in any format (voice-scrub guard)", () => {
-    for (const fmt of ["html", "markdownv2", "text"] as const) {
-      const line = formatHandoffLine("anything goes here", fmt);
-      expect(line).not.toContain("—");
-      expect(line).not.toContain("–");
-    }
-  });
-});