@rubytech/create-maxy-code 0.1.603 → 0.1.605

package/payload/platform/lib/telegram-store-read/src/__tests__/fold.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from "vitest";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { conversationCensus, readFoldedConversation } from "../index.js";
+
+function seed(rows: unknown[], stem = "111_222"): string {
+  const dir = mkdtempSync(join(tmpdir(), "tg-store-"));
+  writeFileSync(join(dir, `${stem}.jsonl`), rows.map((r) => JSON.stringify(r)).join("\n") + "\n");
+  return dir;
+}
+
+const msg = (over: Record<string, unknown> = {}) => ({
+  messageId: "m1",
+  sessionId: "s",
+  dateSent: "2026-08-13T17:00:00.000Z",
+  body: "hello",
+  fromMe: false,
+  senderId: "222",
+  senderName: "Mcha",
+  chatId: "222",
+  channelKey: "111:222",
+  scope: "admin",
+  origin: "inbound",
+  createdAt: "2026-08-13T17:00:00.000Z",
+  ...over,
+});
+
+describe("readFoldedConversation", () => {
+  it("returns both directions in dateSent order", () => {
+    const dir = seed([
+      msg({
+        messageId: "m2",
+        dateSent: "2026-08-13T17:01:00.000Z",
+        origin: "agent",
+        fromMe: true,
+        body: "hi back",
+      }),
+      msg(),
+    ]);
+    const out = readFoldedConversation(dir, "111:222");
+    expect(out.map((m) => m.body)).toEqual(["hello", "hi back"]);
+    expect(out.map((m) => m.origin)).toEqual(["inbound", "agent"]);
+  });
+
+  it("lets a later update row replace the body", () => {
+    const dir = seed([
+      msg({ body: "[voice note]" }),
+      { kind: "update", targetMessageId: "m1", body: "the transcript", createdAt: "x" },
+    ]);
+    expect(readFoldedConversation(dir, "111:222")[0].body).toBe("the transcript");
+  });
+
+  it("keeps deleted sticky once a later patch arrives", () => {
+    const dir = seed([
+      msg(),
+      { kind: "update", targetMessageId: "m1", deleted: true, createdAt: "x" },
+      { kind: "update", targetMessageId: "m1", attachmentIds: ["a1"], createdAt: "x" },
+    ]);
+    expect(readFoldedConversation(dir, "111:222")[0].deleted).toBe(true);
+  });
+
+  it("de-dupes attachment ids across repeated patches", () => {
+    const dir = seed([
+      msg(),
+      { kind: "update", targetMessageId: "m1", attachmentIds: ["a1"], createdAt: "x" },
+      { kind: "update", targetMessageId: "m1", attachmentIds: ["a1", "a2"], createdAt: "x" },
+    ]);
+    expect(readFoldedConversation(dir, "111:222")[0].attachmentIds).toEqual(["a1", "a2"]);
+  });
+
+  it("lets a later update row replace the buttons", () => {
+    const dir = seed([
+      msg({ buttons: [{ text: "old", data: "o" }] }),
+      { kind: "update", targetMessageId: "m1", buttons: [{ text: "new", data: "n" }], createdAt: "x" },
+    ]);
+    expect(readFoldedConversation(dir, "111:222")[0].buttons).toEqual([{ text: "new", data: "n" }]);
+  });
+
+  it("refuses an unstorable channel key rather than building a path", () => {
+    const dir = seed([msg()]);
+    expect(readFoldedConversation(dir, "../../etc:222")).toEqual([]);
+  });
+
+  it("returns nothing for a conversation with no file, without throwing", () => {
+    const dir = seed([msg()]);
+    expect(readFoldedConversation(dir, "111:999")).toEqual([]);
+  });
+
+  it("skips one corrupt line and keeps the rest", () => {
+    const dir = mkdtempSync(join(tmpdir(), "tg-store-"));
+    writeFileSync(join(dir, "111_222.jsonl"), JSON.stringify(msg()) + "\n{not json\n");
+    expect(readFoldedConversation(dir, "111:222")).toHaveLength(1);
+  });
+
+  it("reads a business conversation under its three-part key", () => {
+    const dir = seed([msg({ channelKey: "111:biz:222" })], "111_biz_222");
+    expect(readFoldedConversation(dir, "111:biz:222")).toHaveLength(1);
+  });
+});
+
+describe("conversationCensus", () => {
+  it("counts conversations and message rows, and reports the newest dateSent", () => {
+    const dir = seed([
+      msg(),
+      msg({ messageId: "m2", dateSent: "2026-08-13T17:05:00.000Z" }),
+      { kind: "update", targetMessageId: "m1", body: "patched", createdAt: "x" },
+    ]);
+    writeFileSync(join(dir, "111_333.jsonl"), JSON.stringify(msg({ chatId: "333", senderId: "333" })) + "\n");
+    const census = conversationCensus(dir);
+    expect(census.conversations).toBe(2);
+    // The update row is a patch, not a message: counting it would inflate the total.
+    expect(census.rows).toBe(3);
+    expect(census.newest).toBe("2026-08-13T17:05:00.000Z");
+  });
+
+  it("reports zeroes and a null newest for a directory that does not exist", () => {
+    expect(conversationCensus(join(tmpdir(), "tg-store-absent-xyz"))).toEqual({
+      conversations: 0,
+      rows: 0,
+      newest: null,
+    });
+  });
+});

package/payload/platform/lib/telegram-store-read/src/index.ts

