@agentprojectcontext/apx 1.81.0 → 1.89.1

package/src/interfaces/web/src/lib/channels.ts

@@ -0,0 +1,214 @@
+// Channels, as THIS DEVICE wants them.
+//
+// One agent is reachable from several places at once, and the inbox now shows
+// every one of them. That is right for the list and wrong for the bell: the
+// phone has Telegram installed ON it, so a Telegram reply announced by APX is
+// the same event announced twice, while the same reply on the laptop is the
+// only way to hear about it at all. There is no single correct answer, so the
+// question is asked per device.
+//
+// Two independent axes, deliberately not one setting:
+//   VIEW   — whose conversations appear in the lists (inbox, phone).
+//   NOTIFY — who is allowed to raise a notification.
+// Hiding Telegram threads from the phone list and still wanting a bell for them
+// is a coherent position; so is the reverse.
+//
+// Stored in localStorage because that IS the scope of the question — per
+// origin, per device, and untouched by another browser signing in. Only
+// EXPLICIT choices are stored: an absent channel falls through to the default
+// for the surface, so a channel invented after this code shipped behaves
+// sensibly instead of being silently muted.
+import { isInstalled } from "./net";
+import { t } from "../i18n";
+
+export type ChannelAxis = "view" | "notify";
+
+const KEYS: Record<ChannelAxis, string> = {
+  view: "apx.channels.view",
+  notify: "apx.channels.notify",
+};
+
+/** Proper nouns, mostly, so they read the same in either locale. The two that
+ *  are descriptions rather than names go through i18n. Anything unknown shows
+ *  its raw value rather than being hidden — a channel nobody named is exactly
+ *  the one worth seeing. */
+const CHANNEL_LABELS: Record<string, string> = {
+  whatsapp: "WhatsApp",
+  telegram: "Telegram",
+  web: "Web",
+  web_sidebar: "Web · sidebar",
+  web_code: "Web · code",
+  desktop: "Desktop",
+  deck: "Deck",
+  code: "Code",
+  cli: "CLI",
+  api: "API",
+  direct: "Direct",
+  routine: "Routine",
+  log: "Log",
+};
+
+export function channelLabel(channel: string): string {
+  if (channel === "a2a") return t("channels.a2a");
+  if (channel === "group") return t("channels.group");
+  if (channel === "other") return t("channels.other");
+  // Not a channel a conversation happens on — a kind of news the phone can
+  // ring for (the trip bubbles). It only ever appears in the APK's notify
+  // list, which is why it is a description and goes through i18n.
+  if (channel === "mobility") return t("channels.mobility");
+  return CHANNEL_LABELS[channel] || channel;
+}
+
+/**
+ * Is this the phone shell, rather than the panel?
+ *
+ * Installed counts (the APK and an installed PWA both open on the phone
+ * surface), and so does simply being on one of its routes in a browser. It
+ * decides two things: the shape of the URL a notification tap lands on, and
+ * which channels are muted out of the box.
+ *
+ * `/mobile` is still matched: it is the phone's old address and the Android
+ * shell still opens it, so a tab that has not been redirected yet is still a
+ * phone. The panel's own modules used to live under `/m` too, so they are
+ * excluded by name — being one render early on `/m/code` must not make a
+ * 27-inch panel start behaving like a phone.
+ */
+const PANEL_MODULES_UNDER_M = /^\/m\/(inbox|code|desktop|voice|deck)(\/|$)/;
+
+export function isPhoneSurface(): boolean {
+  if (isInstalled()) return true;
+  if (typeof location === "undefined") return false;
+  const path = location.pathname;
+  if (PANEL_MODULES_UNDER_M.test(path)) return false;
+  return path === "/m" || path.startsWith("/m/") || path.startsWith("/mobile");
+}
+
+/**
+ * Channels that start OFF on the phone.
+ *
+ * Telegram, and only Telegram: the app is on the same device, so its own
+ * notification has already arrived and its own thread is one home-screen icon
+ * away. Everything else is a place the phone cannot otherwise reach. One tap on
+ * the chip turns it back on, per axis, and that choice is then remembered
+ * instead of falling back here.
+ */
+const PHONE_MUTED = new Set(["telegram"]);
+
+/**
+ * Channels that never ring, on any device.
+ *
+ * `log` is the one: it exists so that output which must be READABLE but must
+ * not ARRIVE has somewhere to live — a routine's reasoning when it chose to
+ * stay quiet. A notification for that is the interruption the routine just
+ * declined to make, so the bell is off by default here rather than left to the
+ * generic "a new channel is probably worth hearing about" rule.
+ *
+ * View is untouched: the thread shows in the lists like any other, in its own
+ * channel group, and one tick in the filter hides it for a device that would
+ * rather not see it at all.
+ */
+const NEVER_NOTIFY = new Set(["log"]);
+
+export function channelDefault(axis: ChannelAxis, channel: string): boolean {
+  if (axis === "notify" && NEVER_NOTIFY.has(channel)) return false;
+  return !(isPhoneSurface() && PHONE_MUTED.has(channel));
+}
+
+/** The explicit choices on one axis. Absent channels are NOT in here. */
+export function channelPrefs(axis: ChannelAxis): Record<string, boolean> {
+  try {
+    const raw = localStorage.getItem(KEYS[axis]);
+    if (!raw) return {};
+    const parsed = JSON.parse(raw) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+    const out: Record<string, boolean> = {};
+    for (const [k, v] of Object.entries(parsed as Record<string, unknown>)) {
+      if (typeof v === "boolean") out[k] = v;
+    }
+    return out;
+  } catch {
+    return {}; // private mode, or something else wrote over the key
+  }
+}
+
+/** The same answer, against a map already in hand — what a React render has,
+ *  and what keeps a memo dependent on a stable value instead of a closure
+ *  rebuilt every render. */
+export function channelEnabledIn(
+  prefs: Record<string, boolean>,
+  axis: ChannelAxis,
+  channel: string | null | undefined,
+): boolean {
+  const key = channel || "other";
+  const explicit = prefs[key];
+  return explicit === undefined ? channelDefault(axis, key) : explicit;
+}
+
+/** Should this channel be shown / announced on this device right now? */
+export function channelEnabled(axis: ChannelAxis, channel: string | null | undefined): boolean {
+  return channelEnabledIn(channelPrefs(axis), axis, channel);
+}
+
+/** Remember a choice. Listeners (the chips, the notifier) hear about it through
+ *  the event below rather than by polling storage. */
+export function setChannelEnabled(axis: ChannelAxis, channel: string, on: boolean) {
+  const next = { ...channelPrefs(axis), [channel]: on };
+  try {
+    localStorage.setItem(KEYS[axis], JSON.stringify(next));
+  } catch {
+    /* private mode: it holds for this session, which is all we can offer */
+  }
+  emitChange(axis);
+}
+
+/** Turn a whole set on or off in one write — "show everything again" is one
+ *  decision, not eleven, and eleven writes would be eleven re-renders. */
+export function setChannelsEnabled(axis: ChannelAxis, channels: string[], on: boolean) {
+  const next = { ...channelPrefs(axis) };
+  for (const channel of channels) next[channel] = on;
+  try {
+    localStorage.setItem(KEYS[axis], JSON.stringify(next));
+  } catch {
+    /* private mode: it holds for this session, which is all we can offer */
+  }
+  emitChange(axis);
+}
+
+// A same-tab change fires nothing on its own — `storage` only reaches OTHER
+// tabs — so the chips and the notifier would keep rendering the old answer
+// until something else re-rendered them.
+const CHANGE_EVENT = "apx:channel-prefs";
+
+function emitChange(axis: ChannelAxis) {
+  try {
+    window.dispatchEvent(new CustomEvent(CHANGE_EVENT, { detail: { axis } }));
+  } catch {
+    /* no window (SSR, a test): nothing is listening anyway */
+  }
+}
+
+/** Subscribe to preference changes, from this tab or another one. */
+export function onChannelPrefsChange(fn: () => void): () => void {
+  const local = () => fn();
+  const remote = (e: StorageEvent) => {
+    if (!e.key || e.key === KEYS.view || e.key === KEYS.notify) fn();
+  };
+  window.addEventListener(CHANGE_EVENT, local);
+  window.addEventListener("storage", remote);
+  return () => {
+    window.removeEventListener(CHANGE_EVENT, local);
+    window.removeEventListener("storage", remote);
+  };
+}
+
+/** The channels present in a set of rows, most recent first (rows arrive
+ *  sorted), so a filter strip offers what actually exists on this install
+ *  rather than a hardcoded catalog of everything APX can speak. */
+export function channelsOf(rows: { channel: string | null }[]): string[] {
+  const seen: string[] = [];
+  for (const row of rows) {
+    const key = row.channel || "other";
+    if (!seen.includes(key)) seen.push(key);
+  }
+  return seen;
+}

