talon-agent 3.33.4 → 3.34.0

package/src/frontend/whatsapp/runtime.ts

@@ -0,0 +1,74 @@
+/**
+ * WhatsApp frontend runtime — the state every module shares.
+ *
+ * `createWhatsAppFrontend` used to hold all of this as closure variables
+ * with every handler nested inside it. It is now one explicit object,
+ * constructed once, that each module (access, inbound, connection) takes
+ * as its first parameter. The runtime carries the parsed settings, the
+ * allow-lists and the live socket state; the modules own the behaviour.
+ */
+
+import type { WASocket } from "baileys";
+import type { TalonConfig } from "../../util/config.js";
+import type { Gateway } from "../../core/engine/gateway.js";
+import { bareId } from "./identity.js";
+
+type WhatsAppSettings = {
+  allowedJids: string[];
+  allowedGroups: string[];
+  groupPolicy: "listed" | "with-allowed-user" | "all";
+  respondMode: "mention" | "all";
+  pairingNumber?: string;
+  sendReadReceipts: boolean;
+};
+
+/** Reconnect backoff: WhatsApp throttles a client that hammers it. */
+export const RECONNECT_BASE_MS = 2_000;
+export const RECONNECT_MAX_MS = 60_000;
+
+export type WhatsAppRuntime = {
+  readonly config: TalonConfig;
+  readonly gateway: Gateway;
+  readonly settings: WhatsAppSettings;
+  /** `allowedJids` / `allowedGroups`, normalised to bare ids. */
+  readonly allowedDms: ReadonlySet<string>;
+  readonly allowedGroups: ReadonlySet<string>;
+  /** Cached `groupPolicy` verdicts, keyed by group JID. */
+  readonly groupAllowCache: Map<string, { allowed: boolean; at: number }>;
+  /** The live socket. Reconnects replace it, so read it at each use. */
+  sock: WASocket | null;
+  stopping: boolean;
+  reconnectDelay: number;
+  /** One "not linked" admin note per outage, not one per QR window. */
+  unpairedNotified: boolean;
+  /** Our own ids (phone and LID), once connected — for mention detection. */
+  selfIds: string[];
+};
+
+export function createWhatsAppRuntime(
+  config: TalonConfig,
+  gateway: Gateway,
+): WhatsAppRuntime {
+  const settings: WhatsAppSettings = {
+    allowedJids: [],
+    allowedGroups: [],
+    groupPolicy: "listed",
+    respondMode: "mention",
+    sendReadReceipts: true,
+    ...((config as Record<string, unknown>).whatsapp as
+      Partial<WhatsAppSettings> | undefined),
+  };
+  return {
+    config,
+    gateway,
+    settings,
+    allowedDms: new Set(settings.allowedJids.map(bareId)),
+    allowedGroups: new Set(settings.allowedGroups.map(bareId)),
+    groupAllowCache: new Map(),
+    sock: null,
+    stopping: false,
+    reconnectDelay: RECONNECT_BASE_MS,
+    unpairedNotified: false,
+    selfIds: [],
+  };
+}

package/src/storage/metrics.ts

@@ -9,6 +9,16 @@ import {
   type MetricsGrain,
   type MetricsLatencyAgg,
 } from "./sessions.js";
+import { emptyPhases, TURN_PHASES, type TurnPhase } from "./session-record.js";
+
+/** Snapshot key for each turn phase — same `_ms` suffix the panels key on. */
+const PHASE_HISTOGRAM: Record<TurnPhase, string> = {
+  queueWait: "turn.queue_wait_ms",
+  warpResolve: "turn.warp_resolve_ms",
+  firstToken: "turn.first_token_ms",
+  stream: "turn.stream_ms",
+  delivery: "turn.delivery_ms",
+};
 
 const legacyCounters = new Map<string, number>();
 
