viber-channel 0.8.38 → 0.8.40

package/lib/agent_tools.ts

@@ -190,15 +190,27 @@ export async function messageAgent(
   try {
     outcome = await openDm(ctx.baseUrl(), ctx.instanceToken(), trimmedPeerId);
   } catch (err) {
-    return errorText(`message_agent failed: ${String(err)}`);
+    // #694: openDm already retried a network failure once. No message was posted.
+    return errorText(
+      `message_agent could not open the DM (network error, retried once; nothing was posted): ${String(err)}`,
+    );
   }
   if (!outcome.ok) {
     let friendly: string;
-    if (outcome.detail === "target_offline") {
+    if (outcome.detail === "target_offline" && outcome.liveInstanceIds) {
+      // #692: the id is stale and its agent is online under several ids (a
+      // reconnect race) — the server refused to guess.
+      friendly =
+        `${trimmedPeerId} is a stale id: that agent reconnected and is online under ` +
+        `${outcome.liveInstanceIds.join(", ")}. Call message_agent again with one of them.`;
+    } else if (outcome.detail === "target_offline") {
       // #627: a just-launched agent comes online with its runner's first beat (≤ 30 s).
+      // #692: an agent that reconnected under a new id is followed by the server;
+      // reaching here means no live instance of it was found under any id.
       friendly =
         "That agent is offline right now — it must be running to receive a DM. " +
-        "If it was just launched, it comes online with its runner's next beat (within 30 s): retry then.";
+        "If it was just launched, it comes online with its runner's next beat (within 30 s): retry then. " +
+        "If you expected it online, check list_agents: it may have been relaunched under another name.";
     } else if (outcome.detail === "dm_unavailable_retry") {
       friendly = "Could not open the DM due to a transient conflict — try message_agent again.";
     } else {
@@ -231,7 +243,16 @@ export async function messageAgent(
     return errorText(`message_agent post failed: ${String(err)}`);
   }
   if (!result.ok) {
-    return errorText(result.detail);
+    // #694: name the step — the DM opened, the post is what failed.
+    return errorText(`message_agent: the DM is open, but the post failed: ${result.detail}`);
+  }
+  if (outcome.redirect) {
+    // #692: say which agent was reached, and that the id used is stale.
+    return text(
+      `Message sent to agent ${outcome.redirect.to} (DM ${outcome.dm.conversation_id}). ` +
+        `Note: ${outcome.redirect.from} is a stale id — the same agent reconnected as ` +
+        `${outcome.redirect.to}; use that id from now on.`,
+    );
   }
   return text(`Message sent to agent (DM ${outcome.dm.conversation_id}).`);
 }

package/lib/bridge_tool_host.ts

@@ -115,7 +115,8 @@ export const TOOL_DEFS = [
       "(from list_agents) and the text. Opens or reuses a private 1:1 DM and posts your message; " +
       "the agent's reply arrives back on this channel. Targets are normally same-project; an " +
       "ORCHESTRATOR instance (#307) can also message agents of the owner's other projects. " +
-      "Fails if the target agent is offline.",
+      "Fails if the target agent is offline. An id gone stale because the agent reconnected " +
+      "(same name, new id) still reaches it: the result then names the new id to use (#692).",
     inputSchema: {
       type: "object",
       properties: {

package/lib/claude_tool_defs.ts

@@ -104,7 +104,8 @@ export const CLAUDE_TOOL_DEFS = [
       "the agent's reply arrives back on this channel tagged source=agent-dm. " +
       "Targets are normally same-project; an ORCHESTRATOR instance (#307) can also message agents " +
       "of the owner's other projects (ids from its cross-project list_agents). " +
-      "Fails if the target agent is offline.",
+      "Fails if the target agent is offline. An id gone stale because the agent reconnected " +
+      "(same name, new id) still reaches it: the result then names the new id to use (#692).",
     inputSchema: {
       type: "object" as const,
       properties: {

package/lib/messages.ts

@@ -136,13 +136,144 @@ export interface MessagePostError {
   ok: false;
   status: number;
   detail: string;
-  retriable: boolean;
 }
 
 export type MessagePostResult = MessagePostSuccess | MessagePostError;
 
 /**
- * POST /api/conversations/:conversationId/messages
+ * `detail` of viber-api's GLOBAL notFound (`viber-api/src/index.ts`): what a server
+ * that predates `POST …/messages/idempotent` answers on that route (#694). The
+ * ONLY cue that allows falling back to the legacy route. Tied to the server's text
+ * by a cross test (test/messages.test.ts), so a change there breaks the build here.
+ */
+export const SERVER_NOT_FOUND_DETAIL = "Not found";
+
+/** Statuses an edge or a tunnel answers for a request that may never have run: resent once (#694). */
+const RESEND_STATUSES: ReadonlySet<number> = new Set([502, 503, 504]);
+
+/**
+ * Pause before the single resend (#694). The failed attempt reused a keep-alive
+ * socket a Cloudflare datacenter switch had killed; Bun drops it from its pool, so
+ * the resend opens a fresh connection.
+ */
+export const RESEND_DELAY_MS = 250;
+
+/** Test seams of postMessage; production never passes them. */
+export interface PostMessageOptions {
+  /** Pause before the resend. Default RESEND_DELAY_MS. */
+  resendDelayMs?: number;
+  /** Client message id generator. Default crypto.randomUUID. */
+  newClientMessageId?: () => string;
+}
+
+/** One HTTP attempt: a response whose body was read IN FULL, or a network failure. */
+type Attempt =
+  | { kind: "response"; status: number; statusText: string; body: string }
+  | { kind: "network"; error: unknown };
+
+async function attemptPost(
+  fetchImpl: typeof fetch,
+  url: string,
+  conversationToken: string,
+  payload: Record<string, unknown>,
+  signal: AbortSignal | undefined,
+): Promise<Attempt> {
+  try {
+    const resp = await fetchImpl(url, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${conversationToken}`,
+        "Content-Type": "application/json",
+        ...cfAccessHeaders(),
+      },
+      body: JSON.stringify(payload),
+      signal,
+    });
+    // Read the body here: a socket reset can also land mid-body, and a 404 whose body
+    // was lost must never be mistaken for the global notFound (#694).
+    const body = await resp.text();
+    return { kind: "response", status: resp.status, statusText: resp.statusText, body };
+  } catch (error) {
+    return { kind: "network", error };
+  }
+}
+
+/**
+ * True for the global notFound body BYTE FOR BYTE — `{"detail":"Not found"}`, as
+ * Hono's `c.json` serializes it — and nothing else: not a reformatted variant, not
+ * a different detail, not a body cut by a reset (Codex review, step-02).
+ */
+function isServerNotFound(attempt: Attempt): boolean {
+  return (
+    attempt.kind === "response" &&
+    attempt.status === 404 &&
+    attempt.body === JSON.stringify({ detail: SERVER_NOT_FOUND_DETAIL })
+  );
+}
+
+/** Worth one resend with the same client id: a network failure (not an abort) or 502/503/504. */
+function isResendable(attempt: Attempt, signal: AbortSignal | undefined): boolean {
+  if (signal?.aborted) return false;
+  return attempt.kind === "network" || RESEND_STATUSES.has(attempt.status);
+}
+
+/**
+ * Map one attempt to the result the tools see.
+ * @throws ConversationTokenExpiredError on HTTP 401
+ */
+function toResult(attempt: Attempt, resent: boolean): MessagePostResult {
+  // After a resend the first attempt may have been written: say so, never "lost".
+  const resendNote = resent
+    ? " Resent once with the same client_message_id: delivery is NOT confirmed, it may already be delivered." +
+      " Do not resend unless the user asks: a resend is a new message and could appear twice."
+    : "";
+  if (attempt.kind === "network") {
+    return { ok: false, status: 0, detail: `Network error: ${String(attempt.error)}.${resendNote}` };
+  }
+  const { status, statusText, body } = attempt;
+  if (status === 401) throw new ConversationTokenExpiredError();
+  if (status >= 500) {
+    return {
+      ok: false,
+      status,
+      detail: `Server error (HTTP ${status}): ${body || statusText}.${resendNote || " Retry the call."}`,
+    };
+  }
+  if (status < 200 || status >= 300) {
+    let detail = `HTTP ${status}`;
+    try {
+      const json = JSON.parse(body) as { detail?: unknown };
+      if (typeof json.detail === "string") detail = `HTTP ${status}: ${json.detail}`;
+    } catch {
+      if (body) detail = `HTTP ${status}: ${body}`;
+    }
+    return { ok: false, status, detail: `${detail}${resendNote}` };
+  }
+  // 200 or 201 — the saved message (a 200 on the idempotent route is the one an
+  // earlier attempt wrote).
+  try {
+    const message = JSON.parse(body) as { id: string };
+    return { ok: true, message_id: message.id };
+  } catch (err) {
+    return { ok: false, status, detail: `Failed to parse response JSON: ${String(err)}` };
+  }
+}
+
+/**
+ * POST a message, at most once (#694).
+ *
+ * A Cloudflare datacenter switch kills idle keep-alive sockets; the next POST on
+ * one fails in ~20 ms with ECONNRESET, and Bun never resends a POST itself. So:
+ *   1. one client message id per logical send, sent to `…/messages/idempotent`;
+ *   2. a network failure (not an abort) or 502/503/504 → ONE resend, same id, after
+ *      RESEND_DELAY_MS — the server answers the row the first attempt wrote, if any;
+ *   3. a server that predates the idempotent route answers its global notFound:
+ *      ONLY on the FIRST attempt, and only on that exact, fully read body, the send
+ *      falls back to the legacy `…/messages`, without resend (today's behaviour).
+ *      After an ambiguous first attempt a notFound means a rollback between the two
+ *      attempts: the first may have been written, so the legacy route would
+ *      duplicate it — that is an error, never a fallback.
+ * No timer, no periodic request: a request is added only when a send fails.
  *
  * @throws ConversationTokenExpiredError on HTTP 401
  * @returns MessagePostResult — success with message_id, or error with detail
@@ -157,7 +288,7 @@ export async function postMessage(
    * Optional abort signal (#303 step-12.03): the codex bridge passes its stream's
    * signal so a reply in flight is cancelled atomically if the stream is aborted
    * (re-join / revoke / shutdown) — closing the check-then-post window that a bare
-   * `signal.aborted` guard before the call cannot.
+   * `signal.aborted` guard before the call cannot. An aborted send is never resent.
    */
   signal?: AbortSignal,
   /**
@@ -167,85 +298,26 @@ export async function postMessage(
    * that cannot see the notice cannot prove the fix that exists to emit it.
    */
   fetchImpl: typeof fetch = fetch,
+  options: PostMessageOptions = {},
 ): Promise<MessagePostResult> {
   if (!text || text.trim().length === 0) {
-    return {
-      ok: false,
-      status: 0,
-      detail: "text must be a non-empty string",
-      retriable: false,
-    };
-  }
-
-  const url = `${baseUrl}/api/conversations/${conversationId}/messages`;
-  let resp: Response;
-  try {
-    resp = await fetchImpl(url, {
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${conversationToken}`,
-        "Content-Type": "application/json",
-        ...cfAccessHeaders(),
-      },
-      body: JSON.stringify(artifact ? { content: text, artifact } : { content: text }),
-      signal,
-    });
-  } catch (err) {
-    return {
-      ok: false,
-      status: 0,
-      detail: `Network error: ${String(err)}`,
-      retriable: true,
-    };
-  }
-
-  if (resp.status === 401) {
-    throw new ConversationTokenExpiredError();
+    return { ok: false, status: 0, detail: "text must be a non-empty string" };
   }
 
-  if (resp.status >= 500) {
-    let body = "";
-    try {
-      body = await resp.text();
-    } catch {
-      // ignore
-    }
-    return {
-      ok: false,
-      status: resp.status,
-      detail: `Server error (HTTP ${resp.status}): ${body || resp.statusText}. Retry the call.`,
-      retriable: true,
-    };
-  }
+  const messagesUrl = `${baseUrl}/api/conversations/${conversationId}/messages`;
+  const content: Record<string, unknown> = artifact ? { content: text, artifact } : { content: text };
+  const clientMessageId = (options.newClientMessageId ?? (() => crypto.randomUUID()))();
+  const idempotent = { ...content, client_message_id: clientMessageId };
 
-  if (!resp.ok) {
-    let detail = `HTTP ${resp.status}`;
-    try {
-      const json = (await resp.json()) as { detail?: string };
-      if (typeof json.detail === "string") detail = `HTTP ${resp.status}: ${json.detail}`;
-    } catch {
-      try {
-        const body = await resp.text();
-        if (body) detail = `HTTP ${resp.status}: ${body}`;
-      } catch {
-        // ignore
-      }
-    }
-    return { ok: false, status: resp.status, detail, retriable: false };
-  }
-
-  // 200 or 201 — parse the saved message
-  let message: { id: string };
-  try {
-    message = (await resp.json()) as { id: string };
-  } catch (err) {
-    return {
-      ok: false,
-      status: resp.status,
-      detail: `Failed to parse response JSON: ${String(err)}`,
-      retriable: false,
-    };
+  const first = await attemptPost(fetchImpl, `${messagesUrl}/idempotent`, conversationToken, idempotent, signal);
+  if (isServerNotFound(first)) {
+    const legacy = await attemptPost(fetchImpl, messagesUrl, conversationToken, content, signal);
+    return toResult(legacy, false);
   }
+  if (!isResendable(first, signal)) return toResult(first, false);
 
-  return { ok: true, message_id: message.id };
+  await new Promise((resolve) => setTimeout(resolve, options.resendDelayMs ?? RESEND_DELAY_MS));
+  if (signal?.aborted) return toResult(first, false);
+  const second = await attemptPost(fetchImpl, `${messagesUrl}/idempotent`, conversationToken, idempotent, signal);
+  return toResult(second, true);
 }

package/lib/peers.ts

@@ -10,6 +10,7 @@
  */
 
 import { cfAccessHeaders } from "./cfAccess.js";
+import { RESEND_DELAY_MS } from "./messages.js";
 
 /** A peer agent as returned by GET /api/instances/peers.
  *  project_id/project_name are present only in the user-scoped listing (#307):
@@ -153,40 +154,76 @@ export interface OpenDmResult {
   invited: boolean;
 }
 
+/** #692: the server opened the DM with the live instance of the identity the
+ *  caller named by a stale id. */
+export interface OpenDmRedirect {
+  from: string;
+  to: string;
+}
+
 export type OpenDmOutcome =
-  | { ok: true; dm: OpenDmResult }
-  | { ok: false; detail: string; status: number };
+  | { ok: true; dm: OpenDmResult; redirect?: OpenDmRedirect }
+  | { ok: false; detail: string; status: number; liveInstanceIds?: string[] };
+
+/** Server-supplied ids end up in the model's prompt: only an instance id shape
+ *  (32 lowercase hex) is ever echoed back, never free text. */
+function instanceIdOrNull(v: unknown): string | null {
+  return typeof v === "string" && /^[0-9a-f]{32}$/.test(v) ? v : null;
+}
 
 /**
  * Open-or-create a 1:1 DM with `peerInstanceId` (POST /api/instances/dms).
  * Returns a structured outcome rather than throwing on the expected 4xx cases
  * (peer offline / not found) so the tool can surface a clear message to the
  * model; network/parse failures throw.
+ *
+ * #694: a network failure (a keep-alive socket killed by a Cloudflare datacenter
+ * switch) is retried ONCE after `retryDelayMs`. Safe because the route is
+ * open-or-create: a second call finds the pair the first one created and pushes
+ * no second join (viber-api instances.test.ts, "a resend in the SAME direction").
  */
 export async function openDm(
   baseUrl: string,
   instanceToken: string,
   peerInstanceId: string,
+  /** Fetch seam (#694 tests). Defaults to the global `fetch`. */
+  fetchImpl: typeof fetch = fetch,
+  retryDelayMs: number = RESEND_DELAY_MS,
 ): Promise<OpenDmOutcome> {
-  const resp = await fetch(`${baseUrl}/api/instances/dms`, {
-    method: "POST",
-    headers: {
-      Authorization: `Bearer ${instanceToken}`,
-      "Content-Type": "application/json",
-      ...cfAccessHeaders(),
-    },
-    body: JSON.stringify({ peer_instance_id: peerInstanceId }),
-  });
+  const send = (): Promise<Response> =>
+    fetchImpl(`${baseUrl}/api/instances/dms`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${instanceToken}`,
+        "Content-Type": "application/json",
+        ...cfAccessHeaders(),
+      },
+      body: JSON.stringify({ peer_instance_id: peerInstanceId }),
+    });
+  let resp: Response;
+  try {
+    resp = await send();
+  } catch {
+    await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
+    resp = await send();
+  }
 
   if (!resp.ok) {
     let detail = `HTTP ${resp.status}`;
+    let liveInstanceIds: string[] | undefined;
     try {
-      const json = (await resp.json()) as { detail?: string };
+      const json = (await resp.json()) as { detail?: string; live_instance_ids?: unknown };
       if (typeof json.detail === "string") detail = json.detail;
+      // #692: several live instances of a stale id's identity — the server
+      // refused to guess and named them.
+      if (Array.isArray(json.live_instance_ids)) {
+        const ids = json.live_instance_ids.map(instanceIdOrNull).filter((id): id is string => id !== null);
+        if (ids.length > 0) liveInstanceIds = ids;
+      }
     } catch {
       /* non-JSON body */
     }
-    return { ok: false, detail, status: resp.status };
+    return { ok: false, detail, status: resp.status, ...(liveInstanceIds ? { liveInstanceIds } : {}) };
   }
 
   const body = (await resp.json()) as {
@@ -194,6 +231,8 @@ export async function openDm(
     conversation_token?: string;
     expires_at?: number;
     invited?: boolean;
+    peer_instance_id?: unknown;
+    redirected_from?: unknown;
   };
   if (!body.conversation?.id || typeof body.conversation_token !== "string") {
     throw new Error("openDm: malformed response (missing conversation id or token)");
@@ -206,5 +245,14 @@ export async function openDm(
       expires_at: typeof body.expires_at === "number" ? body.expires_at : 0,
       invited: body.invited === true,
     },
+    ...redirectOf(body.redirected_from, body.peer_instance_id),
   };
 }
+
+/** #692: both ids well-formed and distinct, or no redirect at all. An older
+ *  server sends neither field. */
+function redirectOf(from: unknown, to: unknown): { redirect?: OpenDmRedirect } {
+  const f = instanceIdOrNull(from);
+  const t = instanceIdOrNull(to);
+  return f && t && f !== t ? { redirect: { from: f, to: t } } : {};
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viber-channel",
-  "version": "0.8.38",
+  "version": "0.8.40",
   "description": "Voice + text MCP channel between a Claude Code session and the Viber UI (https://viber.dgypx.dev). Push transcripts to Claude; send_message tool delivers text back to the UI.",
   "type": "module",
   "bin": {