package/src/interfaces/web/src/lib/chat-activity.ts

@@ -0,0 +1,175 @@
+// One device-wide chat activity registry.
+//
+// Chat panes mount and unmount as navigation moves between Inbox, a project and
+// the phone shell. A turn does not: it belongs to the daemon. Keeping the small
+// UI projection here (running / unread / queued) gives every rail one contract
+// and keeps a finished answer visible after the pane that started it is gone.
+import { subscribeTurns } from "./live";
+import type { ActiveTurn, TurnFrame } from "../types/daemon";
+
+export interface ChatActivity {
+  running: boolean;
+  unread: boolean;
+  queued: number;
+  turnId?: string;
+}
+
+const EMPTY: ChatActivity = Object.freeze({ running: false, unread: false, queued: 0 });
+const state = new Map<string, ChatActivity>();
+const visible = new Set<string>();
+const closedTurnIds = new Set<string>();
+const listeners = new Set<() => void>();
+const UNREAD_KEY = "apx.chat.unread.v1";
+let wired = false;
+let hydrated = false;
+
+export function conversationActivityKey(pid: string | number, conversationId: string): string {
+  return `${pid}:conv:${conversationId}`;
+}
+
+export function threadActivityKey(
+  pid: string | number,
+  channel: string,
+  threadId: string,
+): string {
+  return `${pid}:thread:${channel}:${threadId}`;
+}
+
+export function liveActivityKey(pid: string | number, agentSlug: string): string {
+  return `${pid}:live:${agentSlug}`;
+}
+
+export function activityKeyFromActiveTurn(active?: ActiveTurn | null): string | null {
+  if (!active || active.project_id == null) return null;
+  if (active.conversation_id) {
+    return conversationActivityKey(active.project_id, active.conversation_id);
+  }
+  if (active.channel && active.thread_id) {
+    return threadActivityKey(active.project_id, active.channel, active.thread_id);
+  }
+  return null;
+}
+
+function frameKey(frame: TurnFrame): string | null {
+  if (frame.project_id == null) return null;
+  if (frame.conversation_id) {
+    return conversationActivityKey(frame.project_id, frame.conversation_id);
+  }
+  if (frame.channel && frame.thread_id) {
+    return threadActivityKey(frame.project_id, frame.channel, frame.thread_id);
+  }
+  return null;
+}
+
+function hydrateUnread() {
+  if (hydrated || typeof window === "undefined") return;
+  hydrated = true;
+  try {
+    const raw = JSON.parse(localStorage.getItem(UNREAD_KEY) || "[]");
+    if (!Array.isArray(raw)) return;
+    for (const key of raw) {
+      if (typeof key === "string") state.set(key, { ...EMPTY, unread: true });
+    }
+  } catch {
+    // Private mode / corrupt preference: unread starts empty.
+  }
+}
+
+function persistUnread() {
+  if (typeof window === "undefined") return;
+  try {
+    const keys = [...state.entries()].filter(([, value]) => value.unread).map(([key]) => key);
+    localStorage.setItem(UNREAD_KEY, JSON.stringify(keys));
+  } catch {
+    // Per-device hint only; storage refusal must never break chat.
+  }
+}
+
+function publish() {
+  for (const listener of listeners) listener();
+}
+
+function patch(key: string, next: Partial<ChatActivity>) {
+  hydrateUnread();
+  const current = state.get(key) || EMPTY;
+  const value = { ...current, ...next };
+  if (!value.running && !value.unread && !value.queued) state.delete(key);
+  else state.set(key, value);
+  publish();
+}
+
+function onTurn(frame: TurnFrame) {
+  const key = frameKey(frame);
+  if (!key) return;
+  if (frame.phase === "start" || frame.phase === "delta") {
+    closedTurnIds.delete(frame.turn_id);
+    patch(key, { running: true, turnId: frame.turn_id });
+    return;
+  }
+  closedTurnIds.add(frame.turn_id);
+  const unread = frame.phase === "final" || frame.phase === "aborted"
+    ? !visible.has(key)
+    : false;
+  patch(key, { running: false, unread, turnId: undefined });
+  persistUnread();
+}
+
+function wire() {
+  if (wired) return;
+  wired = true;
+  hydrateUnread();
+  // Deliberately process-lifetime. Screens churn; the device-wide registry must
+  // hear the closing frame even when no chat pane happens to be mounted.
+  subscribeTurns(onTurn);
+}
+
+export function subscribeChatActivity(listener: () => void): () => void {
+  wire();
+  listeners.add(listener);
+  return () => { listeners.delete(listener); };
+}
+
+export function readChatActivity(key: string | null): ChatActivity {
+  hydrateUnread();
+  if (!key) return EMPTY;
+  return state.get(key) || EMPTY;
+}
+
+/** Seed a list row from the daemon snapshot. Never clears a live frame with a
+ * stale list response; closing frames own that transition. */
+export function seedActiveTurn(key: string | null, active?: ActiveTurn | null) {
+  if (!key || !active || closedTurnIds.has(active.turn_id)) return;
+  patch(key, { running: true, turnId: active.turn_id });
+}
+
+/** A list/detail response can have been serialized just before its turn closed
+ * frame arrived. Refuse that stale snapshot when the response reaches React. */
+export function isChatTurnClosed(turnId?: string | null): boolean {
+  return !!turnId && closedTurnIds.has(turnId);
+}
+
+export function setChatQueued(key: string | null, queued: number) {
+  if (!key) return;
+  patch(key, { queued: Math.max(0, queued) });
+}
+
+export function setChatVisible(key: string | null, shown: boolean) {
+  if (!key) return;
+  wire();
+  if (shown) {
+    visible.add(key);
+    patch(key, { unread: false });
+    persistUnread();
+  } else {
+    visible.delete(key);
+  }
+}
+
+/** Test seam. */
+export function resetChatActivity() {
+  state.clear();
+  visible.clear();
+  closedTurnIds.clear();
+  hydrated = false;
+  publish();
+}

