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).
*
* A long-poll `getUpdates` bot that turns pocket messages into staged
* captures through the seam-1 capture-note contract. The transport is an
* injected interface so the update-handling core is unit-testable with no
* network; the real transport ({@link createFetchTelegramTransport}) is a
* thin `fetch` wrapper built only by the CLI runner verb, never by a hook.
*
* Design invariants:
* - every accepted text update becomes exactly one capture note;
* - every rejected, refused, or malformed update is one explicit logged
* decision - never a silent drop, and never a crash that stops the run
* before the offset advances past it (a contract refusal records
* `refused-contract` and the loop continues with the next update);
* - `/catchup` replies with captures since the last acknowledged one,
* using the existing MarkdownV2 escaping;
* - a missing bot token is a typed error at startup, surfaced by
* {@link requireTelegramToken};
* - nothing runs implicitly - the loop only turns when a caller invokes
* {@link runTelegramCapture}.
*/
import { appendFileSync, mkdirSync } from "node:fs";
import { dirname } from "node:path";
import { escapeMarkdownV2 } from "../../discipline/telegram.ts";
import { isoSecond } from "../time.ts";
import { CAPTURE_DECISION_LEDGER_STEM, captureDecisionLogPath } from "../paths.ts";
import { ledgerRowRecord } from "../../store/dual-write-records.ts";
import { rowNamesPrivatePage } from "../../store/reference-privacy.ts";
import { isStoreOnly } from "../../store/store-only.ts";
import { storeWrite } from "../../store/store-write.ts";
import {
CaptureContractError,
capturesSince,
readCatchupWatermark,
writeCaptureNote,
writeCatchupWatermark,
type CaptureNote,
} from "./capture-note.ts";
import { assertVaultIdentityForWrite } from "../vault-identity.ts";
/** Telegram command that triggers a catchup reply. */
export const CATCHUP_COMMAND = "/catchup";
/** Default capture channel label stamped into provenance. */
export const TELEGRAM_CAPTURE_SOURCE = "telegram";
/** Telegram Bot API host. Kept as a named constant, never logged with a token. */
const TELEGRAM_API_BASE = "https://api.telegram.org";
/** Long-poll timeout (seconds) passed to getUpdates. */
const LONG_POLL_TIMEOUT_SECONDS = 30;
/**
* Margin (seconds) added to the long-poll window before the client-side fetch
* aborts, so a wedged connection surfaces as a caught, retried transport error
* rather than a hang that stalls the runner forever.
*/
const FETCH_TIMEOUT_MARGIN_SECONDS = 10;
/** Client-side abort timeout (seconds) for the short sendMessage request. */
const SEND_MESSAGE_TIMEOUT_SECONDS = 15;
/**
* Base wait (ms) before retrying getUpdates after the first consecutive
* transport failure. Each further consecutive failure doubles the wait.
*/
const TRANSPORT_BACKOFF_BASE_MS = 1000;
/**
* Ceiling (ms) for the exponential getUpdates retry backoff. Without a cap a
* long outage would push the wait unbounded; with it the loop settles into a
* steady, gentle retry cadence instead of hammering the API or pinning CPU.
*/
const TRANSPORT_BACKOFF_MAX_MS = 30_000;
/** Real timer sleep, used when no {@link RunTelegramCaptureOptions.sleep} is injected. */
function defaultSleep(ms: number): Promise<void> {
return new Promise((resolve) => setTimeout(resolve, ms));
}
/**
* Exponential backoff for `consecutiveFailures` (1-based): base doubled per
* failure, capped at {@link TRANSPORT_BACKOFF_MAX_MS}.
*/
function transportBackoffMs(consecutiveFailures: number): number {
const raw = TRANSPORT_BACKOFF_BASE_MS * 2 ** (consecutiveFailures - 1);
return Math.min(raw, TRANSPORT_BACKOFF_MAX_MS);
}
/** Minimal shape of the Telegram update objects this bot reads. */
export interface TelegramUpdate {
readonly update_id: number;
readonly message?: {
readonly message_id?: number;
readonly text?: string;
readonly chat?: { readonly id: number | string };
};
}
/** Transport seam: the two Telegram Bot API calls the bot needs. */
export interface TelegramTransport {
getUpdates(offset: number): Promise<TelegramUpdate[]>;
sendMessage(chatId: string | number, text: string): Promise<void>;
}
export type CaptureDecisionResult =
| "captured"
| "catchup"
| "rejected-chat"
| "refused-contract"
| "malformed"
| "transport-error";
export interface CaptureDecision {
readonly updateId: number;
readonly result: CaptureDecisionResult;
readonly reason: string;
readonly chatId: string | null;
/** Vault-relative path of the capture written, when `result` is captured. */
readonly capturePath: string | null;
readonly at: string;
}
export interface HandleUpdateResult {
readonly decision: CaptureDecision;
/** A reply to send back, or null when the update warrants no reply. */
readonly reply: {
readonly chatId: string;
readonly text: string;
/**
* Deferred side effect to run only once delivery has succeeded (the bot
* path advances the catchup watermark here). Absent when the reply carries
* no post-delivery commit.
*/
readonly commit?: () => void;
} | null;
}
/** A rendered catchup reply plus the deferred watermark advance. */
export interface CatchupReply {
/** The MarkdownV2-escaped reply text. */
readonly text: string;
/**
* Advance the watermark to the newest capture included in `text`. Split from
* rendering so a caller whose delivery can fail (the bot's sendMessage) only
* commits after a successful send; a caller whose rendering IS delivery (the
* CLI writing to stdout) commits immediately.
*/
readonly commit: () => void;
}
export interface HandleUpdateOptions {
/** Allowlisted chat ids (as strings). An empty set accepts nothing. */
readonly allowlist: ReadonlySet<string>;
readonly agent: string;
/** Injected clock so captures are deterministic in tests. */
readonly now: () => Date;
/** Capture channel label; defaults to {@link TELEGRAM_CAPTURE_SOURCE}. */
readonly source?: string;
}
/** Typed startup error raised when no bot token is configured. */
export class MissingTelegramTokenError extends Error {
constructor() {
super(
"no Telegram bot token configured; set TELEGRAM_BOT_TOKEN or telegram_bot_token in the config",
);
this.name = "MissingTelegramTokenError";
}
}
/** Return the token or raise {@link MissingTelegramTokenError} - never a silent no-op. */
export function requireTelegramToken(token: string | null): string {
if (token === null || token.trim().length === 0) {
throw new MissingTelegramTokenError();
}
return token;
}
/** The store ledger of capture decisions (FORMAT.md, the migration's ledgers). */
export const CAPTURE_DECISIONS_LEDGER = CAPTURE_DECISION_LEDGER_STEM;
function appendDecision(vault: string, decision: CaptureDecision): void {
// One `capture-decisions` ledger row on a store-only machine (design D14
// item 1); an unswitched machine keeps its decision shard, with no dual
// write (format version 1 has none for this ledger; the migration
// imports the shard). A decision names a chat and the capture page it
// wrote: `private` when that page is private or cannot be judged, else
// `private-when-held` (private when this machine holds it).
if (isStoreOnly({ vault })) {
storeWrite(
() =>
ledgerRowRecord(
CAPTURE_DECISIONS_LEDGER,
decision,
rowNamesPrivatePage(vault, decision) ? "private" : "private-when-held",
),
{ vault },
);
return;
}
const path = captureDecisionLogPath(vault);
mkdirSync(dirname(path), { recursive: true });
appendFileSync(path, `${JSON.stringify(decision)}\n`, { encoding: "utf8" });
}
function messageOf(err: unknown): string {
return err instanceof Error ? err.message : String(err);
}
/**
* Record one `transport-error` decision (getUpdates / sendMessage failure) so a
* transient network fault is a logged, greppable decision rather than a crash
* that terminates the runner. Returns the decision for the in-memory list too.
*/
function logTransportError(
vault: string,
updateId: number,
chatId: string | null,
reason: string,
now: () => Date,
): CaptureDecision {
const decision: CaptureDecision = {
updateId,
result: "transport-error",
reason,
chatId,
capturePath: null,
at: isoSecond(now()),
};
appendDecision(vault, decision);
return decision;
}
/**
* Render the catchup reply for the captures since the last acknowledged one.
* Rendering NEVER advances the watermark; the returned {@link CatchupReply.commit}
* does that, so a failed delivery cannot silently drop the catchup forever.
*/
export function renderCatchup(vault: string): CatchupReply {
const watermark = readCatchupWatermark(vault);
const pending = capturesSince(vault, watermark);
if (pending.length === 0) {
return { text: escapeMarkdownV2("No new captures since the last catchup."), commit: () => {} };
}
const header = escapeMarkdownV2(`${pending.length} capture(s) since the last catchup:`);
const lines = pending.map((c) => `- ${escapeMarkdownV2(catchupLine(c))}`);
const newest = pending[pending.length - 1]!;
return {
text: [header, ...lines].join("\n"),
commit: () => writeCatchupWatermark(vault, newest.id),
};
}
function catchupLine(capture: CaptureNote): string {
return `${capture.provenance.capturedAt}: ${capture.body}`;
}
/**
* Handle one inbound update: capture it, reject it, or answer `/catchup`.
* Always writes exactly one decision to the ledger and never throws on a
* malformed or disallowed update - those are decisions, not crashes.
*/
export function handleCaptureUpdate(
vault: string,
update: TelegramUpdate,
opts: HandleUpdateOptions,
): HandleUpdateResult {
// Vault-identity write guard (context-integrity-gates, Unit J).
assertVaultIdentityForWrite(vault);
const now = opts.now();
const at = isoSecond(now);
const updateId = typeof update.update_id === "number" ? update.update_id : -1;
const source = opts.source ?? TELEGRAM_CAPTURE_SOURCE;
const chatRaw = update.message?.chat?.id;
const text = update.message?.text;
const finish = (
result: CaptureDecisionResult,
reason: string,
chatId: string | null,
capturePath: string | null,
reply: { chatId: string; text: string; commit?: () => void } | null,
): HandleUpdateResult => {
const decision: CaptureDecision = { updateId, result, reason, chatId, capturePath, at };
appendDecision(vault, decision);
return { decision, reply };
};
if (chatRaw === undefined || chatRaw === null) {
return finish("malformed", "update has no chat id", null, null, null);
}
const chatId = String(chatRaw);
if (!opts.allowlist.has(chatId)) {
return finish("rejected-chat", "chat id not in allowlist", chatId, null, null);
}
if (typeof text !== "string" || text.trim().length === 0) {
return finish("malformed", "update has no text body", chatId, null, null);
}
const trimmed = text.trim();
if (trimmed === CATCHUP_COMMAND) {
const catchup = renderCatchup(vault);
// The watermark advances via catchup.commit, invoked by the run loop only
// after sendMessage succeeds - a failed send must not lose the catchup.
return finish("catchup", "catchup requested", chatId, null, {
chatId,
text: catchup.text,
commit: catchup.commit,
});
}
// No `guidance` here, and that is a reading of the payload rather than
// an omission: a Telegram update carries a chat id and one text body,
// and nothing in it distinguishes what was captured from what should be
// done with it. Splitting a message on a convention this bot invented
// would put words in the sender's mouth. Guidance reaches the contract
// from surfaces that have a field for it - see `o2b brain capture`.
//
// A contract refusal (an undeclared capture kind, today) is one named
// decision, not a crash - the same refusal message the drain lane
// records for an unroutable capture. Letting it throw would reject the
// whole poll before the offset advanced, so every restart would
// re-fetch the refused update and die on it again, blocking every
// later message behind it. The reply names the remedy, escaped for the
// MarkdownV2 send the catchup path already uses.
try {
const note = writeCaptureNote(vault, {
body: trimmed,
provenance: { source, sender: chatId, capturedAt: at },
});
return finish("captured", "text captured", chatId, note.path, null);
} catch (err) {
if (!(err instanceof CaptureContractError)) throw err;
return finish("refused-contract", err.message, chatId, null, {
chatId,
text: escapeMarkdownV2(`capture refused: ${err.message}`),
});
}
}
export interface RunTelegramCaptureOptions {
readonly transport: TelegramTransport;
readonly allowlist: ReadonlySet<string>;
readonly agent: string;
readonly now: () => Date;
readonly source?: string;
/**
* Hard cap on poll cycles. Bounds the loop for tests and cron-style
* single-shot runs; when unset the loop runs until {@link shouldStop}.
*/
readonly maxCycles?: number;
/** Cooperative shutdown signal, checked at the top of each cycle. */
readonly shouldStop?: () => boolean;
/**
* Injected sleep, awaited to back off between repeated getUpdates transport
* failures. Defaults to a real timer ({@link defaultSleep}); tests pass a
* recorder so the growing waits are asserted without spending wall-clock time.
*/
readonly sleep?: (ms: number) => Promise<void>;
}
export interface RunTelegramCaptureResult {
readonly cycles: number;
readonly decisions: readonly CaptureDecision[];
readonly lastOffset: number;
}
/**
* Long-poll loop over the injected transport. Each cycle fetches updates
* from the running offset, handles each through {@link handleCaptureUpdate},
* sends any reply, and advances the offset past the highest update_id seen.
*/
export async function runTelegramCapture(
vault: string,
opts: RunTelegramCaptureOptions,
): Promise<RunTelegramCaptureResult> {
const decisions: CaptureDecision[] = [];
let offset = 0;
let cycles = 0;
let consecutiveFailures = 0;
const sleep = opts.sleep ?? defaultSleep;
const handleOpts: HandleUpdateOptions = {
allowlist: opts.allowlist,
agent: opts.agent,
now: opts.now,
...(opts.source !== undefined ? { source: opts.source } : {}),
};
while (opts.maxCycles === undefined || cycles < opts.maxCycles) {
if (opts.shouldStop?.() === true) break;
cycles += 1;
// A long-poll loop is inherently sequential: each getUpdates uses the
// offset produced by the previous cycle, so the awaits cannot be
// parallelized.
let updates: TelegramUpdate[];
try {
// oxlint-disable-next-line no-await-in-loop
updates = await opts.transport.getUpdates(offset);
// A clean poll clears the failure streak so the next outage restarts the
// backoff ladder from the base wait rather than an inflated one.
consecutiveFailures = 0;
} catch (err) {
// A transient transport failure is one logged decision, not a crash: the
// loop retries on the next cycle. Typed startup errors (missing token)
// are raised before the loop and stay fatal. Before retrying we wait out
// an exponential backoff so a persistent outage (bad token, DNS failure,
// API downtime) settles into a gentle retry cadence instead of a hot loop
// that hammers the API and pins the CPU, which matters because production
// runs with no maxCycles.
consecutiveFailures += 1;
decisions.push(
logTransportError(vault, -1, null, `getUpdates failed: ${messageOf(err)}`, opts.now),
);
// oxlint-disable-next-line no-await-in-loop
await sleep(transportBackoffMs(consecutiveFailures));
// A stop requested during the backoff ends the loop promptly rather than
// issuing another getUpdates, so shutdown never waits on a full retry.
if (opts.shouldStop?.() === true) break;
continue;
}
for (const update of updates) {
const { decision, reply } = handleCaptureUpdate(vault, update, handleOpts);
decisions.push(decision);
if (reply !== null) {
try {
// oxlint-disable-next-line no-await-in-loop
await opts.transport.sendMessage(reply.chatId, reply.text);
// Commit deferred side effects (the catchup watermark) ONLY after a
// successful send, so a failed delivery never loses the catchup.
reply.commit?.();
} catch (err) {
decisions.push(
logTransportError(
vault,
decision.updateId,
reply.chatId,
`sendMessage failed: ${messageOf(err)}`,
opts.now,
),
);
}
}
if (typeof update.update_id === "number") {
offset = Math.max(offset, update.update_id + 1);
}
}
}
return { cycles, decisions, lastOffset: offset };
}
/**
* Build the real fetch-based transport. Used only by the CLI runner verb;
* never constructed in tests, so no test path ever reaches the network. The
* token travels only in the request URL path (never logged) per the Bot API.
*/
export function createFetchTelegramTransport(token: string): TelegramTransport {
const base = `${TELEGRAM_API_BASE}/bot${token}`;
return {
async getUpdates(offset: number): Promise<TelegramUpdate[]> {
const url = `${base}/getUpdates?offset=${offset}&timeout=${LONG_POLL_TIMEOUT_SECONDS}`;
const res = await fetch(url, {
signal: AbortSignal.timeout(
(LONG_POLL_TIMEOUT_SECONDS + FETCH_TIMEOUT_MARGIN_SECONDS) * 1000,
),
});
if (!res.ok) {
throw new Error(`Telegram getUpdates failed with HTTP ${res.status}`);
}
const body = (await res.json()) as { ok?: boolean; result?: TelegramUpdate[] };
if (body.ok !== true || !Array.isArray(body.result)) {
throw new Error("Telegram getUpdates returned a non-ok payload");
}
return body.result;
},
async sendMessage(chatId: string | number, text: string): Promise<void> {
const res = await fetch(`${base}/sendMessage`, {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ chat_id: chatId, text, parse_mode: "MarkdownV2" }),
signal: AbortSignal.timeout(SEND_MESSAGE_TIMEOUT_SECONDS * 1000),
});
if (!res.ok) {
throw new Error(`Telegram sendMessage failed with HTTP ${res.status}`);
}
},
};
}