talon-agent 4.4.0 → 4.6.0

package/src/frontend/native/routes/host.ts

@@ -12,12 +12,14 @@ import type {
   DeviceLocation,
   LogEntry,
   LogLevel,
+  MemoryWhyWire,
   ModelOption,
   PluginItem,
   SearchResult,
   SkillItem,
   ToggleResult,
 } from "../protocol.js";
+import type { MemoryListQuery, MemoryListResult } from "../memory.js";
 import type { ConfigSnapshot } from "../settings.js";
 
 /** Optional attachment references carried alongside a sent message. */
@@ -48,6 +50,13 @@ export type BridgeServerHandlers = {
   ): ClientMessage[];
   /** Full-text search across chats (or one chat when `chatId` is given). */
   search(query: string, chatId?: string): SearchResult[];
+  /**
+   * Live memory rows — a full-text search when `q` is given, else the
+   * ranked listing. Read-only: the bridge exposes no memory writes.
+   */
+  listMemory(query: MemoryListQuery): MemoryListResult;
+  /** One memory row plus its audit trail, or null when no such id. */
+  memoryWhy(id: number): MemoryWhyWire | null;
   /** Fire-and-forget: streams its results back through `broadcast`. */
   send(id: string, text: string, opts?: SendOptions): void;
   /**

package/src/frontend/native/routes/index.ts

@@ -7,6 +7,7 @@ import type { RouteHost } from "./host.js";
 import type { BridgeRoutes } from "./table.js";
 import { preAuthRoutes } from "./pre-auth.js";
 import { chatRoutes } from "./chats.js";
+import { memoryRoutes } from "./memory.js";
 import { modelRoutes } from "./models.js";
 import { daemonRoutes } from "./daemon.js";
 import { meshRoutes } from "./mesh.js";
@@ -15,6 +16,7 @@ export function buildRoutes(host: RouteHost): BridgeRoutes {
   return {
     ...preAuthRoutes(host),
     ...chatRoutes(host),
+    ...memoryRoutes(host),
     ...modelRoutes(host),
     ...daemonRoutes(host),
     ...meshRoutes(host),

package/src/frontend/native/routes/memory.ts

@@ -0,0 +1,34 @@
+import type { RouteHost } from "./host.js";
+import type { BridgeRoutes } from "./table.js";
+import { asPositiveInt } from "./params.js";
+
+export function memoryRoutes(
+  host: RouteHost,
+): Pick<BridgeRoutes, "GET /memory" | "GET /memory/why"> {
+  const { json, handlers: h } = host;
+  return {
+    // ── Memory (read-only) ─────────────────────────────────────────────
+
+    // `q` turns the listing into a search; `kind` narrows either. A bad
+    // kind is a 400 naming the valid ones, not an empty list — a typo
+    // must not look like an empty memory.
+    "GET /memory": ({ res, url }) => {
+      const result = h.listMemory({
+        q: url.searchParams.get("q") ?? undefined,
+        kind: url.searchParams.get("kind") ?? undefined,
+        limit: asPositiveInt(url.searchParams.get("limit")),
+      });
+      return result.ok
+        ? json(res, 200, { rows: result.rows })
+        : json(res, 400, { ok: false, error: result.error });
+    },
+    "GET /memory/why": ({ res, url }) => {
+      const raw = url.searchParams.get("id") ?? "";
+      const id = asPositiveInt(raw);
+      const why = id === undefined ? null : h.memoryWhy(id);
+      return why
+        ? json(res, 200, why)
+        : json(res, 404, { ok: false, error: `No memory with id ${raw}` });
+    },
+  };
+}

package/src/frontend/native/routes/table.ts

@@ -47,6 +47,13 @@ export const BRIDGE_ROUTE_AUTH = {
   "POST /queue": "bearer",
   "GET /history": "bearer",
   "GET /search": "bearer",
+
+  // Memory — read-only. The typed memory store is readable over the
+  // bridge but never writable from it: asserting and dropping stay with
+  // the daemon's own write path.
+  "GET /memory": "bearer",
+  "GET /memory/why": "bearer",
+
   "POST /send": "bearer",
   "POST /upload": "bearer",
   "GET /media": "bearer",

package/src/frontend/telegram/commands/definitions.ts

@@ -44,6 +44,10 @@ export const TELEGRAM_COMMANDS: ReadonlyArray<{
     description: "Environment and native-module health",
   },
   { command: "dream", description: "Force memory consolidation" },
+  {
+    command: "memory",
+    description: "What Talon remembers — list, search, why <id>",
+  },
   { command: "plugins", description: "List loaded plugins" },
   { command: "help", description: "All commands and features" },
 ];

package/src/frontend/telegram/commands/index.ts

@@ -5,6 +5,7 @@
  *   - `definitions` — the TELEGRAM_COMMANDS menu (single source of truth)
  *   - `state`       — shared admin-id holder + admin guard
  *   - `info`        — /start /help /ping /plugins
+ *   - `memory`      — /memory (read-only view of the typed memory store)
  *   - `session`     — /reset /status
  *   - `settings`    — /model /effort /pulse /settings
  *   - `admin`       — /admin /metrics /doctor /dream /soul /restart /update
@@ -19,6 +20,7 @@ import type { Bot } from "grammy";
 import type { TalonConfig } from "../../../core/config/index.js";
 import type { Backend } from "../../../core/agent-runtime/capabilities.js";
 import { registerInfoCommands } from "./info.js";
+import { registerMemoryCommand } from "./memory.js";
 import { registerSessionCommands } from "./session.js";
 import { registerSettingsCommands } from "./settings.js";
 import { registerAdminCommands } from "./admin.js";
@@ -35,6 +37,7 @@ export function registerCommands(
 ): void {
   const deps = { config, gateway };
   registerInfoCommands(bot);
+  registerMemoryCommand(bot);
   registerSessionCommands(bot, deps);
   registerSettingsCommands(bot, deps);
   registerWhatsAppPairingCommand(bot);

package/src/frontend/telegram/commands/info.ts

@@ -50,6 +50,9 @@ export function registerInfoCommands(bot: Bot): void {
         "  /metrics -- aggregate performance metrics (admin)",
         "  /doctor -- environment and native-module health (admin)",
         "  /dream -- force memory consolidation now",
+        // Entity-escaped: this whole message is sent with parse_mode HTML,
+        // so a literal <id> would be read as a tag and 400 the reply.
+        "  /memory -- what Talon remembers; /memory why &lt;id&gt; for provenance",
         "  /ping -- health check with latency",
         "  /mesh -- ping and list companion mesh devices",
         "  /reset -- clear session and start fresh",

package/src/frontend/telegram/commands/memory.ts

@@ -0,0 +1,112 @@
+/**
+ * `/memory` — a read-only window on the typed memory store.
+ *
+ * Four shapes, all reads: the ranked listing, a full-text search, one
+ * row's provenance (`why <id>`) and a per-kind listing. Nothing here
+ * writes: asserting, superseding and dropping are the write path's job
+ * (rollout PR 6), so the operator can always ask what Talon remembers
+ * without the answer being able to change it.
+ *
+ * Gated exactly like `/status` — not at all. The store holds the
+ * operator's own memory, and a read of it is the least privileged thing
+ * a chat can do.
+ *
+ * Every line is model- or user-authored text reaching an HTML-parsed
+ * send, so it goes through `escapeHtml` before it is joined; the reply
+ * is chunked because a listing of 15 rows can outgrow Telegram's
+ * 4096-char cap on its own.
+ */
+
+import type { Bot, Context } from "grammy";
+import { escapeHtml } from "../formatting.js";
+import { replyHtmlChunked } from "../admin/chunked-reply.js";
+import {
+  formatMemory,
+  getMemory,
+  isMemoryKind,
+  listMemories,
+  memoryHistory,
+  searchMemories,
+  MEMORY_KINDS,
+  type MemoryRow,
+} from "../../../storage/memory.js";
+
+/** Rows per reply — a chat listing is a glance, not an export. */
+const LIST_LIMIT = 15;
+
+export function registerMemoryCommand(bot: Bot): void {
+  bot.command("memory", async (ctx: Context) => {
+    const arg = (ctx.match ?? "").toString().trim();
+    await replyHtmlChunked(ctx, renderMemory(arg));
+  });
+}
+
+/** Route the argument to one of the four reads. Returns ready HTML. */
+function renderMemory(arg: string): string {
+  const why = /^why\b\s*(.*)$/is.exec(arg);
+  if (why) return renderWhy(why[1]!.trim());
+  const kind = /^kind\b\s*(.*)$/is.exec(arg);
+  if (kind) return renderKind(kind[1]!.trim());
+  if (!arg)
+    return renderRows(
+      listMemories({ limit: LIST_LIMIT }),
+      "Nothing remembered yet.",
+    );
+  return renderRows(
+    searchMemories(arg, { limit: LIST_LIMIT }),
+    `No memories matching "${arg}".`,
+  );
+}
+
+/** One escaped line per row, or the (escaped) empty-case sentence. */
+function renderRows(rows: MemoryRow[], empty: string): string {
+  if (rows.length === 0) return escapeHtml(empty);
+  return rows.map((row) => escapeHtml(formatMemory(row))).join("\n");
+}
+
+function renderKind(kind: string): string {
+  if (!isMemoryKind(kind))
+    return escapeHtml(
+      `No such kind "${kind}". Valid kinds: ${MEMORY_KINDS.join(", ")}.`,
+    );
+  return renderRows(
+    listMemories({ kind, limit: LIST_LIMIT }),
+    `Nothing remembered under ${kind}.`,
+  );
+}
+
+/**
+ * Provenance for one row: the row itself, the numbers that decide where
+ * it ranks, and its audit trail. Reads by id rather than by the live
+ * listing, so a superseded or dropped row still explains itself.
+ */
+function renderWhy(raw: string): string {
+  const id = Number(raw);
+  if (!raw || !Number.isInteger(id))
+    return escapeHtml(`No memory with id ${raw || "(none given)"}.`);
+  const row = getMemory(id);
+  if (!row) return escapeHtml(`No memory with id ${id}.`);
+  const lines = [
+    escapeHtml(formatMemory(row)),
+    "",
+    escapeHtml(
+      `trust ${row.trust} · confidence ${row.confidence} · hits ${row.hitCount} · salience ${row.salience}`,
+    ),
+    escapeHtml(
+      `created ${isoTime(row.createdAt)} · last seen ${isoTime(row.lastSeenAt)}`,
+    ),
+  ];
+  const history = memoryHistory(row.id);
+  if (history.length > 0) {
+    lines.push("", "<b>History</b>");
+    for (const entry of history) {
+      const reason = entry.reason ? ` — ${entry.reason}` : "";
+      lines.push(escapeHtml(`${isoTime(entry.at)} ${entry.op}${reason}`));
+    }
+  }
+  return lines.join("\n");
+}
+
+function isoTime(ms: number): string {
+  return new Date(ms).toISOString();
+}