package/src/interfaces/web/src/lib/chat-prefs.ts

@@ -0,0 +1,48 @@
+// What this DEVICE wants a chat to do, kept out of the global config for the
+// same reason the per-channel view/notify choices are (lib/channels.ts): the
+// phone and the desktop are used differently by the same person, and neither
+// should be able to change the other's behaviour by accident.
+
+const KEY = "apx.chat.queueOnSend";
+
+type Listener = () => void;
+const listeners = new Set<Listener>();
+
+/**
+ * Send during a running turn: interrupt it, or wait behind it?
+ *
+ * The default is INTERRUPT, because that is what typing while an agent works
+ * almost always means — "no, stop, do this instead" — and it is what Telegram
+ * has always done (core/channels/telegram/dispatch.js aborts the running turn
+ * when a new message arrives). Queueing was the web's behaviour only because
+ * there was nothing to interrupt: no route passed a signal, so waiting was the
+ * only thing the panel could offer.
+ *
+ * Queueing is still worth having on purpose — "finish that, then do this" —
+ * which is why it stayed, as a choice rather than as the only option.
+ */
+export function queueOnSend(): boolean {
+  try {
+    return localStorage.getItem(KEY) === "1";
+  } catch {
+    // Private mode, blocked site data: fall back to the default rather than
+    // making the composer throw.
+    return false;
+  }
+}
+
+export function setQueueOnSend(on: boolean): void {
+  try {
+    if (on) localStorage.setItem(KEY, "1");
+    else localStorage.removeItem(KEY);
+  } catch {
+    /* nothing to persist to; the session still honours the call below */
+  }
+  for (const fn of listeners) fn();
+}
+
+/** Subscribe to changes from anywhere in this tab. Returns an unsubscribe. */
+export function onChatPrefsChange(fn: Listener): () => void {
+  listeners.add(fn);
+  return () => listeners.delete(fn);
+}

