Local-first 🧠memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.
TypeScript
/**
* Inbound Telegram capture core (Knowledge intake suite, t_f8f5ef6a).
*
* The update-handling core is exercised with an injected transport - no real
* network is ever touched. Every accepted text update becomes one capture
* note through the contract; every rejected, refused, or malformed update is
* one explicit logged decision (a vocabulary refusal records
* `refused-contract` and the run advances past it); `/catchup` replies with
* captures since the last acknowledged one.
*/
import { afterEach, beforeEach, expect, test } from "bun:test";
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import {
CATCHUP_COMMAND,
MissingTelegramTokenError,
handleCaptureUpdate,
requireTelegramToken,
runTelegramCapture,
type TelegramTransport,
type TelegramUpdate,
} from "../../../../src/core/brain/capture/telegram-capture.ts";
import {
listStagedCaptures,
readCatchupWatermark,
} from "../../../../src/core/brain/capture/capture-note.ts";
import { captureDecisionLogPath } from "../../../../src/core/brain/paths.ts";
import { escapeMarkdownV2 } from "../../../../src/core/discipline/telegram.ts";
import { withDeviceId } from "../../../helpers/device-id.ts";
const NOW = new Date("2026-07-19T12:00:00Z");
const ALLOW = new Set(["100"]);
let vault: string;
beforeEach(() => {
vault = mkdtempSync(join(tmpdir(), "osb-telegram-capture-"));
mkdirSync(join(vault, "Brain"), { recursive: true });
});
afterEach(() => {
rmSync(vault, { recursive: true, force: true });
});
function textUpdate(id: number, chatId: string | number, text: string): TelegramUpdate {
return { update_id: id, message: { message_id: id, text, chat: { id: chatId } } };
}
function baseOpts() {
return { allowlist: ALLOW, agent: "tester", now: () => NOW, source: "telegram" };
}
test("an allowlisted text update becomes one capture note through the contract", () => {
const res = handleCaptureUpdate(vault, textUpdate(1, "100", "an idea worth keeping"), baseOpts());
expect(res.decision.result).toBe("captured");
expect(res.decision.chatId).toBe("100");
expect(res.reply).toBeNull();
const staged = listStagedCaptures(vault);
expect(staged).toHaveLength(1);
expect(staged[0]!.body).toBe("an idea worth keeping");
expect(staged[0]!.provenance.sender).toBe("100");
});
test("a non-allowlisted chat is rejected with a decision and writes no capture", () => {
const res = handleCaptureUpdate(vault, textUpdate(2, "999", "hello"), baseOpts());
expect(res.decision.result).toBe("rejected-chat");
expect(res.reply).toBeNull();
expect(listStagedCaptures(vault)).toHaveLength(0);
});
test("a malformed update (no text) is a decision, not a throw", () => {
const res = handleCaptureUpdate(
vault,
{ update_id: 3, message: { message_id: 3, chat: { id: 100 } } },
baseOpts(),
);
expect(res.decision.result).toBe("malformed");
expect(listStagedCaptures(vault)).toHaveLength(0);
});
test("/catchup replies with captures since the last acknowledged one; watermark advances only on commit", () => {
handleCaptureUpdate(vault, textUpdate(1, "100", "first thought"), baseOpts());
handleCaptureUpdate(vault, textUpdate(2, "100", "second thought"), baseOpts());
const res = handleCaptureUpdate(vault, textUpdate(3, "100", CATCHUP_COMMAND), baseOpts());
expect(res.decision.result).toBe("catchup");
expect(res.reply).not.toBeNull();
expect(res.reply!.chatId).toBe("100");
expect(res.reply!.text).toContain("first thought");
expect(res.reply!.text).toContain("second thought");
// Rendering the reply must NOT advance the watermark: only a successful
// delivery (commit) does, so a failed send cannot lose the catchup forever.
expect(readCatchupWatermark(vault)).toBeNull();
res.reply!.commit!();
expect(readCatchupWatermark(vault)).not.toBeNull();
// A second catchup after commit reports the empty state.
const again = handleCaptureUpdate(vault, textUpdate(4, "100", CATCHUP_COMMAND), baseOpts());
expect(again.reply!.text).not.toContain("first thought");
});
test("runTelegramCapture advances the catchup watermark only after the send succeeds", async () => {
handleCaptureUpdate(vault, textUpdate(1, "100", "alpha"), baseOpts());
handleCaptureUpdate(vault, textUpdate(2, "100", "beta"), baseOpts());
expect(readCatchupWatermark(vault)).toBeNull();
// A failed send must leave the watermark unchanged.
const failing: TelegramTransport = {
getUpdates: (offset) =>
Promise.resolve(offset === 0 ? [textUpdate(3, "100", CATCHUP_COMMAND)] : []),
sendMessage: () => Promise.reject(new Error("network down")),
};
const failedRun = await runTelegramCapture(vault, {
transport: failing,
allowlist: ALLOW,
agent: "tester",
now: () => NOW,
maxCycles: 1,
});
expect(readCatchupWatermark(vault)).toBeNull();
expect(failedRun.decisions.some((d) => d.result === "transport-error")).toBe(true);
// A successful send advances it.
const okTransport: TelegramTransport = {
getUpdates: (offset) =>
Promise.resolve(offset === 0 ? [textUpdate(4, "100", CATCHUP_COMMAND)] : []),
sendMessage: () => Promise.resolve(),
};
await runTelegramCapture(vault, {
transport: okTransport,
allowlist: ALLOW,
agent: "tester",
now: () => NOW,
maxCycles: 1,
});
expect(readCatchupWatermark(vault)).not.toBeNull();
});
test("runTelegramCapture survives a transport throw, logs one decision, and keeps polling", async () => {
let call = 0;
const transport: TelegramTransport = {
getUpdates: () => {
call += 1;
if (call === 1) return Promise.reject(new Error("transient network failure"));
return Promise.resolve(call === 2 ? [textUpdate(20, "100", "after the failure")] : []);
},
sendMessage: () => Promise.resolve(),
};
const result = await runTelegramCapture(vault, {
transport,
allowlist: ALLOW,
agent: "tester",
now: () => NOW,
maxCycles: 3,
});
// The loop did not crash: it ran every cycle, logged the transport error as a
// decision, and still captured the update delivered after the failure.
expect(result.cycles).toBe(3);
expect(result.decisions.filter((d) => d.result === "transport-error")).toHaveLength(1);
const staged = listStagedCaptures(vault);
expect(staged).toHaveLength(1);
expect(staged[0]!.body).toBe("after the failure");
});
test("repeated getUpdates transport failures back off exponentially and a success resets the counter", async () => {
const slept: number[] = [];
let call = 0;
const transport: TelegramTransport = {
getUpdates: () => {
call += 1;
// Fail on calls 1-3, succeed (empty) on call 4, fail again on call 5.
if (call === 4) return Promise.resolve([]);
return Promise.reject(new Error("transport down"));
},
sendMessage: () => Promise.resolve(),
};
await runTelegramCapture(vault, {
transport,
allowlist: ALLOW,
agent: "tester",
now: () => NOW,
maxCycles: 5,
sleep: (ms) => {
slept.push(ms);
return Promise.resolve();
},
});
// Failures 1-3 double the wait (1000, 2000, 4000); the success on call 4
// records no sleep and resets the counter, so the failure on call 5 starts
// the ladder over at the base wait.
expect(slept).toEqual([1000, 2000, 4000, 1000]);
});
test("the backoff wait is capped and never grows without bound", async () => {
const slept: number[] = [];
const transport: TelegramTransport = {
getUpdates: () => Promise.reject(new Error("transport down")),
sendMessage: () => Promise.resolve(),
};
await runTelegramCapture(vault, {
transport,
allowlist: ALLOW,
agent: "tester",
now: () => NOW,
maxCycles: 8,
sleep: (ms) => {
slept.push(ms);
return Promise.resolve();
},
});
// 1000, 2000, 4000, 8000, 16000, then capped at 30000 thereafter.
expect(slept).toEqual([1000, 2000, 4000, 8000, 16000, 30000, 30000, 30000]);
});
test("a stop request during a transport backoff ends the loop promptly", async () => {
const slept: number[] = [];
let stop = false;
let calls = 0;
const transport: TelegramTransport = {
getUpdates: () => {
calls += 1;
return Promise.reject(new Error("transport down"));
},
sendMessage: () => Promise.resolve(),
};
const result = await runTelegramCapture(vault, {
transport,
allowlist: ALLOW,
agent: "tester",
now: () => NOW,
// No maxCycles: only shouldStop can end the loop, proving the backoff path
// honors a stop rather than hot-looping the API forever.
shouldStop: () => stop,
sleep: (ms) => {
slept.push(ms);
stop = true;
return Promise.resolve();
},
});
// One failed poll, one backoff, then the stop observed after the sleep ends
// the loop: no second getUpdates is issued.
expect(calls).toBe(1);
expect(result.cycles).toBe(1);
expect(slept).toEqual([1000]);
expect(result.decisions.filter((d) => d.result === "transport-error")).toHaveLength(1);
});
test("requireTelegramToken throws a typed error when the token is absent", () => {
expect(() => requireTelegramToken(null)).toThrow(MissingTelegramTokenError);
expect(requireTelegramToken("abc")).toBe("abc");
});
test("runTelegramCapture polls the injected transport, advances the offset, and sends replies", async () => {
const sent: Array<{ chatId: string; text: string }> = [];
const batches: TelegramUpdate[][] = [
[textUpdate(10, "100", "captured via poll"), textUpdate(11, "999", "blocked")],
[],
];
let call = 0;
const offsets: number[] = [];
const transport: TelegramTransport = {
getUpdates: (offset) => {
offsets.push(offset);
return Promise.resolve(batches[call++] ?? []);
},
sendMessage: (chatId, text) => {
sent.push({ chatId: String(chatId), text });
return Promise.resolve();
},
};
const result = await runTelegramCapture(vault, {
transport,
allowlist: ALLOW,
agent: "tester",
now: () => NOW,
maxCycles: 2,
});
expect(result.cycles).toBe(2);
expect(offsets[0]).toBe(0);
expect(offsets[1]).toBe(12); // last update_id 11 + 1
expect(listStagedCaptures(vault)).toHaveLength(1);
expect(result.decisions.map((d) => d.result)).toEqual(["captured", "rejected-chat"]);
// No unsolicited replies for plain captures or rejections.
expect(sent).toHaveLength(0);
});
test("every handled update writes exactly one decision to the ledger", () => {
handleCaptureUpdate(vault, textUpdate(1, "100", "keep this"), baseOpts());
handleCaptureUpdate(vault, textUpdate(2, "999", "nope"), baseOpts());
const log = readFileSync(captureDecisionLogPath(vault), "utf8").trim().split("\n");
expect(log).toHaveLength(2);
const kinds = log.map((line) => (JSON.parse(line) as { result: string }).result);
expect(kinds).toEqual(["captured", "rejected-chat"]);
expect(existsSync(captureDecisionLogPath(vault))).toBe(true);
});
test("two capture hosts append to their own decision shards (t_774dea61)", () => {
withDeviceId("a", () => handleCaptureUpdate(vault, textUpdate(1, "100", "host a"), baseOpts()));
withDeviceId("b", () => handleCaptureUpdate(vault, textUpdate(2, "200", "host b"), baseOpts()));
const logDir = join(vault, "Brain", "log");
expect(existsSync(join(logDir, "capture-decisions.a.jsonl"))).toBe(true);
expect(existsSync(join(logDir, "capture-decisions.b.jsonl"))).toBe(true);
expect(existsSync(join(logDir, "capture-decisions.jsonl"))).toBe(false);
});
// ── t_151a564c: the typed vocabulary refusal surfaces through this lane ──────
test("a pack declaring page_types without brain-capture records the refusal as a decision", () => {
// The vault made a declaration that omits the kind this lane stamps, so
// the capture contract refuses - and the refusal is one named decision
// (the same refusal message the drain lane records for an unroutable
// capture), never a throw that would kill the run before the offset
// advances. No capture is written behind it.
writeFileSync(join(vault, "Brain", "_brain.yaml"), "schema:\n page_types: [note]\n", "utf8");
const res = handleCaptureUpdate(vault, textUpdate(1, "100", "an idea worth keeping"), baseOpts());
expect(res.decision.result).toBe("refused-contract");
expect(res.decision.reason).toContain("brain-capture");
expect(res.decision.reason).toContain("declare it in Brain/_brain.yaml");
expect(res.decision.capturePath).toBeNull();
expect(listStagedCaptures(vault)).toHaveLength(0);
});
test("a contract refusal replies with the escaped remedy text", () => {
writeFileSync(join(vault, "Brain", "_brain.yaml"), "schema:\n page_types: [note]\n", "utf8");
const res = handleCaptureUpdate(vault, textUpdate(1, "100", "an idea worth keeping"), baseOpts());
expect(res.reply).not.toBeNull();
expect(res.reply!.chatId).toBe("100");
expect(res.reply!.text).toContain("capture refused");
// The reply rides the MarkdownV2 send the catchup path uses, so the
// remedy text arrives escaped, not as a failed send.
expect(res.reply!.text).toContain(escapeMarkdownV2("declare it in Brain/_brain.yaml"));
});
test("the run advances past a refused update and processes the valid one behind it", async () => {
// Regression pin (v1.78.0 review round): one refused update used to reject
// the whole poll before the offset advanced, so every restart re-fetched
// it and died on it again, blocking every later message. Here the run
// survives the refusal; once the operator declares the kind (the config
// the fake transport fixes at the batch boundary), the next update in the
// same run is captured instead of being blocked behind the refusal.
const configPath = join(vault, "Brain", "_brain.yaml");
writeFileSync(configPath, "schema:\n page_types: [note]\n", "utf8");
let call = 0;
const offsets: number[] = [];
const transport: TelegramTransport = {
getUpdates: (offset) => {
offsets.push(offset);
call += 1;
if (call === 1) return Promise.resolve([textUpdate(10, "100", "refused vocabulary")]);
// The operator declared the kind between polls; the backlog flows.
writeFileSync(configPath, "schema:\n page_types: [note, brain-capture]\n", "utf8");
return Promise.resolve([textUpdate(11, "100", "valid idea")]);
},
sendMessage: () => Promise.resolve(),
};
const result = await runTelegramCapture(vault, {
transport,
allowlist: ALLOW,
agent: "tester",
now: () => NOW,
maxCycles: 2,
});
// The refusal is recorded, not thrown, and the offset moved past BOTH
// updates so the valid one behind the refusal is captured.
expect(offsets).toEqual([0, 11]);
expect(result.lastOffset).toBe(12);
expect(result.decisions.map((d) => d.result)).toEqual(["refused-contract", "captured"]);
const refused = result.decisions[0]!;
expect(refused.updateId).toBe(10);
expect(refused.reason).toContain("brain-capture");
const staged = listStagedCaptures(vault);
expect(staged).toHaveLength(1);
expect(staged[0]!.body).toBe("valid idea");
});
test("the refusal decision lands in the decision ledger like every other", () => {
writeFileSync(join(vault, "Brain", "_brain.yaml"), "schema:\n page_types: [note]\n", "utf8");
handleCaptureUpdate(vault, textUpdate(1, "100", "an idea worth keeping"), baseOpts());
const log = readFileSync(captureDecisionLogPath(vault), "utf8").trim().split("\n");
expect(log).toHaveLength(1);
const row = JSON.parse(log[0]!) as { result: string; reason: string };
expect(row.result).toBe("refused-contract");
expect(row.reason).toContain("schema.page_types");
});