@cello-protocol/daemon 0.0.53 → 0.0.55

package/dist/sqlcipher-db.js

@@ -1,8 +1,8 @@
 /**
- * CELLO-M7-PERSIST-002 — the daemon's single encrypted store (DEC-1).
+ * The daemon's single encrypted store.
  *
  * The daemon DB is a SQLCipher database (whole-file AES-256 at rest). This module is the ONE
- * engine site: it loads @signalapp/sqlcipher (prebuilt — DEC-1; no compile), opens the DB with a
+ * engine site: it loads @signalapp/sqlcipher (prebuilt — never compiled from source), opens the DB with a
  * PRAGMA key, verifies the key, enables WAL, and presents a thin `DaemonDatabase` adapter so the
  * rest of the daemon (SessionNodeManager, RetryQueue, NonceDedupStore) keeps its node:sqlite-style
  * varargs call sites unchanged.
@@ -13,19 +13,18 @@
  * satisfies them too (used for in-memory test handles and for reading a legacy plaintext DB during
  * migration), and `SqlcipherDatabase` implements them by forwarding varargs as an array.
  *
- * Key custody (DEC-2/DEC-4): the SQLCipher key is a standalone random 32-byte 0600 key file beside
- * the DB. It is NOT derived from K_local (chicken-and-egg — K_local now lives inside the DB). It is
- * the single plaintext key file and replaces the old `sessions.db.transcript-key`.
+ * Key custody: the SQLCipher key is a standalone random 32-byte 0600 key file beside the DB. It is
+ * NOT derived from K_local — that is a chicken-and-egg, since K_local itself lives inside the DB. It
+ * is the ONE plaintext key file on disk.
  *
- * Fail closed (SI-002/AC-011): there is no plaintext fallback anywhere. A wrong/missing key on an
- * existing DB throws `db_encryption_key_mismatch`; the daemon never opens, creates, or migrates to a
- * plaintext store as a fallback.
+ * FAILS CLOSED: there is no plaintext fallback anywhere. A wrong/missing key on an existing DB throws
+ * `db_encryption_key_mismatch`; the daemon never opens, creates, or migrates to a plaintext store as
+ * a fallback.
  *
  * Security invariants:
- *   SI-001: the db key is NEVER logged, serialized, or placed in an error message — only the raw
- *           `PRAGMA key` string uses the hex, and that string is never logged.
- *   SI-003 (M6B-005 parity): WAL mode is enabled only AFTER key verification, so WAL files are
- *           encrypted at rest.
+ *   - The db key is NEVER logged, serialized, or placed in an error message — only the raw
+ *     `PRAGMA key` string uses the hex, and that string is never logged.
+ *   - WAL mode is enabled only AFTER key verification, so WAL files are encrypted at rest.
  */
 import { createRequire } from "node:module";
 import { existsSync, readFileSync, readSync, openSync, writeSync, fsyncSync, closeSync, renameSync, mkdirSync, unlinkSync, } from "node:fs";
@@ -79,8 +78,8 @@ class SqlcipherDatabase {
 }
 // ─── The raw SQLite magic — used to distinguish a plaintext DB from an encrypted one ──
 // A plaintext SQLite file begins with "SQLite format 3\0". A SQLCipher database encrypts the
-// header too, so its first bytes are ciphertext and never match. The migration path (PERSIST-002
-// Unit 6) uses this to detect a pre-story plaintext DB that must be migrated.
+// header too, so its first bytes are ciphertext and never match. The migration path uses this to
+// detect a legacy plaintext DB that must be migrated.
 const SQLITE_MAGIC = Buffer.concat([Buffer.from("SQLite format 3", "latin1"), Buffer.from([0x00])]);
 /** True when the file at `dbPath` exists and is an UNENCRYPTED node:sqlite database. */
 export function isPlaintextSqliteFile(dbPath) {
@@ -104,16 +103,16 @@ export function isPlaintextSqliteFile(dbPath) {
     }
     return head.equals(SQLITE_MAGIC);
 }
