talon-agent 4.3.0 → 4.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "4.3.0",
+  "version": "4.3.1",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",

package/src/bootstrap.ts

@@ -568,9 +568,12 @@ export async function initBackendAndDispatcher(
     const { crossSendHandlers } =
       await import("./core/engine/gateway-actions/cross-send.js");
     void deliverPendingProvisionReport(async (frontend, target, text) => {
+      // Chat-free: the same "no chat" sentinels handleChatFreeAction passes.
       const result = await crossSendHandlers.send_via(
         { frontend, target, text },
         0,
+        undefined,
+        "0",
       );
       return Boolean(result && (result as { ok?: unknown }).ok === true);
     });

package/src/core/background/cron.ts

@@ -34,6 +34,7 @@ import {
 } from "../../storage/cron-store.js";
 import { appendDailyLog } from "../../storage/daily-log.js";
 import { log, logError, logWarn } from "../../util/log.js";
+import { numericChatIdFor } from "../../util/chat-id.js";
 import { runJobOneShot } from "./job-oneshot.js";
 import {
   jobAllowsRun,
@@ -464,10 +465,7 @@ const CRON_JOB_TIMEOUT_MS = 10 * 60_000; // 10-minute max per job
 export async function executeJob(job: CronJob): Promise<ExecuteJobResult> {
   if (!deps) return { status: "skipped", reason: "cron is not initialised" };
 
-  const numericChatId = Number(job.chatId);
-  if (!Number.isFinite(numericChatId)) {
-    throw new Error(`Invalid chatId for job "${job.name}": ${job.chatId}`);
-  }
+  const numericChatId = numericChatIdFor(job.chatId);
 
   if (job.type === "message") {
     await deps.sendMessage(numericChatId, job.content, job.chatId);

package/src/core/engine/gateway-actions/cron.ts

@@ -33,19 +33,19 @@ import type { SharedActionHandlers } from "./types.js";
  * Returns an error string, or null when valid.
  */
 async function validateCronModelOverride(
-  chatId: number,
+  chatKey: string,
   model?: string,
   provider?: string,
 ): Promise<string | null> {
-  const chatBackendId = getBackendIdForChat(String(chatId));
+  const chatBackendId = getBackendIdForChat(chatKey);
   if (!provider || provider === chatBackendId) {
     const capabilityErr = validateCronBackgroundCapability(
       chatBackendId,
-      getBackendForChat(String(chatId)),
+      getBackendForChat(chatKey),
     );
     if (capabilityErr) return capabilityErr;
     if (!model) return null;
-    return validateJobModelOverride(chatId, model);
+    return validateJobModelOverride(chatKey, model);
   }
 
   let acquired: Awaited<ReturnType<typeof acquireBackendInstance>> | null =
@@ -85,7 +85,7 @@ function validateCronBackgroundCapability(
 }
 
 export const cronHandlers: SharedActionHandlers = {
-  create_cron_job: async (body, chatId) => {
+  create_cron_job: async (body, chatId, _backend, chatKey) => {
     const parsed = parseCronSpec(body);
     if (!parsed.ok) return { ok: false, error: parsed.error };
     const spec = parsed.effective;
@@ -103,7 +103,7 @@ export const cronHandlers: SharedActionHandlers = {
     // backend is rejected here instead of silently failing at fire time.
     if (jobType === "query") {
       const modelErr = await validateCronModelOverride(
-        chatId,
+        chatKey,
         spec.model,
         spec.provider,
       );
@@ -114,7 +114,7 @@ export const cronHandlers: SharedActionHandlers = {
     addCronJob({
       ...spec,
       id,
-      chatId: String(chatId),
+      chatId: chatKey,
       enabled: true,
       createdAt: Date.now(),
       runCount: 0,
@@ -147,8 +147,8 @@ export const cronHandlers: SharedActionHandlers = {
     };
   },
 
-  list_cron_jobs: (body, chatId) => {
-    const jobs = getCronJobsForChat(String(chatId));
+  list_cron_jobs: (body, chatId, _backend, chatKey) => {
+    const jobs = getCronJobsForChat(chatKey);
     if (jobs.length === 0)
       return { ok: true, text: "No cron jobs in this chat." };
     const fmt = (ms: number) =>
@@ -191,12 +191,12 @@ export const cronHandlers: SharedActionHandlers = {
     };
   },
 
-  edit_cron_job: async (body, chatId) => {
+  edit_cron_job: async (body, chatId, _backend, chatKey) => {
     const jobId = String(body.job_id ?? "");
     if (!jobId) return { ok: false, error: "Missing job_id" };
     const job = getCronJob(jobId);
     if (!job) return { ok: false, error: `Job ${jobId} not found` };
-    if (job.chatId !== String(chatId))
+    if (job.chatId !== chatKey)
       return { ok: false, error: "Job belongs to a different chat" };
 
     const parsed = parseCronSpec(body, job);
@@ -210,7 +210,7 @@ export const cronHandlers: SharedActionHandlers = {
       ("model" in updates || "provider" in updates || "type" in updates)
     ) {
       const modelErr = await validateCronModelOverride(
-        chatId,
+        chatKey,
         effective.model,
         effective.provider,
       );
@@ -233,12 +233,12 @@ export const cronHandlers: SharedActionHandlers = {
     };
   },
 
-  run_cron_job: async (body, chatId) => {
+  run_cron_job: async (body, chatId, _backend, chatKey) => {
     const jobId = String(body.job_id ?? "");
     if (!jobId) return { ok: false, error: "Missing job_id" };
     const job = getCronJob(jobId);
     if (!job) return { ok: false, error: `Job ${jobId} not found` };
-    if (job.chatId !== String(chatId))
+    if (job.chatId !== chatKey)
       return { ok: false, error: "Job belongs to a different chat" };
     const result = await runJobNow(jobId);
     if (!result.ok) return { ok: false, error: result.error ?? "Run failed" };
@@ -246,12 +246,12 @@ export const cronHandlers: SharedActionHandlers = {
     return { ok: true, text: `Ran job "${job.name}" (${jobId}) now.` };
   },
 
-  delete_cron_job: (body, chatId) => {
+  delete_cron_job: (body, chatId, _backend, chatKey) => {
     const jobId = String(body.job_id ?? "");
     if (!jobId) return { ok: false, error: "Missing job_id" };
     const job = getCronJob(jobId);
     if (!job) return { ok: false, error: `Job ${jobId} not found` };
-    if (job.chatId !== String(chatId))
+    if (job.chatId !== chatKey)
       return { ok: false, error: "Job belongs to a different chat" };
     deleteCronJob(jobId);
     return { ok: true, text: `Deleted cron job "${job.name}" (${jobId})` };

package/src/core/engine/gateway-actions/goals.ts

@@ -26,7 +26,7 @@ import { parseDueDate } from "./shared.js";
 import type { SharedActionHandlers } from "./types.js";
 
 export const goalHandlers: SharedActionHandlers = {
-  add_goal: (body, chatId) => {
+  add_goal: (body, chatId, _backend, chatKey) => {
     const title = String(body.title ?? "").trim();
     const description = body.description ? String(body.description) : undefined;
     const priority = body.priority ?? "normal";
@@ -48,7 +48,7 @@ export const goalHandlers: SharedActionHandlers = {
         };
     }
 
-    const chatIdStr = String(chatId);
+    const chatIdStr = chatKey;
     // No open-goal cap: goals grow freely. The heartbeat re-reads every open
     // goal, so keep them tidy by closing finished ones (completed/abandoned).
 
@@ -75,10 +75,10 @@ export const goalHandlers: SharedActionHandlers = {
     };
   },
 
-  list_goals: (body, chatId) => {
+  list_goals: (body, chatId, _backend, chatKey) => {
     const includeClosed = body.include_closed === true;
     const goals = getGoalsForChat(
-      String(chatId),
+      chatKey,
       includeClosed ? GOAL_STATUSES : OPEN_GOAL_STATUSES,
     );
     if (goals.length === 0)
@@ -94,12 +94,12 @@ export const goalHandlers: SharedActionHandlers = {
     };
   },
 
-  update_goal: (body, chatId) => {
+  update_goal: (body, chatId, _backend, chatKey) => {
     const goalId = String(body.goal_id ?? "");
     if (!goalId) return { ok: false, error: "Missing goal_id" };
     const goal = getGoal(goalId);
     if (!goal) return { ok: false, error: `Goal ${goalId} not found` };
-    if (goal.chatId !== String(chatId))
+    if (goal.chatId !== chatKey)
       return { ok: false, error: "Goal belongs to a different chat" };
 
     const updates: Parameters<typeof updateGoal>[1] = {};
@@ -158,12 +158,12 @@ export const goalHandlers: SharedActionHandlers = {
     };
   },
 
-  delete_goal: (body, chatId) => {
+  delete_goal: (body, chatId, _backend, chatKey) => {
     const goalId = String(body.goal_id ?? "");
     if (!goalId) return { ok: false, error: "Missing goal_id" };
     const goal = getGoal(goalId);
     if (!goal) return { ok: false, error: `Goal ${goalId} not found` };
-    if (goal.chatId !== String(chatId))
+    if (goal.chatId !== chatKey)
       return { ok: false, error: "Goal belongs to a different chat" };
     deleteGoal(goalId);
     return { ok: true, text: `Deleted goal "${goal.title}" (${goalId})` };

package/src/core/engine/gateway-actions/history.ts

@@ -15,9 +15,9 @@ import { formatMediaIndex } from "../../../storage/media-index.js";
 import type { SharedActionHandlers } from "./types.js";
 
 export const historyHandlers: SharedActionHandlers = {
-  read_history: (body, chatId) => {
+  read_history: (body, chatId, _backend, chatKey) => {
     const limit = Math.min(100, Number(body.limit ?? 30));
-    const cid = String(chatId);
+    const cid = chatKey;
     // The tool schema advertises `offset_id` and `before` for paging back;
     // this fallback used to ignore both and hand back the same newest
     // window no matter what the model asked, so "go further back" was a
@@ -36,7 +36,7 @@ export const historyHandlers: SharedActionHandlers = {
     return { ok: true, text: getRecentFormatted(cid, limit) };
   },
 
-  search_history: (body, chatId) => {
+  search_history: (body, chatId, _backend, chatKey) => {
     const limit = Math.min(100, Number(body.limit ?? 20));
     // Optional ISO date bounds; an unparseable one is ignored rather
     // than silently narrowing the search to nothing.
@@ -48,35 +48,28 @@ export const historyHandlers: SharedActionHandlers = {
     };
     return {
       ok: true,
-      text: searchHistory(String(chatId), String(body.query ?? ""), limit, {
+      text: searchHistory(chatKey, String(body.query ?? ""), limit, {
         after: bound(body.after),
         before: bound(body.before),
       }),
     };
   },
 
-  get_user_messages: (body, chatId) => {
+  get_user_messages: (body, chatId, _backend, chatKey) => {
     const limit = Math.min(50, Number(body.limit ?? 20));
     return {
       ok: true,
-      text: getMessagesByUser(
-        String(chatId),
-        String(body.user_name ?? ""),
-        limit,
-      ),
+      text: getMessagesByUser(chatKey, String(body.user_name ?? ""), limit),
     };
   },
 
-  list_known_users: (body, chatId) => ({
+  list_known_users: (body, chatId, _backend, chatKey) => ({
     ok: true,
-    text: getKnownUsers(String(chatId)),
+    text: getKnownUsers(chatKey),
   }),
 
-  list_media: (body, chatId) => ({
+  list_media: (body, chatId, _backend, chatKey) => ({
     ok: true,
-    text: formatMediaIndex(
-      String(chatId),
-      Math.min(20, Number(body.limit ?? 10)),
-    ),
+    text: formatMediaIndex(chatKey, Math.min(20, Number(body.limit ?? 10))),
   }),
 };

package/src/core/engine/gateway-actions/index.ts

@@ -72,15 +72,22 @@ const chatFreeActions: ReadonlySet<string> = new Set([
   ...whatsappAccountChatFreeActions,
 ]);
 
+/**
+ * `chatKey` is the chat's canonical string id (see `SharedActionHandler`).
+ * It defaults to `String(chatId)`, which is exact for Telegram and for the
+ * numeric-only callers (tests, chat-free dispatch); the gateway passes the
+ * real string id it holds for the active turn.
+ */
 export async function handleSharedAction(
   body: Record<string, unknown>,
   chatId: number,
   backend?: Backend | null,
+  chatKey: string = String(chatId),
 ): Promise<ActionResult | null> {
   const action = body.action as string;
   const handler = handlers[action];
   if (!handler) return null; // not a shared action — delegate to frontend
-  return handler(body, chatId, backend);
+  return handler(body, chatId, backend, chatKey);
 }
 
 /**
@@ -104,5 +111,5 @@ export async function handleChatFreeAction(
   if (!isChatFreeAction(action)) return null;
   const handler = handlers[action];
   if (!handler) return null;
-  return handler(body, 0);
+  return handler(body, 0, undefined, "0");
 }

package/src/core/engine/gateway-actions/models.ts

@@ -16,8 +16,8 @@ import {
 import type { SharedActionHandlers } from "./types.js";
 
 export const modelHandlers: SharedActionHandlers = {
-  list_models: async (body, chatId) => {
-    const chatIdStr = String(chatId);
+  list_models: async (body, chatId, _backend, chatKey) => {
+    const chatIdStr = chatKey;
     const currentId = getBackendIdForChat(chatIdStr);
     const requested = body.backend ? String(body.backend).trim() : "";
     const targetId = requested || currentId;
@@ -100,8 +100,8 @@ export const modelHandlers: SharedActionHandlers = {
 
   // Account-level, so it falls back to the pooled Claude backend when
   // another provider is serving this chat.
-  plan_usage: async (_body, chatId) => {
-    const current = getPooledBackend(getBackendIdForChat(String(chatId)));
+  plan_usage: async (_body, chatId, _backend, chatKey) => {
+    const current = getPooledBackend(getBackendIdForChat(chatKey));
     const source = current?.usage?.getPlanUsage
       ? current
       : getPooledBackend("claude");
@@ -131,8 +131,8 @@ export const modelHandlers: SharedActionHandlers = {
     };
   },
 
-  list_backends: (body, chatId) => {
-    const currentId = getBackendIdForChat(String(chatId));
+  list_backends: (body, chatId, _backend, chatKey) => {
+    const currentId = getBackendIdForChat(chatKey);
     const backends = getAvailableBackends().map((b) => ({
       id: b.id,
       label: b.label,

package/src/core/engine/gateway-actions/plugins.ts

@@ -43,7 +43,7 @@ export async function performPluginReload(
 }
 
 export const pluginHandlers: SharedActionHandlers = {
-  reload_plugins: async (body, chatId, backend) => {
+  reload_plugins: async (body, chatId, backend, chatKey) => {
     try {
       const { names } = await performPluginReload(backend);
 
@@ -52,13 +52,7 @@ export const pluginHandlers: SharedActionHandlers = {
       let mcpInfo = "";
       if (backend?.tools?.refreshTools) {
         try {
-          // Prefer body._chatId (string chat ID passed by frontends that use
-          // non-numeric IDs, e.g. Teams/terminal) over the numeric context ID.
-          const refreshChatId =
-            typeof body._chatId === "string" && body._chatId.length > 0
-              ? body._chatId
-              : String(chatId);
-          const result = await backend.tools.refreshTools(refreshChatId);
+          const result = await backend.tools.refreshTools(chatKey);
           if (result) {
             const parts: string[] = [];
             if (result.added.length > 0)

package/src/core/engine/gateway-actions/shared.ts

@@ -30,15 +30,14 @@ export function parseDueDate(value: unknown): number | undefined {
  * when it isn't, or `null` when it's valid.
  */
 export async function validateJobModelOverride(
-  chatId: number,
+  chatKey: string,
   model: string,
 ): Promise<string | null> {
   try {
-    const chatIdStr = String(chatId);
     const ref = await resolveExplicitModelRef(
       model,
-      getBackendForChat(chatIdStr),
-      getBackendIdForChat(chatIdStr),
+      getBackendForChat(chatKey),
+      getBackendIdForChat(chatKey),
     );
     if (!ref) {
       return (

package/src/core/engine/gateway-actions/triggers.ts

@@ -31,7 +31,7 @@ import { validateJobModelOverride } from "./shared.js";
 import type { SharedActionHandlers } from "./types.js";
 
 export const triggerHandlers: SharedActionHandlers = {
-  trigger_create: async (body, chatId) => {
+  trigger_create: async (body, chatId, _backend, chatKey) => {
     const name = String(body.name ?? "").trim();
     const language = body.language;
     const script = String(body.script ?? "");
@@ -55,14 +55,13 @@ export const triggerHandlers: SharedActionHandlers = {
     const timeoutErr = validateTimeout(timeoutSeconds);
     if (timeoutErr) return { ok: false, error: timeoutErr };
 
-    const chatIdStr = String(chatId);
-    if (getTriggerByName(chatIdStr, name)) {
+    if (getTriggerByName(chatKey, name)) {
       return {
         ok: false,
         error: `A trigger named "${name}" already exists in this chat. Cancel it first or pick a different name.`,
       };
     }
-    const active = getActiveTriggersForChat(chatIdStr);
+    const active = getActiveTriggersForChat(chatKey);
     if (active.length >= MAX_ACTIVE_PER_CHAT) {
       return {
         ok: false,
@@ -70,18 +69,10 @@ export const triggerHandlers: SharedActionHandlers = {
       };
     }
 
-    const numericChatId = Number(chatId);
-    if (!Number.isFinite(numericChatId)) {
-      return {
-        ok: false,
-        error: `Cannot derive numeric chatId from ${chatId}`,
-      };
-    }
-
     // Validate the model up front so a bad id is rejected here instead of
     // silently failing at fire time.
     if (model) {
-      const modelErr = await validateJobModelOverride(chatId, model);
+      const modelErr = await validateJobModelOverride(chatKey, model);
       if (modelErr) return { ok: false, error: modelErr };
     }
 
@@ -89,19 +80,19 @@ export const triggerHandlers: SharedActionHandlers = {
     const lang = language as TriggerLanguage;
     let scriptPath: string;
     try {
-      scriptPath = writeScriptFile(chatIdStr, id, lang, script);
+      scriptPath = writeScriptFile(chatKey, id, lang, script);
     } catch (err) {
       return {
         ok: false,
         error: `Failed to write script: ${err instanceof Error ? err.message : err}`,
       };
     }
-    const logPath = triggerLogPath(chatIdStr, id);
+    const logPath = triggerLogPath(chatKey, id);
 
     const trigger = {
       id,
-      chatId: chatIdStr,
-      numericChatId,
+      chatId: chatKey,
+      numericChatId: chatId,
       name,
       language: lang,
       scriptPath,
@@ -151,8 +142,8 @@ export const triggerHandlers: SharedActionHandlers = {
     };
   },
 
-  trigger_list: (body, chatId) => {
-    const triggers = getTriggersForChat(String(chatId));
+  trigger_list: (body, chatId, _backend, chatKey) => {
+    const triggers = getTriggersForChat(chatKey);
     if (triggers.length === 0)
       return { ok: true, text: "No triggers in this chat." };
     const lines = triggers.map((t) => {
@@ -181,12 +172,12 @@ export const triggerHandlers: SharedActionHandlers = {
     };
   },
 
-  trigger_cancel: (body, chatId) => {
+  trigger_cancel: (body, chatId, _backend, chatKey) => {
     const triggerId = String(body.trigger_id ?? "");
     if (!triggerId) return { ok: false, error: "Missing trigger_id" };
     const t = getTrigger(triggerId);
     if (!t) return { ok: false, error: `Trigger ${triggerId} not found` };
-    if (t.chatId !== String(chatId))
+    if (t.chatId !== chatKey)
       return { ok: false, error: "Trigger belongs to a different chat" };
     const wasRunning = cancelTrigger(triggerId);
     if (!wasRunning) {
@@ -201,12 +192,12 @@ export const triggerHandlers: SharedActionHandlers = {
     };
   },
 
-  trigger_logs: (body, chatId) => {
+  trigger_logs: (body, chatId, _backend, chatKey) => {
     const triggerId = String(body.trigger_id ?? "");
     if (!triggerId) return { ok: false, error: "Missing trigger_id" };
     const t = getTrigger(triggerId);
     if (!t) return { ok: false, error: `Trigger ${triggerId} not found` };
-    if (t.chatId !== String(chatId))
+    if (t.chatId !== chatKey)
       return { ok: false, error: "Trigger belongs to a different chat" };
     const lines = Math.min(500, Math.max(1, Number(body.lines ?? 80)));
     const { tail, truncated } = readTriggerLogTail(t.logPath, lines);
@@ -219,12 +210,12 @@ export const triggerHandlers: SharedActionHandlers = {
     };
   },
 
-  trigger_delete: (body, chatId) => {
+  trigger_delete: (body, chatId, _backend, chatKey) => {
     const triggerId = String(body.trigger_id ?? "");
     if (!triggerId) return { ok: false, error: "Missing trigger_id" };
     const t = getTrigger(triggerId);
     if (!t) return { ok: false, error: `Trigger ${triggerId} not found` };
-    if (t.chatId !== String(chatId))
+    if (t.chatId !== chatKey)
       return { ok: false, error: "Trigger belongs to a different chat" };
     // Cancel first if it's still running so we don't orphan a child
     cancelTrigger(triggerId);

package/src/core/engine/gateway-actions/types.ts

@@ -9,10 +9,20 @@
 import type { ActionResult } from "../../types.js";
 import type { Backend } from "../../agent-runtime/capabilities.js";
 
+/**
+ * `chatId` is the frontend's numeric id — the only identity the HTTP bridge
+ * carries. `chatKey` is the chat's canonical string id (the dispatcher's
+ * `chatId`, which every store is keyed on): for Telegram it is just
+ * `String(chatId)`, for every other frontend it is the real id the numeric
+ * one was derived from (`d_…`, `wa_…`, `discord_…`). Handlers that persist,
+ * look up, or route by chat must use `chatKey`, never `String(chatId)` —
+ * a `d_…` chat's jobs stored under its numeric id fire into Telegram.
+ */
 type SharedActionHandler = (
   body: Record<string, unknown>,
   chatId: number,
-  backend?: Backend | null,
+  backend: Backend | null | undefined,
+  chatKey: string,
 ) => Promise<ActionResult> | ActionResult;
 
 export type SharedActionHandlers = Record<string, SharedActionHandler>;

package/src/core/engine/gateway.ts

@@ -307,6 +307,11 @@ export class Gateway {
     const action = typeof body.action === "string" ? body.action : "";
     if (!action) return { ok: false, error: "Missing action" };
     const t0 = Date.now();
+    // The canonical string id for this chat. The bridge only carries the
+    // numeric id, but the turn's Thread is keyed by the dispatcher's string
+    // chatId — hand that to the handlers so a `d_…`/`wa_…` chat's cron jobs,
+    // triggers and history land under the id the rest of the engine uses.
+    const chatKey = this.loom.stringIdForNumeric(chatId) ?? String(chatId);
 
     try {
       // Try frontend first — it has richer implementations (e.g. userbot history)
@@ -326,7 +331,7 @@ export class Gateway {
       }
 
       // Try plugin actions (loaded from external plugin packages)
-      const pluginResult = await handlePluginAction(body, String(chatId));
+      const pluginResult = await handlePluginAction(body, chatKey);
       if (pluginResult) {
         logDebug(
           "gateway",
@@ -336,7 +341,12 @@ export class Gateway {
       }
 
       // Shared actions last — provides in-memory fallbacks for history, cron, etc.
-      const shared = await handleSharedAction(body, chatId, this.backend);
+      const shared = await handleSharedAction(
+        body,
+        chatId,
+        this.backend,
+        chatKey,
+      );
       if (shared) {
         logDebug(
           "gateway",

package/src/core/weaver/loom.ts

@@ -22,6 +22,8 @@ export interface ContextRegistry {
   activeContextCount(): number;
   /** Resolve a string chat id to the numeric id of its active context. */
   numericForStringId(stringId: string): number | null;
+  /** Resolve a numeric id to the string chat id of its active context. */
+  stringIdForNumeric(numericChatId: number): string | null;
   /** Number of live Threads in the registry. */
   size(): number;
 }
@@ -146,6 +148,15 @@ export class Loom implements ContextRegistry {
     return thread?.contextActive ? (thread.numericChatId ?? null) : null;
   }
 
+  /**
+   * Resolve a numeric id to the string chat id of its active context — the
+   * Thread key, which is the dispatcher's `chatId` (see `acquireContext`).
+   * Null outside a turn: the numeric index only mirrors held contexts.
+   */
+  stringIdForNumeric(numericChatId: number): string | null {
+    return this.byNumeric.get(numericChatId)?.chatId ?? null;
+  }
+
   private resolve(id: number | string): Thread | undefined {
     if (typeof id === "number") return this.byNumeric.get(id);
     const direct = this.threads.get(id);

package/src/util/chat-id.ts

@@ -10,6 +10,19 @@ export function deriveNumericChatId(chatId: string): number {
   return hash.readUInt32BE(0);
 }
 
+/**
+ * The numeric id a frontend uses for a chat. Telegram ids are numeric
+ * already; every other frontend (native, WhatsApp, Discord, Teams, terminal)
+ * derives its numeric id from the string one with `deriveNumericChatId`.
+ * This is the inverse the background runtimes need to address a stored
+ * string chat id the way its frontend does.
+ */
+export function numericChatIdFor(chatId: string): number {
+  return isTelegramChatId(chatId)
+    ? Number(chatId)
+    : deriveNumericChatId(chatId);
+}
+
 /** Generate a unique terminal chat ID. */
 export function generateTerminalChatId(): string {
   return `t_${Date.now()}`;