@@ -0,0 +1,262 @@
+/**
+ * Task 2709 — reading one Telegram conversation back off disk, patches folded.
+ *
+ * The store is the only complete record of a Telegram conversation. No platform
+ * path writes a `:Message` node for Telegram: `persistMessage` in
+ * `ui/app/lib/neo4j-store.ts` has one caller, the webchat customer-inbound path,
+ * so a `:Message` carrying `channel:'telegram'` was written by an agent calling
+ * `memory-write` and records only what that agent chose to save. On 2026-08-13
+ * that was every inbound and one of ten outbound, and the agent read it back as
+ * the whole conversation.
+ *
+ * A message row is never rewritten once appended — `telegram-reader.ts` streams
+ * byte offsets as SSE resume ids, so a read-modify-write would invalidate every
+ * offset behind it. A correction is therefore a SECOND line, a
+ * `TelegramUpdateRecord`, naming its target. Reading the message rows alone
+ * yields the pre-patch text: a voice note's placeholder instead of its
+ * transcript, an edited message's original wording, and a withdrawn message with
+ * nothing saying it was withdrawn. Folding is what makes the read truthful,
+ * which is why this is a library and not four lines at the call site.
+ *
+ * Attachment ids come back RAW. `telegram-reader.ts` resolves each one to
+ * servable metadata against an uploads directory, because it is answering a
+ * browser; an agent has no use for that URL, and importing the uploads directory
+ * into the MCP would drag an HTTP concern across the plugin boundary. The three
+ * rules that ARE shared — body last-write-wins, buttons last-write-wins, deleted
+ * sticky-true — are pinned against the route by
+ * `ui/app/lib/telegram/__tests__/store-read-boundary.test.ts`.
+ *
+ * The key and filename rules are imported from `telegram-reach` rather than
+ * restated. That module is already the one derivation the store writer uses, and
+ * Task 2644 is the record of what a second derivation costs.
+ */
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import {
+  channelKeyToFileStem,
+  fileStemToChannelKey,
+  isStorableChannelKey,
+} from "../../telegram-reach/dist/index.js";
+
+/** One stored message with every patch that names it already applied. */
+export interface FoldedMessage {
+  messageId: string;
+  /** ISO 8601, this install's clock at write time — NOT Telegram's own second. */
+  dateSent: string;
+  /** The patched body when an update replaced it, else the row's own. */
+  body: string;
+  /** 'inbound' | 'agent' | 'operator-manual'. Kept as the string the store
+   *  holds: a reader that meets an origin this build does not know should show
+   *  it, not drop the message. */
+  origin: string;
+  fromMe: boolean;
+  senderId: string;
+  senderName: string | null;
+  /** The sender withdrew this at their end. The body is KEPT: Telegram sends
+   *  none on a deletion, so the stored body is the only account anywhere of what
+   *  was withdrawn. */
+  deleted: boolean;
+  /** Servable attachment ids in arrival order, de-duplicated. Raw ids, never
+   *  resolved metadata — see the file header. */
+  attachmentIds: string[];
+  /** A card's inline-keyboard labels. Null on an ordinary message that never
+   *  carried a keyboard; an EMPTY ARRAY when an edit removed the one it had.
+   *  The two are different facts and the distinction is the route's, kept here
+   *  so the agent and the operator cannot read one card two ways. */
+  buttons: { text: string; data: string | null }[] | null;
+}
+
+export interface ConversationCensus {
+  /** Store files in this directory holding a storable channel key. */
+  conversations: number;
+  /** Message rows across all of them. Update rows are patches, not messages, and
+   *  counting them would inflate the total. */
+  rows: number;
+  /** Newest `dateSent` anywhere in the directory, or null when empty. */
+  newest: string | null;
+}
+
+/** The fields this module reads. Declared structurally rather than imported from
+ *  `ui/app/lib/telegram/message-store.ts`: the plugin cannot import from
+ *  `platform/ui/app`, which is the same boundary `telegram-reach` sits behind. */
+interface StoreRowLike {
+  kind?: unknown;
+  messageId?: unknown;
+  targetMessageId?: unknown;
+  dateSent?: unknown;
+  body?: unknown;
+  fromMe?: unknown;
+  senderId?: unknown;
+  senderName?: unknown;
+  origin?: unknown;
+  deleted?: unknown;
+  attachmentIds?: unknown;
+  buttons?: unknown;
+}
+
+function parseLines(raw: string): StoreRowLike[] {
+  const out: StoreRowLike[] = [];
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      out.push(JSON.parse(line) as StoreRowLike);
+    } catch {
+      // A partial write from a crash mid-append is skipped, never fatal: one
+      // corrupt line must not hide every other message in the conversation.
+    }
+  }
+  return out;
+}
+
+function isUpdateRow(row: StoreRowLike): boolean {
+  return row.kind === "update";
+}
+
+function readButtons(value: unknown): { text: string; data: string | null }[] | null {
+  if (!Array.isArray(value)) return null;
+  const out: { text: string; data: string | null }[] = [];
+  for (const b of value) {
+    if (!b || typeof b !== "object") continue;
+    const { text, data } = b as { text?: unknown; data?: unknown };
+    if (typeof text !== "string") continue;
+    out.push({ text, data: typeof data === "string" ? data : null });
+  }
+  return out.length > 0 ? out : null;
+}
+
+interface Patch {
+  body?: string;
+  buttons?: { text: string; data: string | null }[];
+  deleted?: true;
+  attachmentIds: string[];
+}
+
+/** Fold every update row into one patch per target id.
+ *
+ *  Mirrors `telegram-reader.ts:77-106`. Later rows win for the body and the
+ *  buttons. Attachment ids accumulate in arrival order and are de-duplicated per
+ *  target, because two rows can legitimately name the same id: `appendMessage`
+ *  dedupes a Telegram redelivery, but the route does not read that result — it
+ *  downloads again, resolves the SAME deterministic id, and patches again.
+ *  `deleted` is sticky: a withdrawal is not undone by a later transcript or
+ *  media patch, and letting one clear it would hide the withdrawal. */
+function foldPatches(rows: StoreRowLike[]): Map<string, Patch> {
+  const out = new Map<string, Patch>();
+  for (const row of rows) {
+    if (!isUpdateRow(row)) continue;
+    if (typeof row.targetMessageId !== "string") continue;
+    const patch = out.get(row.targetMessageId) ?? { attachmentIds: [] };
+    if (Array.isArray(row.attachmentIds)) {
+      for (const id of row.attachmentIds) {
+        if (typeof id !== "string") continue;
+        if (patch.attachmentIds.includes(id)) continue;
+        patch.attachmentIds.push(id);
+      }
+    }
+    if (typeof row.body === "string") patch.body = row.body;
+    // Keyed on the field BEING an array, not on it holding anything. An operator
+    // editing a card down to no buttons produces `buttons: []`, and that is a
+    // removal: the route reads it as one, because an empty array is truthy
+    // there. Treating it as "no patch" would keep showing the agent buttons the
+    // customer can no longer see, with nothing failing while the two surfaces
+    // disagreed.
+    if (Array.isArray(row.buttons)) patch.buttons = readButtons(row.buttons) ?? [];
+    if (row.deleted === true) patch.deleted = true;
+    out.set(row.targetMessageId, patch);
+  }
+  return out;
+}
+
+function conversationFile(storeDir: string, channelKey: string): string | null {
+  // The guard, not the path. Both halves of a key are Telegram numeric ids
+  // around an optional literal `biz`, so a key that passes cannot carry a `.`,
+  // `/` or `\`, and one that fails is refused rather than sanitised into a path
+  // nobody asked for.
+  if (!isStorableChannelKey(channelKey)) return null;
+  return join(storeDir, `${channelKeyToFileStem(channelKey)}.jsonl`);
+}
+
+/**
+ * One conversation, oldest first, with every patch applied.
+ *
+ * Empty for an unstorable key, a missing directory and a conversation with no
+ * file. Those are three different facts, and none of them is an error the caller
+ * can act on differently: all three mean there is nothing stored to show.
+ */
+export function readFoldedConversation(storeDir: string, channelKey: string): FoldedMessage[] {
+  const file = conversationFile(storeDir, channelKey);
+  if (file === null || !existsSync(file)) return [];
+  let raw: string;
+  try {
+    raw = readFileSync(file, "utf8");
+  } catch {
+    return [];
+  }
+  const rows = parseLines(raw);
+  const patches = foldPatches(rows);
+  const out: FoldedMessage[] = [];
+  for (const row of rows) {
+    if (isUpdateRow(row)) continue;
+    if (typeof row.messageId !== "string") continue;
+    if (typeof row.dateSent !== "string") continue;
+    const patch = patches.get(row.messageId);
+    out.push({
+      messageId: row.messageId,
+      dateSent: row.dateSent,
+      body: patch?.body ?? (typeof row.body === "string" ? row.body : ""),
+      origin: typeof row.origin === "string" ? row.origin : "inbound",
+      fromMe: row.fromMe === true,
+      senderId: typeof row.senderId === "string" ? row.senderId : "",
+      senderName: typeof row.senderName === "string" ? row.senderName : null,
+      deleted: patch?.deleted === true,
+      attachmentIds: patch?.attachmentIds ?? [],
+      buttons: patch?.buttons ?? readButtons(row.buttons),
+    });
+  }
+  // Sort AFTER folding, so a patch that arrived before its target in file order
+  // still lands on it. Ties keep file order, which is arrival order.
+  return out.sort((a, b) => a.dateSent.localeCompare(b.dateSent));
+}
+
+/**
+ * What this account's store actually holds.
+ *
+ * `conversations` beside `rows` is load-bearing. A tool that returns nothing
+ * looks identical to a conversation that is empty, and `conversations=0
+ * rows=0` is also exactly what a reader pointed at the wrong directory prints —
+ * which is the failure Task 2644 shipped and Task 2557 named. With both numbers,
+ * a zero result on an account showing `conversations>0` is a wrong chat id, and
+ * `conversations=0` on a live account is a dead reader.
+ */
+export function conversationCensus(storeDir: string): ConversationCensus {
+  const empty: ConversationCensus = { conversations: 0, rows: 0, newest: null };
+  if (!storeDir || !existsSync(storeDir)) return empty;
+  let entries: string[];
+  try {
+    entries = readdirSync(storeDir);
+  } catch {
+    return empty;
+  }
+  let conversations = 0;
+  let rows = 0;
+  let newest: string | null = null;
+  for (const entry of entries) {
+    if (!entry.endsWith(".jsonl")) continue;
+    const channelKey = fileStemToChannelKey(entry.slice(0, -".jsonl".length));
+    if (!isStorableChannelKey(channelKey)) continue;
+    conversations += 1;
+    let raw: string;
+    try {
+      raw = readFileSync(join(storeDir, entry), "utf8");
+    } catch {
+      continue;
+    }
+    for (const row of parseLines(raw)) {
+      if (isUpdateRow(row)) continue;
+      rows += 1;
+      if (typeof row.dateSent !== "string") continue;
+      if (newest === null || newest.localeCompare(row.dateSent) < 0) newest = row.dateSent;
+    }
+  }
+  return { conversations, rows, newest };
+}