-// ─── Key custody (DEC-2/DEC-4) ───────────────────────────────────────────────────
+// ─── Key custody ─────────────────────────────────────────────────────────────────
 /**
  * Resolve the SQLCipher key, generating it on a genuinely fresh install only.
  *
- * Fail-closed matrix (SI-002/AC-011):
+ * Fail-closed matrix:
  *   key present                      → load it (must be 32 bytes).
  *   key absent + DB absent           → generate + persist (0600), proceed (fresh install).
  *   key absent + DB present          → THROW db_encryption_key_mismatch (never overwrite an
  *                                      existing DB with a new key — that would be data loss; and
- *                                      a pre-story PLAINTEXT DB must be migrated first, not opened).
+ *                                      a legacy PLAINTEXT DB must be migrated first, not opened).
  */
 export function resolveDbKey(dbPath, keyPath) {
     if (existsSync(keyPath)) {
@@ -137,8 +136,8 @@ export function resolveDbKey(dbPath, keyPath) {
         fsyncSync(fd);
     }
     catch (err) {
-        // Never leave a stray plaintext key fragment on disk if the write/fsync failed partway
-        // (SI-001: the only plaintext key on disk is the one sanctioned key file).
+        // Never leave a stray plaintext key fragment on disk if the write/fsync failed partway — the
+        // only plaintext key on disk is the one sanctioned key file.
         closeSync(fd);
         try {
             unlinkSync(tmp);
@@ -179,9 +178,9 @@ export function resolveDbKey(dbPath, keyPath) {
 }
 // ─── Open ────────────────────────────────────────────────────────────────────────
 /**
- * Load the SQLCipher native module. Exported because the daemon's singleton lock
- * (DOD-SINGLE-DAEMON-1) needs the same engine for its kernel-level file lock — one place that knows
- * how to load the prebuilt, and one error when it will not load.
+ * Load the SQLCipher native module. Exported because the daemon's singleton lock needs the same
+ * engine for its kernel-level file lock — one place that knows how to load the prebuilt, and one
+ * error when it will not load.
  */
 export function loadSignalModule() {
     const require = createRequire(import.meta.url);
@@ -196,7 +195,7 @@ export function loadSignalModule() {
 /**
  * Open `dbPath` as a SQLCipher database keyed by `dbKey`. Verifies the key (reads sqlite_master)
  * and enables WAL after verification. Throws DbEncryptionError on any failure — never returns a
- * plaintext handle (SI-002).
+ * plaintext handle.
  */
 export function openEncryptedDatabase(dbPath, dbKey, logger) {
     const mod = loadSignalModule();
@@ -209,9 +208,10 @@ export function openEncryptedDatabase(dbPath, dbKey, logger) {
         const reason = err instanceof Error ? err.message : String(err);
         throw new DbEncryptionError("db_open_failed", reason, `Could not open the database file at ${dbPath}.`);
     }
-    // SI-001: set the key OUTSIDE the message-bearing try below, so the key hex can never reach a
-    // thrown/logged error string even if a future SQLCipher build echoed the pragma source on error.
-    // A well-formed `key` pragma does not throw; a wrong key surfaces at the verify read instead.
+    // The key is set OUTSIDE the message-bearing try below — keep it there. The key hex must never be
+    // able to reach a thrown/logged error string, even if a future SQLCipher build echoed the pragma
+    // source on error. A well-formed `key` pragma does not throw; a wrong key surfaces at the verify
+    // read instead.
     const keyHex = Buffer.from(dbKey).toString("hex");
     inner.pragma(`key = "x'${keyHex}'"`);
     try {
@@ -225,12 +225,12 @@ export function openEncryptedDatabase(dbPath, dbKey, logger) {
         catch {
             /* ignore */
         }
-        // Deliberately do NOT echo the underlying SQLITE message into guidance verbatim — but DO log
-        // nothing here (the caller logs). SI-001: no key material in the message.
+        // Do NOT echo the underlying SQLITE message into guidance verbatim, and log nothing here (the
+        // caller logs). No key material may appear in the message.
         const reason = err instanceof Error ? err.message : String(err);
         throw new DbEncryptionError("db_encryption_key_mismatch", `database did not decrypt with the supplied key (${reason})`, "The SQLCipher key does not match this database. Restore the correct key file; the daemon will not fall back to a plaintext store.");
     }
-    // SI-003 (M6B-005 parity): WAL only AFTER key verification, so WAL/SHM files are encrypted.
+    // WAL only AFTER key verification, so WAL/SHM files are encrypted.
     try {
         const mode = inner.pragma("journal_mode=WAL", { simple: true });
         if (mode !== "wal") {
@@ -257,7 +257,7 @@ export function openEncryptedDatabaseAtPath(dbPath, keyPath) {
     const key = readFileSync(kp);
     return openEncryptedDatabase(dbPath, new Uint8Array(key));
 }
-/** The key file path the daemon uses for a given DB path (DEC-2: one plaintext key file). */
+/** The key file path the daemon uses for a given DB path — the one plaintext key file. */
 export function dbKeyPathFor(dbPath) {
     return `${dbPath}.key`;
 }

package/dist/sqlcipher-db.js.map

@@ -1 +1 @@
-{"version":3,"file":"sqlcipher-db.js","sourceRoot":"","sources":["../src/sqlcipher-db.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sqlcipher-db.js","sourceRoot":"","sources":["../src/sqlcipher-db.ts"],"names":[],"mappings":"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"}

package/dist/telegram-doorbell.d.ts

@@ -0,0 +1,38 @@
+/**
+ * M8C-TGDOOR-1: the Telegram doorbell.
+ *
+ * A daemon-owned bot pushes discrete, CONTENT-FREE events (session request / message waiting /
+ * state change) to one allowlisted operator chat. It is a convenience, never load-bearing: a
+ * network hiccup backs off and retries rather than killing the poller, and an unconfigured
+ * doorbell is INERT, not an error.
+ *
+ * Two invariants worth stating at the boundary, because the boundary is what enforces them now:
+ *
+ *   DOD-INV-CONTENTFREE — the doorbell sends a fixed label per event kind, NEVER message text.
+ *     This module cannot leak conversation content because it is never given any: its whole
+ *     dependency list is a logger, the stored settings, and a bot client.
+ *   D6 — an inbound Telegram message from ANY chat is acknowledged and dropped. Nothing from
+ *     Telegram enters a CELLO content path. Inside startDaemon that was a promise; here it is
+ *     structural — there is no session-send seam in this module to abuse.
+ */
+import { type TelegramBotClient } from "./telegram-bot-client.js";
+import type { Logger } from "./types.js";
+export interface TelegramDoorbellDeps {
+    logger: Logger;
+    /** The persisted bot token + allowlisted chat id, or null when TGDOOR was never configured. */
+    getTelegramSettings: () => {
+        botToken: string;
+        allowlistedChatId: string;
+    } | null;
+    /** Test injection. Production passes nothing and a real HttpTelegramBotClient is built per token. */
+    injectedClient?: TelegramBotClient | null;
+}
+export interface TelegramDoorbell {
+    sendTelegramDoorbell: (agentName: string, sessionId: string, kind: "session_request" | "message_waiting" | "state_change", detail: string) => Promise<void>;
+    clearTelegramRung: (agentName: string, sessionId: string) => void;
+    startTelegramPollerIfConfigured: () => void;
+    /** Shutdown: invalidate the running loop. It exits on its next generation check. */
+    stopTelegramPoller: () => void;
+}
+export declare function createTelegramDoorbell(deps: TelegramDoorbellDeps): TelegramDoorbell;
+//# sourceMappingURL=telegram-doorbell.d.ts.map

package/dist/telegram-doorbell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telegram-doorbell.d.ts","sourceRoot":"","sources":["../src/telegram-doorbell.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAyB,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACzF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,+FAA+F;IAC/F,mBAAmB,EAAE,MAAM;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAClF,qGAAqG;IACrG,cAAc,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;CAC3C;AAED,MAAM,WAAW,gBAAgB;IAC/B,oBAAoB,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,GAAG,iBAAiB,GAAG,cAAc,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5J,iBAAiB,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAClE,+BAA+B,EAAE,MAAM,IAAI,CAAC;IAC5C,oFAAoF;IACpF,kBAAkB,EAAE,MAAM,IAAI,CAAC;CAChC;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,oBAAoB,GAAG,gBAAgB,CA+HnF"}

package/dist/telegram-doorbell.js

@@ -0,0 +1,139 @@
+/**
+ * M8C-TGDOOR-1: the Telegram doorbell.
+ *
+ * A daemon-owned bot pushes discrete, CONTENT-FREE events (session request / message waiting /
+ * state change) to one allowlisted operator chat. It is a convenience, never load-bearing: a
+ * network hiccup backs off and retries rather than killing the poller, and an unconfigured
+ * doorbell is INERT, not an error.
+ *
+ * Two invariants worth stating at the boundary, because the boundary is what enforces them now:
+ *
+ *   DOD-INV-CONTENTFREE — the doorbell sends a fixed label per event kind, NEVER message text.
+ *     This module cannot leak conversation content because it is never given any: its whole
+ *     dependency list is a logger, the stored settings, and a bot client.
+ *   D6 — an inbound Telegram message from ANY chat is acknowledged and dropped. Nothing from
+ *     Telegram enters a CELLO content path. Inside startDaemon that was a promise; here it is
+ *     structural — there is no session-send seam in this module to abuse.
+ */
+import { HttpTelegramBotClient } from "./telegram-bot-client.js";
+export function createTelegramDoorbell(deps) {
+    const { logger, getTelegramSettings, injectedClient } = deps;
+    // M8C-TGDOOR-1: Telegram Mode 1 doorbell — a daemon-owned bot pushes discrete, content-free
+    // events (session request / message-waiting / state change) to one allowlisted operator chat.
+    // "NO channel machinery" (DoD) — this talks to the Telegram Bot API directly, unrelated to the
+    // claude/channel MCP capability from Tiers 1-2. Inert until telegram_settings exist.
+    let telegramBotClient = injectedClient ?? null;
+    let telegramChatId = null;
+    let telegramBotToken = null; // tracked only to detect an actual token CHANGE
+    // Generation counter, NOT a shared boolean — a boolean flip-to-false-then-true-again (e.g. a
+    // settings update that restarts the poller) would let the OLD loop's `while` condition still
+    // read true on its next check, running TWO concurrent loops. Each loop instance captures its
+    // OWN generation at start and exits the instant the counter no longer matches (a new start, or
+    // shutdown, both just bump it).
+    let telegramPollerGeneration = 0;
+    let telegramUpdateOffset = 0;
+    // Coalescing: ring once for the FIRST message-waiting event since a session was last fully
+    // read; cleared on read (cello_receive/since_seq advancing that session's watermark). Session
+    // requests and state changes bypass this Set entirely — DoD says they always ring.
+    const telegramRungUnread = new Set();
+    async function sendTelegramDoorbell(agentName, sessionId, kind, detail) {
+        if (!telegramBotClient || !telegramChatId)
+            return; // TGDOOR not configured — inert, not an error
+        if (kind === "message_waiting") {
+            const rungKey = `${agentName}:${sessionId}`;
+            if (telegramRungUnread.has(rungKey))
+                return; // already rung, still unread — coalesced
+            telegramRungUnread.add(rungKey);
+        }
+        // DOD-INV-CONTENTFREE: `detail` is a fixed, content-free label per kind — NEVER message text.
+        const text = `[${agentName} · ${sessionId.slice(0, 8)}] ${detail}`;
+        try {
+            const result = await telegramBotClient.sendMessage(telegramChatId, text);
+            if (!result.ok) {
+                logger.warn("telegram.doorbell.send.failed", { agentName, sessionId, kind, reason: result.error });
+                return;
+            }
+            logger.info("telegram.doorbell.sent", { agentName, sessionId, kind });
+        }
+        catch (err) {
+            logger.warn("telegram.doorbell.send.failed", { agentName, sessionId, kind, error: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    // Read clears the ring (DoD: "ring-once-until-read") — called wherever a receive advances a
+    // session's read watermark, mirroring AWAY-1's own dedup-clear-on-attend pattern.
+    function clearTelegramRung(agentName, sessionId) {
+        telegramRungUnread.delete(`${agentName}:${sessionId}`);
+    }
+    async function handleInboundTelegramUpdate(update, client) {
+        const chatId = update.message?.chat?.id !== undefined ? String(update.message.chat.id) : undefined;
+        if (!chatId)
+            return;
+        if (chatId !== telegramChatId) {
+            // D6: any other chat is silently dropped — nothing enters CELLO content paths.
+            logger.info("telegram.inbound.rejected", { chatId });
+            return;
+        }
+        logger.info("telegram.inbound.acknowledged", { chatId });
+        try {
+            await client.sendMessage(chatId, "CELLO doesn't process messages here — this channel only sends you notifications. Use your CELLO client to reply.");
+        }
+        catch (err) {
+            logger.warn("telegram.inbound.ack.failed", { chatId, error: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    // Single long-lived getUpdates poller (DoD) — one in-flight loop per daemon; started once
+    // settings exist, stopped on daemon shutdown. A network hiccup backs off and retries rather
+    // than killing the poller (best-effort — the doorbell is a convenience, never load-bearing).
+    // The client is a PARAMETER and must never be re-read from the shared, reassignable
+    // telegramBotClient: a settings update mid-await would otherwise let a stale response from the OLD
+    // client still be processed once (the generation check blocks the loop's NEXT iteration, not an
+    // in-flight call), and stomp telegramUpdateOffset with the OLD bot's update_id numbering, which is
+    // meaningless to a new token (Telegram scopes update_id per bot). Re-check the generation
+    // immediately after EVERY await, before acting on its result or touching shared state.
+    async function runTelegramPollerLoop(myGeneration, myClient) {
+        let myOffset = telegramUpdateOffset;
+        while (telegramPollerGeneration === myGeneration) {
+            try {
+                const updates = await myClient.getUpdates(myOffset, 25);
+                if (telegramPollerGeneration !== myGeneration)
+                    break; // superseded while awaiting — drop stale results
+                for (const u of updates) {
+                    myOffset = u.update_id + 1;
+                    telegramUpdateOffset = myOffset;
+                    if (u.message)
+                        void handleInboundTelegramUpdate(u, myClient);
+                }
+            }
+            catch (err) {
+                if (telegramPollerGeneration !== myGeneration)
+                    break; // superseded — don't retry under a dead generation
+                logger.warn("telegram.poller.error", { error: err instanceof Error ? err.message : String(err) });
+                await new Promise((r) => setTimeout(r, 2000)); // back off before retrying
+            }
+        }
+    }
+    // Always bumps the generation (invalidating any prior loop, which exits on its next check) and
+    // starts a fresh one — correct both for the first start AND a settings-change restart.
+    function startTelegramPollerIfConfigured() {
+        const settings = getTelegramSettings();
+        if (!settings)
+            return; // not configured — TGDOOR stays inert
+        // Reviewer MEDIUM fix: reset the offset on an actual token/chat CHANGE — a prior bot's
+        // update_id numbering is meaningless to a new one (Telegram scopes it per bot token).
+        if (telegramBotToken !== settings.botToken || telegramChatId !== settings.allowlistedChatId) {
+            telegramUpdateOffset = 0;
+        }
+        telegramBotToken = settings.botToken;
+        telegramChatId = settings.allowlistedChatId;
+        const client = injectedClient ?? new HttpTelegramBotClient(settings.botToken);
+        telegramBotClient = client;
+        telegramPollerGeneration += 1;
+        void runTelegramPollerLoop(telegramPollerGeneration, client);
+        logger.info("telegram.poller.started", {});
+    }
+    function stopTelegramPoller() {
+        telegramPollerGeneration += 1;
+    }
+    return { sendTelegramDoorbell, clearTelegramRung, startTelegramPollerIfConfigured, stopTelegramPoller };
+}
+//# sourceMappingURL=telegram-doorbell.js.map

package/dist/telegram-doorbell.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telegram-doorbell.js","sourceRoot":"","sources":["../src/telegram-doorbell.ts"],"names":[],"mappings":"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"}