package/src/storage/memory.ts

@@ -440,6 +440,14 @@ export function touchMemory(id: number): void {
 
 // ── Reads ───────────────────────────────────────────────────────────────────
 
+/**
+ * The idempotency key a re-import compares against: sha256 of
+ * `kind|subject|key|text`. Re-exported from the repository so
+ * core/memory/import.ts can decide skip-vs-supersede without reaching
+ * past the store (plan §3.1).
+ */
+export const memoryContentHash = repo.contentHash;
+
 /** Any row by id — including superseded and dropped ones. */
 export function getMemory(id: number): MemoryRow | undefined {
   return repo.get(id);

package/src/storage/metrics.ts

@@ -22,6 +22,14 @@ const PHASE_HISTOGRAM: Record<TurnPhase, string> = {
 
 const legacyCounters = new Map<string, number>();
 
+/**
+ * Process-lifetime distributions for values that are not chat-turn
+ * latencies and so have nowhere to live on a session record — currently
+ * `prompt.memory_chars`, the size of the injected memory block, which is
+ * what the `TALON_MEMORY_STORE` before/after comparison reads.
+ */
+const processHistograms = new Map<string, MetricsLatencyAgg>();
+
 export type MetricsSnapshot = {
   counters: Record<string, number>;
   histograms: Record<
@@ -34,6 +42,18 @@ export function incrementCounter(name: string, amount = 1): void {
   legacyCounters.set(name, (legacyCounters.get(name) ?? 0) + amount);
 }
 
+/**
+ * Record one observation of a non-turn distribution. Lifetime-scoped and
+ * in-process, like the legacy counters: it surfaces in `getMetrics()`
+ * (count / avg / min / max), not in the daily rollup.
+ */
+export function recordHistogram(name: string, value: number): void {
+  if (!Number.isFinite(value)) return;
+  const agg = processHistograms.get(name) ?? emptyAgg();
+  mergeAgg(agg, { count: 1, sumMs: value, minMs: value, maxMs: value });
+  processHistograms.set(name, agg);
+}
+
 function addCounter(
   counters: Record<string, number>,
   name: string,
@@ -158,10 +178,14 @@ function buildSnapshot(
 export function getMetrics(): MetricsSnapshot {
   const counters: Record<string, number> = {};
   for (const [key, value] of legacyCounters) addCounter(counters, key, value);
-  return buildSnapshot(
+  const snapshot = buildSnapshot(
     getAllSessions().map(({ info }) => info.metrics.lifetime),
     counters,
   );
+  for (const [name, agg] of processHistograms) {
+    if (agg.count) snapshot.histograms[name] = snapshotAgg(agg);
+  }
+  return snapshot;
 }
 
 /** Today's (UTC) fleet snapshot, aggregated from the sessions' daily
@@ -177,5 +201,6 @@ export function getTodayMetrics(): MetricsSnapshot {
 
 export function resetMetrics(): void {
   legacyCounters.clear();
+  processHistograms.clear();
   resetAllSessionMetrics();
 }