package/src/interfaces/web/src/lib/code-context.ts

@@ -6,8 +6,6 @@
 // where the conversation's weight sits (user vs assistant vs tool I/O).
 import type { CodeTurn } from "./api/code";
 
-const estTokens = (s: string): number => (s ? Math.ceil(s.length / 4) : 0);
-
 function turnText(turn: CodeTurn, kinds: { text?: boolean; tool?: boolean }): number {
   let chars = 0;
   for (const p of turn.parts || []) {

package/src/interfaces/web/src/lib/http.ts

@@ -1,7 +1,14 @@
 // Typed HTTP client against the APX daemon. All requests carry the bearer
-// token loaded once on first paint (see useTokenBootstrap). Same-origin:
-// when the daemon serves the SPA, requests land on the same port; in
+// token loaded once on first paint (see useTokenBootstrap). Same-origin by
+// default: when the daemon serves the SPA, requests land on the same port; in
 // `vite dev` the proxy redirects to 7430.
+//
+// "By default", because an installed app launches at the address it was
+// installed from and that address is not always reachable — the phone left the
+// Wi-Fi, or Tailscale is off. A request that cannot reach the current address
+// asks lib/net to find one that answers and is retried there; see that file
+// for the whole story.
+import { apiUrl, mayBeWrongAddress, recoverConnection, recoverIfAddressIsWrong } from "./net";
 
 let token: string | null = null;
 
@@ -31,12 +38,30 @@ async function request<T>(
     ...(token ? { authorization: `Bearer ${token}` } : {}),
     ...((init.headers as Record<string, string>) || {}),
   };
-  const res = await fetch(path, {
-    ...init,
-    method,
-    headers,
-    body: body !== undefined ? JSON.stringify(body) : undefined,
-  });
+  const send = () =>
+    fetch(apiUrl(path), {
+      ...init,
+      method,
+      headers,
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+  let res: Response;
+  try {
+    res = await send();
+  } catch (e) {
+    // A rejected fetch is a NETWORK failure — DNS, refused, unreachable — not
+    // an HTTP error. That is exactly the case another address might fix.
+    if ((init.signal as AbortSignal | undefined)?.aborted) throw e;
+    if ((await recoverConnection()) === null) throw e;
+    res = await send();
+  }
+  // Not every wrong address fails by rejecting. Private ranges repeat across
+  // networks, so a phone that changed Wi-Fi can reach *something* at the old
+  // address and be told 404 by a stranger. Confirm our daemon is still there
+  // before passing that on as an answer.
+  if (!res.ok && mayBeWrongAddress(res.status) && (await recoverIfAddressIsWrong())) {
+    res = await send();
+  }
   if (!res.ok) {
     let detail = "";
     let parsed: unknown = null;
@@ -95,15 +120,24 @@ export async function streamNdjson<E = unknown>(
   onEvent: (ev: E) => void,
   signal?: AbortSignal
 ): Promise<void> {
-  const res = await fetch(path, {
-    method: "POST",
-    signal,
-    headers: {
-      "content-type": "application/json",
-      ...(token ? { authorization: `Bearer ${token}` } : {}),
-    },
-    body: JSON.stringify(body),
-  });
+  const open = () =>
+    fetch(apiUrl(path), {
+      method: "POST",
+      signal,
+      headers: {
+        "content-type": "application/json",
+        ...(token ? { authorization: `Bearer ${token}` } : {}),
+      },
+      body: JSON.stringify(body),
+    });
+  let res: Response;
+  try {
+    res = await open();
+  } catch (e) {
+    if (signal?.aborted) throw e;
+    if ((await recoverConnection()) === null) throw e;
+    res = await open();
+  }
   if (!res.ok || !res.body) {
     const text = await res.text().catch(() => "");
     throw new HttpError(res.status, `POST ${path} → ${res.status}: ${text || "stream failed"}`);

package/src/interfaces/web/src/lib/inbox-selection.ts

@@ -0,0 +1,29 @@
+// Which thread an inbox row points at, and how to tell when it has moved.
+//
+// Pure on purpose: the inbox follows its selected row as the list refreshes
+// underneath, and getting the comparison wrong is invisible until the exact day
+// it matters. Kept out of the screen so it can be tested without a DOM.
+
+/** The part of an inbox row that says WHICH thread it currently points at. */
+export interface RowThread {
+  channel?: string | null;
+  conversation_id?: string | null;
+}
+
+/**
+ * Has this row's thread changed since it was selected?
+ *
+ * Channel AND id, never the id alone. The super-agent's history is a ledger file
+ * per channel per DAY, so today's Telegram thread and today's web thread are
+ * both `2026-08-20` and differ only by channel. Comparing ids left the pane on
+ * the web thread while the row it belongs to had already moved to Telegram: the
+ * list showed a preview the pane could not reach.
+ *
+ * Null and undefined are the same absence — a row that never had a channel and
+ * one whose channel is null must not read as a move, or the pane would remount
+ * on every refresh.
+ */
+export function threadMoved(selected: RowThread, fresh: RowThread): boolean {
+  const same = (a: string | null | undefined, b: string | null | undefined) => (a ?? null) === (b ?? null);
+  return !same(selected.conversation_id, fresh.conversation_id) || !same(selected.channel, fresh.channel);
+}