package/payload/platform/lib/telegram-store-read/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"],
+  "exclude": ["src/__tests__"]
+}

package/payload/platform/lib/telegram-store-read/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    globals: false,
+    include: ["src/__tests__/**/*.test.ts"],
+  },
+});

package/payload/platform/package.json

@@ -10,8 +10,8 @@
     "pdf-lib": "^1.17.1"
   },
   "scripts": {
-    "build": "tsc -p lib/account-schema-regions/tsconfig.json && tsc -p lib/account-ingest-token/tsconfig.json && tsc -p lib/models/tsconfig.json && tsc -p lib/agent-slug/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/mcp-lifeline/tsconfig.json && tsc -p lib/mcp-eager/tsconfig.json && tsc -p lib/account-enumeration/tsconfig.json && tsc -p lib/account-scope/tsconfig.json && tsc -p lib/shared-folder/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/ledger-core/tsconfig.json && tsc -p lib/embed-client/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/active-rules/tsconfig.json && tsc -p lib/admin-conversation-purge/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/graph-style/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && tsc -p lib/entitlement/tsconfig.json && tsc -p lib/task-secrets/tsconfig.json && tsc -p lib/admins-write/tsconfig.json && tsc -p lib/admin-access-password/tsconfig.json && tsc -p lib/persistent-components/tsconfig.json && tsc -p lib/require-port-env/tsconfig.json && tsc -p lib/aeo-llms-txt-writer/tsconfig.json && tsc -p lib/obsidian-parser/tsconfig.json && tsc -p lib/storage-broker/tsconfig.json && tsc -p lib/routine-templates/tsconfig.json && tsc -p lib/agent-dispatch-rule/tsconfig.json && tsc -p lib/canonical-instant/tsconfig.json && tsc -p lib/dispatch-read/tsconfig.json && tsc -p lib/dispatch-write/tsconfig.json && tsc -p lib/learning-constants/tsconfig.json && tsc -p lib/telegram-button-labels/tsconfig.json && tsc -p lib/telegram-media/tsconfig.json && tsc -p lib/telegram-managed-bot/tsconfig.json && tsc -p lib/telegram-reach/tsconfig.json && tsc -p services/claude-session-manager/tsconfig.json && tsc -p services/whatsapp-channel/tsconfig.json && tsc -p services/webchat-channel/tsconfig.json && tsc -p services/telegram-channel/tsconfig.json && NODE_OPTIONS='--max-old-space-size=8192' tsc -b plugins/*/mcp/tsconfig.json",
-    "build:lib": "tsc -p lib/account-schema-regions/tsconfig.json && tsc -p lib/account-ingest-token/tsconfig.json && tsc -p lib/models/tsconfig.json && tsc -p lib/agent-slug/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/mcp-lifeline/tsconfig.json && tsc -p lib/mcp-eager/tsconfig.json && tsc -p lib/account-enumeration/tsconfig.json && tsc -p lib/account-scope/tsconfig.json && tsc -p lib/shared-folder/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/ledger-core/tsconfig.json && tsc -p lib/embed-client/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/active-rules/tsconfig.json && tsc -p lib/admin-conversation-purge/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/graph-style/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && tsc -p lib/entitlement/tsconfig.json && tsc -p lib/task-secrets/tsconfig.json && tsc -p lib/admins-write/tsconfig.json && tsc -p lib/admin-access-password/tsconfig.json && tsc -p lib/persistent-components/tsconfig.json && tsc -p lib/require-port-env/tsconfig.json && tsc -p lib/aeo-llms-txt-writer/tsconfig.json && tsc -p lib/obsidian-parser/tsconfig.json && tsc -p lib/storage-broker/tsconfig.json && tsc -p lib/routine-templates/tsconfig.json && tsc -p lib/agent-dispatch-rule/tsconfig.json && tsc -p lib/shared-folder/tsconfig.json && tsc -p lib/canonical-instant/tsconfig.json && tsc -p lib/dispatch-read/tsconfig.json && tsc -p lib/dispatch-write/tsconfig.json && tsc -p lib/telegram-button-labels/tsconfig.json && tsc -p lib/telegram-media/tsconfig.json && tsc -p lib/telegram-managed-bot/tsconfig.json && tsc -p lib/telegram-reach/tsconfig.json",
+    "build": "tsc -p lib/account-schema-regions/tsconfig.json && tsc -p lib/account-ingest-token/tsconfig.json && tsc -p lib/models/tsconfig.json && tsc -p lib/agent-slug/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/mcp-lifeline/tsconfig.json && tsc -p lib/mcp-eager/tsconfig.json && tsc -p lib/account-enumeration/tsconfig.json && tsc -p lib/account-scope/tsconfig.json && tsc -p lib/shared-folder/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/ledger-core/tsconfig.json && tsc -p lib/embed-client/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/active-rules/tsconfig.json && tsc -p lib/admin-conversation-purge/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/graph-style/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && tsc -p lib/entitlement/tsconfig.json && tsc -p lib/task-secrets/tsconfig.json && tsc -p lib/admins-write/tsconfig.json && tsc -p lib/admin-access-password/tsconfig.json && tsc -p lib/persistent-components/tsconfig.json && tsc -p lib/require-port-env/tsconfig.json && tsc -p lib/aeo-llms-txt-writer/tsconfig.json && tsc -p lib/obsidian-parser/tsconfig.json && tsc -p lib/storage-broker/tsconfig.json && tsc -p lib/routine-templates/tsconfig.json && tsc -p lib/agent-dispatch-rule/tsconfig.json && tsc -p lib/canonical-instant/tsconfig.json && tsc -p lib/dispatch-read/tsconfig.json && tsc -p lib/dispatch-write/tsconfig.json && tsc -p lib/learning-constants/tsconfig.json && tsc -p lib/telegram-button-labels/tsconfig.json && tsc -p lib/telegram-media/tsconfig.json && tsc -p lib/telegram-managed-bot/tsconfig.json && tsc -p lib/telegram-reach/tsconfig.json && tsc -p lib/telegram-store-read/tsconfig.json && tsc -p services/claude-session-manager/tsconfig.json && tsc -p services/whatsapp-channel/tsconfig.json && tsc -p services/webchat-channel/tsconfig.json && tsc -p services/telegram-channel/tsconfig.json && NODE_OPTIONS='--max-old-space-size=8192' tsc -b plugins/*/mcp/tsconfig.json",
+    "build:lib": "tsc -p lib/account-schema-regions/tsconfig.json && tsc -p lib/account-ingest-token/tsconfig.json && tsc -p lib/models/tsconfig.json && tsc -p lib/agent-slug/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/mcp-lifeline/tsconfig.json && tsc -p lib/mcp-eager/tsconfig.json && tsc -p lib/account-enumeration/tsconfig.json && tsc -p lib/account-scope/tsconfig.json && tsc -p lib/shared-folder/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/ledger-core/tsconfig.json && tsc -p lib/embed-client/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/active-rules/tsconfig.json && tsc -p lib/admin-conversation-purge/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/graph-style/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && tsc -p lib/entitlement/tsconfig.json && tsc -p lib/task-secrets/tsconfig.json && tsc -p lib/admins-write/tsconfig.json && tsc -p lib/admin-access-password/tsconfig.json && tsc -p lib/persistent-components/tsconfig.json && tsc -p lib/require-port-env/tsconfig.json && tsc -p lib/aeo-llms-txt-writer/tsconfig.json && tsc -p lib/obsidian-parser/tsconfig.json && tsc -p lib/storage-broker/tsconfig.json && tsc -p lib/routine-templates/tsconfig.json && tsc -p lib/agent-dispatch-rule/tsconfig.json && tsc -p lib/shared-folder/tsconfig.json && tsc -p lib/canonical-instant/tsconfig.json && tsc -p lib/dispatch-read/tsconfig.json && tsc -p lib/dispatch-write/tsconfig.json && tsc -p lib/telegram-button-labels/tsconfig.json && tsc -p lib/telegram-media/tsconfig.json && tsc -p lib/telegram-managed-bot/tsconfig.json && tsc -p lib/telegram-reach/tsconfig.json && tsc -p lib/telegram-store-read/tsconfig.json",
     "clean:dist": "node scripts/check-orphan-dist.mjs --remove",
     "gen:canonical-tools": "node scripts/generate-canonical-tool-names.mjs",
     "build:memory": "tsc -p plugins/memory/mcp/tsconfig.json",

package/payload/platform/plugins/admin/skills/platform-architecture/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: platform-architecture
 description: Use when grounding any documented-surface claim about what Maxy ships — plugins, skills, specialists, install/deploy flows, internals. This is the install catalogue, not evidence of what is enabled on the current account. For install state on this account, call `capabilities-here`; for documented surface, cite the `Source:` URL inline.
-content-hash: sha256:2a7e28897d543df02b543552d72a457eca3956ab090a4bc5b886b487eb950d3e
+content-hash: sha256:6af2c17c66037f12d4a3172828a7db1fef57c3a15e9be8264072e9ae2ae5b362
 brand: maxy-code
 product-name: Maxy
 ---
@@ -2971,7 +2971,21 @@ A group's ID is a long negative number, like `-1001234567890`. To find it, @ment
 
 ## Message History
 
-Ask Maxy: "What messages has the bot received?" or "Show recent Telegram activity."
+Ask Maxy to read a conversation back: "What did I say to Sam on Telegram?" or "Show me the whole
+chat with that driver." It returns the conversation both ways round, oldest first: every message the bot
+received and every one it sent. A voice note reads as its transcript, an edited message as its new wording,
+and a message the other person deleted is shown struck out rather than quietly dropped.
+
+Give it the chat id, which you can get from "Who can you reach on Telegram?". In a group, the id is the
+group's own.
+
+Two things to know:
+
+- **History starts when this machine started storing it.** A conversation that predates the install, or that
+  ran while the machine was off, is not there to read. Telegram's Bot API offers no way to fetch it back.
+- **If the same chat id belongs to two conversations, it will ask which you meant** rather than guess. That
+  happens when two of your bots both talk to the same person, and when a connected business account's
+  customer has the same id as your own chat with that bot.
 
 ## Troubleshooting
 
@@ -3130,7 +3144,7 @@ The `outlook` plugin gives the admin agent access to Microsoft 365 / Outlook.com
 | `outlook-mail-attachment` | List or download any message's attachments — received or draft. With `messageId` alone, LISTS them (`id`, `name`, `contentType`, `size`, `isInline`, and a `kind` of file/item/reference) via `GET /me/messages/{id}/attachments` and `$select` (no bytes). A draft is a message in the same collection, so passing a draftId lists what that draft carries; the returned `name`/`id` is what `outlook-draft-edit`'s `removeAttachments` takes. With `messageId`+`attachmentId`, DOWNLOADS one file attachment: its bytes are written to `{accountDir}/uploads/outlook/<messageHash>/<bytesHash>-<name>` at `0o600` and the saved path is returned, ready for the Read tool, `SendUserFile`, or an `outlook-mail-reply` attachment. Only file attachments download — item/reference kinds, empty payloads, and anything over 25 MB are refused with nothing written. `outlook-mail-list` / `outlook-mail-search` / `outlook-mail-fetch-body` report `hasAttachments` so the agent knows when to call this. Needs `Mail.Read`. |
 | `outlook-mail-reply` | Reply in-thread (`createReply` / `createReplyAll` + send). Threads natively via conversationId. `replyAll`, added cc/bcc, and account-scoped file attachments (up to 25 MB per file; files over Graph's ~3 MB inline limit use a chunked upload session). Body is plain text, prepended above the quote. A reply whose recipients resolve **only** to the sending mailbox is **refused** before the send and its draft deleted: Graph addresses a reply to the original message's sender, so replying to your own sent message addresses it to yourself. An explicit `cc` does not exempt it — use `outlook-mail-send` with an explicit `to`. The resolved recipients are logged as `to=`. Needs `Mail.ReadWrite` + `Mail.Send`. |
 | `outlook-mail-delete` | Move messages to Deleted Items (`POST /me/messages/{id}/move`). Recoverable — never hard-deletes. An id already gone is counted not-moved. Needs `Mail.ReadWrite`. |
-| `outlook-mail-ingest` | Write operator-reviewed messages into the business graph as `:ConversationArchive {source:'email'}` threads (the analogue of the IMAP `email-ingest`). Input `decisions`: one `{messageId, disposition:'ingest'\|'discard'}` per listed message. Each `ingest` message's full body + envelope is fetched, threads group by Graph `conversationId`, and participants resolve closed-set against Neo4j (`:Person`/`:AdminUser` by `accountId`); an unresolved From/To/Cc address skips its whole thread and is returned to the operator (no `:Person` auto-create). Resolvable threads dispatch through the shared `conversation-archive-ingest.sh --source email`. Human-in-the-loop: nothing lands without an explicit per-message decision. The plugin's only Neo4j coupling. Needs `Mail.Read`. |
+| `outlook-mail-ingest` | Write operator-reviewed messages into the business graph as `:ConversationArchive {source:'email'}` threads (the analogue of the IMAP `email-ingest`). Input `decisions`: one `{messageId, disposition:'ingest'\|'discard'}` per listed message. Each `ingest` message's full body + envelope is fetched, threads group by Graph `conversationId`, and participants resolve closed-set against Neo4j (`:Person`/`:AdminUser` by `accountId`); an unresolved From/To/Cc address skips its whole thread and is returned to the operator (no `:Person` auto-create). Resolvable threads dispatch through the shared `conversation-archive-ingest.sh --source email`. Human-in-the-loop: nothing lands without an explicit per-message decision. One of the plugin's two Neo4j couplings; the other is the email-sampler's Outlook arm below, which writes through the same dispatcher with no operator decision at all. Needs `Mail.Read`. |
 | `outlook-mail-otp-extract` | Poll the inbox for a one-time code from a sender (domain). Reads full bodies to extract it; optional subject regex and timeout (default 60 s). |
 | `outlook-calendar-list` | Calendar events in next rangeDays days (default 7, max 365). |
 | `outlook-calendar-event` | Full detail of a single event by id. |
@@ -3167,6 +3181,20 @@ The attach call checks the access before it stores anything, so what it says bac
 
 Mail only: calendar and contacts tools refuse on a shared mailbox and say so. If a shared mailbox stops answering, the delegation was probably removed in Exchange — `outlook-mailbox-list verify:true` reports which ones are still reachable.
 
+An attached shared mailbox is also sampled into the graph on a timer, the same as a signed-in one. See the sampler section below.
+
+## Deterministic ingest into the graph
+
+Separately from `outlook-mail-ingest`, which needs an operator decision per message, the `<brand>-email-sampler.service` unit writes inbound Outlook mail into the graph on a timer with no agent turn. It samples every signed-in mailbox whose status is `ok` and every attached shared mailbox, across every account on the install, and writes `:ConversationArchive {source:'email'}` through the same dispatcher `outlook-mail-ingest` uses. Bodies are stored whole.
+
+Its cursor is the newest `receivedDateTime` written plus the ids seen at that instant, held per account in `secrets/outlook/sampler-cursors.json` (mode 0600, keyed by SMTP address). The id set is what makes a timestamp cursor safe: filtering `gt` would drop a message arriving at the same instant as the boundary, and `ge` alone would re-ingest the boundary on every cycle.
+
+A mailbox with no cursor backfills 7 days on its first pass. A brand with no `OUTLOOK_CLIENT_ID` runs no Outlook arm at all and logs one skip per cycle rather than an auth error per mailbox.
+
+Two things behave the way `outlook-mail-ingest` behaves, because it is the same dispatcher. Participants resolve closed-set, so a thread with an unknown From/To/Cc address is skipped and its mail does not land; and attachments are not archived (the sampler writes text threads only).
+
+Read it with `logs-read.sh --tail email-sampler`, filtering `provider=outlook`. A delegated mailbox's line carries `via=<delegator>`, which is what separates "the shared mailbox is quiet" from "the delegator stopped answering". Not yet proven on a live install.
+
 ## Drafting to a Contact
 
 When the admin agent drafts or sends a message to a known contact, it reads that contact's record first and applies any routing the record carries, for example a preferred send-to address, showing the result for your approval before anything is sent.
@@ -3207,6 +3235,11 @@ All log lines start with `[outlook-mcp]` and write to `server.log`, except the d
 | Mail ingest (per message) | `mail-ingest op=ingest id=<id> conversationId=<id> disposition=ingest` |
 | Mail ingest (per thread) | `mail-ingest op=thread-dispatched root=<key> messages=<N> participants=<N>` (or `op=thread-failed root=<key> status=<N> err=<msg>`; `status=null` with a non-`none` `err` is a spawn launch failure, not a script rejection) |
 | Mail ingest (summary) | `mail-ingest op=summary ingested=<N> discarded=<N> threadsDispatched=<N> threadsSkipped=<N> unresolved=<N>` — one per call; `threadsSkipped` with `unresolved>0` is the closed-set resolution refusing an unknown participant, not a failure |
+| Sampler census, per cycle | `op=sample-census provider=outlook accounts=<n> mailboxes=<n> delegated=<n> skipped=<n>` — emitted every cycle even when every count is zero, so an install with no Outlook mailbox still says so; without it, silence would be indistinguishable from the arm never running. `accounts=0` means the accounts directory resolved somewhere that does not exist |
+| Sampler, per mailbox per cycle | `op=sample mailbox=<addr> provider=outlook fetched=<n> threads=<n> skipped=<n> cursor=<iso>` — NOT in `server.log`; this arm writes to the email-sampler log, read with `logs-read.sh --tail email-sampler`. `via=<delegator>` is added on a delegated mailbox. `fetched` counts messages read, `threads` counts what actually landed in the graph, and `skipped` counts threads the closed-set participant rule refused; `fetched>0 threads=0` means nothing was written even though the cursor advanced. An idle mailbox logs `fetched=0` with no thread counts |
+| Sampler, unresolved participants | `op=sample-unresolved mailbox=<addr> provider=outlook threads=<n> addresses=<csv>` — only when a thread was refused. The addresses are what to add as `:Person` or `:AdminUser` for the account; until then that mail stays out of the graph and the cursor has already passed it |
+| Sampler failure | `op=sample-error mailbox=<addr> provider=outlook detail=<msg>` — the cursor is not advanced, so the same window is retried next cycle |
+| Sampler inert | `op=sample-skip provider=outlook detail=no-client-id` — one line per cycle on a brand with no Azure app, instead of one auth error per mailbox |
 | Calendar list | `calendar-list account=<id> rangeDays=<N> count=<N> elapsedMs=<N>` |
 | Calendar event | `calendar-event account=<id> eventId=<trunc-12> elapsedMs=<N>` |
 | Event created | `cal-create-request account=<id> subj=<trunc-64>` then `event-created account=<id> eventId=<trunc-16> status=201`. A non-201 logs `event-create-failed ... status=<N>` and throws. A 201 whose body carried no readable id logs `event-created-id-unknown account=<id> status=201` and returns a created-but-id-unknown result (the event exists; do not retry) rather than a failure. |
@@ -3290,7 +3323,7 @@ Latency triage: `mail-list count=0 elapsedMs<200` consistent → permissions iss
 
 ## Out of scope
 
-Mail move to arbitrary folders / flag, hard (permanent) delete, removing an attachment from a **sent** message (Graph forbids it), attachment-byte archival into the graph (`outlook-mail-ingest` lands text threads only; the IMAP `:DigitalDocument` archival is a separate concern), contacts write, recurring-series occurrence editing, the `scheduling` Neo4j calendar and any auto-sync with it, OneDrive / Files, push notifications, on-premises Exchange, M365 admin scopes (`User.Read.All`, `AuditLog.Read.All`), public-agent exposure, multi-tenant federation. Mail read, full-body read, inbound attachment list/download, reply, delete (to Deleted Items), and compose — all four outbound paths carrying attachments, with a draft's attachments editable in place (add, remove, replace) — are supported (`outlook-mail-fetch-body`, `outlook-mail-attachment`, `outlook-mail-reply`, `outlook-mail-delete`, `outlook-mail-ingest`, `outlook-mail-otp-extract`, `outlook-mail-send`, `outlook-draft`, `outlook-draft-edit`, `outlook-draft-send`), and the calendar is read plus control. See `platform/plugins/outlook/PLUGIN.md` for the full out-of-scope list.
+Mail move to arbitrary folders / flag, hard (permanent) delete, removing an attachment from a **sent** message (Graph forbids it), attachment-byte archival into the graph (`outlook-mail-ingest` and the email-sampler's Outlook arm both land text threads only; the IMAP `:DigitalDocument` archival is a separate concern), contacts write, recurring-series occurrence editing, the `scheduling` Neo4j calendar and any auto-sync with it, OneDrive / Files, push notifications, on-premises Exchange, M365 admin scopes (`User.Read.All`, `AuditLog.Read.All`), public-agent exposure, multi-tenant federation. Mail read, full-body read, inbound attachment list/download, reply, delete (to Deleted Items), and compose — all four outbound paths carrying attachments, with a draft's attachments editable in place (add, remove, replace) — are supported (`outlook-mail-fetch-body`, `outlook-mail-attachment`, `outlook-mail-reply`, `outlook-mail-delete`, `outlook-mail-ingest`, `outlook-mail-otp-extract`, `outlook-mail-send`, `outlook-draft`, `outlook-draft-edit`, `outlook-draft-send`), and the calendar is read plus control. See `platform/plugins/outlook/PLUGIN.md` for the full out-of-scope list.
 
 ---
 # Google Calendar
@@ -4319,9 +4352,9 @@ one, over the same automation set the routes list. The roster seed's own
 `descNull` counter is its narrow twin, scoped to seeded rows and so blind to
 exactly the operator-created ones most likely to carry no caption.
 
-**The shipped roster.** Every account starts with fourteen routines —
+**The shipped roster.** Every account starts with thirteen routines —
 `start-of-day`, `inbound-check`, `telegram-inbound-check`, `end-of-day`,
-`appointment-reminder`, `commitment-chase`, `calendar-reconcile`,
+`commitment-chase`, `calendar-reconcile`,
 `contact-reconcile`, `crm-reconcile`, `finance-reconcile`, `weekly-digest`,
 `channel-link-check`, `graph-health`, `filesystem-health`, in `/routines`
 display order. `ROUTINE_ROSTER_KEYS.length`

package/payload/platform/plugins/admin/skills/whats-new/SKILL.md

@@ -9,6 +9,17 @@ Invoked by the admin agent directly.
 
 This is the platform's release timeline, newest first. Each entry shows the date it shipped and the version it shipped in, so you can tell the operator how current their install is. To compare, read the installed version from `capabilities-here` and match it against the versions below. Keep answers high level and in plain English; this is a summary, not a full commit log.
 
+## 2026-08-14 (0.1.605)
+
+- Five more routines now check whether there is anything to do before waking the assistant. Mail triage, appointment reminders, the operational and finance reconciles, and the two health reports all previously ran on the clock and did the deciding after starting up.
+- Email kept in the graph is now pruned on a schedule, so it does not grow without limit.
+
+## 2026-08-13 (0.1.604)
+
+- Your assistant can now read a Telegram conversation back to you, both sides of it, from the record kept on your own machine. Ask for the chat with someone and you get every message they sent and every one the bot sent, in order, with a voice note shown as its transcript and a message they deleted marked as deleted.
+- The tool that was supposed to do this had never worked for anyone, on any account. Asking about a past Telegram conversation used to fall back on the handful of notes an assistant happened to save at the time, which is how a twenty-message exchange could be reported back as eleven, with only one of the bot's own replies among them.
+- An hourly check now reports any conversation notes saved that way, so the same gap cannot reopen unnoticed.
+
 ## 2026-08-13 (0.1.603)
 
 - Your Telegram assistant now knows who it is talking to. When someone's Telegram ID is saved on their contact record, every message from them arrives with their name attached, instead of the assistant seeing only a number or whatever that person's Telegram profile happens to be called.

package/payload/platform/plugins/connector/PLUGIN.md

@@ -41,11 +41,19 @@ The credential is stored in the account's secrets file and is never returned by
 
 ## Capabilities
 
-- **connector-register** — store a named API's base URL and a static credential. The credential scheme is one of bearer, api-key-header (a named header), or basic. Returns the non-secret record only.
+- **connector-register** — store a named API's base URL and a static credential, and optionally describe its changed-since queue. The credential scheme is one of bearer, api-key-header (a named header), or basic. Returns the non-secret record only.
 - **connector-call** — make a request (GET or a mutating method) to a registered connector. The credential is injected from the secret store; the request is host-bound and SSRF-guarded. Returns the status, redacted response headers, and the (size-capped) body.
 - **connector-list** — the registered connectors for this account: names and base URLs only.
 - **connector-deregister** — remove a connector and its stored credential.
 
+## The changed-since queue
+
+A registered connector may carry a `queue`, which is what lets a scheduled routine wake only when that system has actually moved. It names four things: the `kind` (`operational` or `accounting`), the `path` to read under the base URL, the `changedSinceParam` the API expects the watermark in, and the `itemsField` holding the array of changed records.
+
+The kind decides which routine watches it. The shipped operational-system reconcile gates on `operational` and the finance reconcile on `accounting`, and neither names a connector: the routine names a kind, the account names the queue. A connector registered without a queue is watched by nothing, which is visible in the listing rather than silent.
+
+The scheduling gate reads it by calling `connector-list` and then `connector-call`, so the credential and the host guard never leave this plugin. A queue whose credential is refused (401 or 403) reports no work rather than an error, so the routine no-ops instead of waking a model to rediscover a dead credential every fire. Registering an existing name again replaces its record, so omitting the queue removes it; that drop writes `op=register name=<n> queue=dropped`, because a queue lost in silence mutes whichever routine gated on it.
+
 ## Who can use it
 
 These tools are admin-driven. The operator's admin agent registers connectors and makes calls; the tools are not granted to any specialist agent, given their reach (arbitrary authenticated outbound requests and a credential store). A vertical agent that needs an external API is served by the admin acting on its behalf.

package/payload/platform/plugins/connector/mcp/dist/__tests__/queue-descriptor.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=queue-descriptor.test.d.ts.map

package/payload/platform/plugins/connector/mcp/dist/__tests__/queue-descriptor.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue-descriptor.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/queue-descriptor.test.ts"],"names":[],"mappings":""}