@@ -64,8 +74,12 @@ function buildSnapshot(
   const apiCallsPerTurn = emptyAgg();
   const cacheHitPercent = emptyAgg();
   const backendLatency = new Map<string, MetricsLatencyAgg>();
+  const phases = emptyPhases();
 
   for (const grain of grains) {
+    for (const phase of TURN_PHASES) {
+      mergeAgg(phases[phase], grain.phases[phase]);
+    }
     const c = grain.counters;
     addCounter(counters, "queries_total", c.queries);
     addCounter(counters, "turns_with_tools_total", c.turnsWithTools);
@@ -131,6 +145,10 @@ function buildSnapshot(
     if (agg.count)
       histograms[`backend.${backend}.response_latency_ms`] = snapshotAgg(agg);
   }
+  for (const phase of TURN_PHASES) {
+    if (phases[phase].count)
+      histograms[PHASE_HISTOGRAM[phase]] = snapshotAgg(phases[phase]);
+  }
 
   return { counters, histograms };
 }

package/src/storage/session-record.ts

@@ -54,6 +54,21 @@ export type MetricsLatencyAgg = {
   maxMs: number;
 };
 
+/**
+ * Where a turn's wall-clock went, as seen from the Weaver: waiting in the
+ * chat's FIFO, resolving the warp, until the backend's first event, the
+ * whole stream, and the slice of it spent inside frontend delivery.
+ */
+export const TURN_PHASES = [
+  "queueWait",
+  "warpResolve",
+  "firstToken",
+  "stream",
+  "delivery",
+] as const;
+export type TurnPhase = (typeof TURN_PHASES)[number];
+export type MetricsPhaseAggs = Record<TurnPhase, MetricsLatencyAgg>;
+
 export type MetricsGrain = {
   counters: MetricsCounterSet;
   latency: MetricsLatencyAgg;
@@ -62,6 +77,7 @@ export type MetricsGrain = {
   cacheHitPercent: MetricsLatencyAgg;
   toolCallsPerTurn: MetricsLatencyAgg;
   apiCallsPerTurn: MetricsLatencyAgg;
+  phases: MetricsPhaseAggs;
 };
 
 export type SessionMetrics = {
@@ -127,6 +143,14 @@ export const emptyLatency = (): MetricsLatencyAgg => ({
   maxMs: 0,
 });
 
+export const emptyPhases = (): MetricsPhaseAggs => ({
+  queueWait: emptyLatency(),
+  warpResolve: emptyLatency(),
+  firstToken: emptyLatency(),
+  stream: emptyLatency(),
+  delivery: emptyLatency(),
+});
+
 export const emptyGrain = (): MetricsGrain => ({
   counters: emptyCounters(),
   latency: emptyLatency(),
@@ -135,6 +159,7 @@ export const emptyGrain = (): MetricsGrain => ({
   cacheHitPercent: emptyLatency(),
   toolCallsPerTurn: emptyLatency(),
   apiCallsPerTurn: emptyLatency(),
+  phases: emptyPhases(),
 });
 
 export const emptyMetrics = (): SessionMetrics => ({
@@ -179,6 +204,10 @@ function normaliseGrain(raw: unknown): MetricsGrain {
   grain.cacheHitPercent = normaliseLatency(r?.cacheHitPercent);
   grain.toolCallsPerTurn = normaliseLatency(r?.toolCallsPerTurn);
   grain.apiCallsPerTurn = normaliseLatency(r?.apiCallsPerTurn);
+  const phases = r?.phases as Partial<Record<TurnPhase, unknown>> | undefined;
+  for (const phase of TURN_PHASES) {
+    grain.phases[phase] = normaliseLatency(phases?.[phase]);
+  }
   if (r?.toolCallsByName && typeof r.toolCallsByName === "object") {
     for (const [key, value] of Object.entries(r.toolCallsByName)) {
       if (typeof value === "number" && Number.isFinite(value)) {

package/src/storage/sessions.ts

@@ -42,6 +42,8 @@ import {
   type SessionMetrics,
   type SessionState,
   type SessionUsage,
+  TURN_PHASES,
+  type TurnPhase,
 } from "./session-record.js";
 // In-memory cache over the sessions table. Reads serve live references
 // from here; writes go through persist() so each mutation commits.
@@ -365,6 +367,28 @@ export function recordSessionMetrics(
   persist(chatId, session);
 }
 
+/**
+ * Fold one turn's phase timings (ms) into the session's lifetime grain and
+ * today's bucket. Phases the caller could not measure are simply absent.
+ */
+export function recordSessionTurnPhases(
+  chatId: string,
+  phases: Partial<Record<TurnPhase, number>>,
+  day = todayUtc(),
+): void {
+  const session = getSession(chatId);
+  for (const grain of [
+    session.metrics.lifetime,
+    metricBucket(session.metrics, day),
+  ]) {
+    for (const phase of TURN_PHASES) {
+      const value = phases[phase];
+      if (value !== undefined) addLatency(grain.phases[phase], value);
+    }
+  }
+  persist(chatId, session);
+}
+
 export function recordSessionMetricEvent(
   chatId: string,
   event: Partial<MetricsCounterSet> & {

package/src/util/boot-timer.ts

@@ -0,0 +1,31 @@
+/**
+ * Boot phase timer — one entry per awaited startup phase, reported once
+ * the daemon is serving, so "why did it take nine seconds to come up"
+ * has an answer in the log instead of a profiler session.
+ */
+
+const phases: { label: string; ms: number }[] = [];
+
+/** Run one startup phase and remember how long it took. */
+export async function bootPhase<T>(
+  label: string,
+  fn: () => Promise<T> | T,
+): Promise<T> {
+  const startedAt = Date.now();
+  try {
+    return await fn();
+  } finally {
+    phases.push({ label, ms: Date.now() - startedAt });
+  }
+}
+
+/** `4210ms (plugins 120ms, stores 15ms, frontends 300ms, …)` — total is process uptime. */
+export function bootReport(now = Math.round(process.uptime() * 1000)): string {
+  const parts = phases.map((phase) => `${phase.label} ${phase.ms}ms`);
+  return parts.length ? `${now}ms (${parts.join(", ")})` : `${now}ms`;
+}
+
+/** Test seam. */
+export function resetBootPhases(): void {
+  phases.length = 0;
+}

package/src/util/concurrency.ts

@@ -0,0 +1,28 @@
+/**
+ * Bounded-concurrency map: run `fn` over `items` with at most `limit`
+ * in flight, preserving result order. Rejections propagate after the
+ * batch drains so a single failure does not orphan in-flight work.
+ */
+export async function mapConcurrent<T, R>(
+  items: readonly T[],
+  limit: number,
+  fn: (item: T, index: number) => Promise<R>,
+): Promise<R[]> {
+  const results: R[] = new Array(items.length);
+  const errors: unknown[] = [];
+  let next = 0;
+  const worker = async (): Promise<void> => {
+    while (next < items.length) {
+      const index = next++;
+      try {
+        results[index] = await fn(items[index] as T, index);
+      } catch (err) {
+        errors.push(err);
+      }
+    }
+  };
+  const width = Math.max(1, Math.min(limit, items.length));
+  await Promise.all(Array.from({ length: width }, worker));
+  if (errors.length > 0) throw errors[0];
+  return results;
+}