talon-agent 4.6.1 → 5.0.1

package/src/frontend/whatsapp/runtime.ts

@@ -11,7 +11,7 @@
 import type { WASocket } from "baileys";
 import type { TalonConfig } from "../../core/config/index.js";
 import type { Gateway } from "../../core/engine/gateway.js";
-import { bareId } from "./identity.js";
+import { bareId } from "./connection/identity.js";
 
 type WhatsAppSettings = {
   allowedJids: string[];

package/src/index.ts

@@ -3,13 +3,16 @@
  *
  * Dispatches the hidden `_mcp-launch` (MCP supervisor) and `_lua-run`
  * (WASM Lua trigger runner) subcommands BEFORE the app graph loads —
- * both are Talon re-invoking itself (see util/mcp-launcher.ts). The
+ * both are Talon re-invoking itself (see core/mcp-hub/launcher.ts). The
  * dynamic import keeps these helper processes light: they evaluate this
  * shim and their own module, never the backends/frontends/plugins.
  */
 
-import { MCP_LAUNCH_SUBCOMMAND, runSupervisor } from "./util/mcp-launcher.js";
-import { LUA_RUN_SUBCOMMAND, runLuaMain } from "./core/scripting/lua-runner.js";
+import {
+  MCP_LAUNCH_SUBCOMMAND,
+  runSupervisor,
+} from "./core/mcp-hub/launcher.js";
+import { LUA_RUN_SUBCOMMAND, runLuaMain } from "./core/scripts/lua.js";
 
 if (process.argv[2] === MCP_LAUNCH_SUBCOMMAND) {
   await runSupervisor(process.argv.slice(3));

package/src/storage/db.ts

@@ -69,7 +69,7 @@ let db: SqlDatabase | null = null;
  * Column reconciliation runs first: `ALTER TABLE … ADD COLUMN` has no
  * IF NOT EXISTS form, so columns added to already-shipped tables
  * (media_index.content_hash, sessions.metrics,
- * history_messages.attachments) are ensured by attempting the ALTER and
+ * history_messages.attachments, sessions.last_turn_ended_at) are ensured by attempting the ALTER and
  * swallowing the two expected failures — "duplicate column name"
  * (column already there) and "no such table" (fresh database; the
  * CREATE TABLE in schema.sql includes the column).
@@ -100,6 +100,11 @@ function ensureSchema(database: SqlDatabase): void {
   } catch {
     /* duplicate column or no such table — both mean nothing to do */
   }
+  try {
+    database.exec(dbSql.addSessionsLastTurnEndedAtColumn);
+  } catch {
+    /* duplicate column or no such table — both mean nothing to do */
+  }
   database.exec("BEGIN");
   try {
     database.exec(SCHEMA);

package/src/storage/memory.ts

@@ -206,6 +206,25 @@ function similarityQuery(text: string): string {
     .join(" OR ");
 }
 
+/**
+ * The near-duplicate probe, in one place: live rows of the same
+ * kind + subject whose text best matches `text` (bm25 order), with
+ * `excludeId` left out. `assertMemory` excludes the row it just wrote;
+ * a caller probing *before* writing has nothing to exclude and passes
+ * `0`, which is not a valid rowid.
+ */
+function similarRows(
+  kind: MemoryKind,
+  subject: string,
+  text: string,
+  excludeId: number,
+  limit: number,
+): MemoryRow[] {
+  const match = similarityQuery(text);
+  if (!match) return [];
+  return repo.similar(match, kind, subject, excludeId, limit);
+}
+
 /**
  * Load a row that a mutation is about to change, or explain why it
  * can't. Only a live row is mutable: a dropped one is in the graveyard
@@ -280,10 +299,13 @@ export function assertMemory(input: MemoryInput): {
   const row = normalize(input);
   return inTransaction(() => {
     const id = insertWithHistory(row, "assert");
-    const match = similarityQuery(row.text);
-    const similar = match
-      ? repo.similar(match, row.kind, row.subject, id, SIMILAR_LIMIT)
-      : [];
+    const similar = similarRows(
+      row.kind,
+      row.subject,
+      row.text,
+      id,
+      SIMILAR_LIMIT,
+    );
     return { id, similar };
   });
 }
@@ -478,14 +500,43 @@ export function listMemories(opts: MemoryListOptions = {}): MemoryRow[] {
  * input is quoted into a literal FTS5 expression by the shared
  * `ftsQuote` core, so operators and punctuation in a query are matched
  * as text rather than parsed as syntax.
+ *
+ * `match` picks how the query's terms combine:
+ *
+ *   - `"all"` (default) — every term must appear. Right for a search
+ *     someone typed on purpose (`talon memory search`, `/memory`).
+ *   - `"any"` — terms are OR-ed and bm25 ranks, the same expression
+ *     near-duplicate detection already uses. Right for a query that is
+ *     a whole sentence nobody wrote as a query — a chat turn's inbound
+ *     message (`core/memory/turn-retrieval.ts`), where AND-ing every
+ *     word means matching nothing.
  */
 export function searchMemories(
   query: string,
-  opts: { kind?: MemoryKind; limit?: number } = {},
+  opts: { kind?: MemoryKind; limit?: number; match?: "all" | "any" } = {},
 ): MemoryRow[] {
-  const match = ftsQuote(query);
-  if (!match) return [];
-  return repo.searchFts(match, opts.kind, opts.limit ?? DEFAULT_SEARCH_LIMIT);
+  const expr = opts.match === "any" ? similarityQuery(query) : ftsQuote(query);
+  if (!expr) return [];
+  return repo.searchFts(expr, opts.kind, opts.limit ?? DEFAULT_SEARCH_LIMIT);
+}
+
+/**
+ * The near-duplicate candidates a claim *would* report if it were
+ * asserted now — the same FTS probe `assertMemory` runs, without
+ * writing anything.
+ *
+ * This is what lets the write path offer supersede-instead-of-append
+ * before a second row exists (plan §3.2): `remember` probes first, and
+ * only inserts once the caller has either picked a row to supersede or
+ * said the claim really is separate.
+ */
+export function findSimilarMemories(
+  kind: MemoryKind,
+  subject: string,
+  text: string,
+  limit: number = SIMILAR_LIMIT,
+): MemoryRow[] {
+  return similarRows(kind, subject, text, 0, limit);
 }
 
 /** The audit trail for one row, oldest entry first. */

package/src/storage/metrics.ts

@@ -15,6 +15,7 @@ import { emptyPhases, TURN_PHASES, type TurnPhase } from "./session-record.js";
 const PHASE_HISTOGRAM: Record<TurnPhase, string> = {
   queueWait: "turn.queue_wait_ms",
   warpResolve: "turn.warp_resolve_ms",
+  memory: "turn.memory_ms",
   firstToken: "turn.first_token_ms",
   stream: "turn.stream_ms",
   delivery: "turn.delivery_ms",
@@ -30,6 +31,42 @@ const legacyCounters = new Map<string, number>();
  */
 const processHistograms = new Map<string, MetricsLatencyAgg>();
 
+/**
+ * A chat's last cross-turn cache verdict — did the turn's FIRST request
+ * read the previous turn's prefix (`hit`), pay to re-write it (`miss`), or
+ * was nothing cacheable at all (`none`)? Mirrors `CrossTurnVerdict` in
+ * backend/runtime/cache/cache-telemetry.ts, which owns the classification; the
+ * union is restated here because `/status` renders it and frontends may
+ * not import backend/ (.dependency-cruiser.cjs: frontend-not-to-backend).
+ */
+export type CacheVerdict = "hit" | "miss" | "none";
+
+/**
+ * Per-chat last verdict. Process-local and deliberately unpersisted: it
+ * describes the live prefix, which dies with the process anyway, and
+ * `/status` is the only reader. Bounded like the per-chat maps in
+ * cache-telemetry.ts, insertion-ordered eviction.
+ */
+const MAX_TRACKED_CHATS = 256;
+const lastCacheVerdicts = new Map<string, CacheVerdict>();
+
+/** Record the chat's newest cross-turn cache verdict. */
+export function noteCacheVerdict(chatId: string, verdict: CacheVerdict): void {
+  if (
+    lastCacheVerdicts.size >= MAX_TRACKED_CHATS &&
+    !lastCacheVerdicts.has(chatId)
+  ) {
+    const oldest = lastCacheVerdicts.keys().next().value;
+    if (oldest !== undefined) lastCacheVerdicts.delete(oldest);
+  }
+  lastCacheVerdicts.set(chatId, verdict);
+}
+
+/** The chat's last cross-turn verdict, or undefined if none was recorded. */
+export function getCacheVerdict(chatId: string): CacheVerdict | undefined {
+  return lastCacheVerdicts.get(chatId);
+}
+
 export type MetricsSnapshot = {
   counters: Record<string, number>;
   histograms: Record<
@@ -202,5 +239,6 @@ export function getTodayMetrics(): MetricsSnapshot {
 export function resetMetrics(): void {
   legacyCounters.clear();
   processHistograms.clear();
+  lastCacheVerdicts.clear();
   resetAllSessionMetrics();
 }

package/src/storage/repositories/sessions-repo.ts

@@ -42,6 +42,7 @@ type Row = {
   total_response_ms: number;
   last_response_ms: number;
   fastest_response_ms: number | null;
+  last_turn_ended_at: number | null;
   metrics: string | null;
 };
 
@@ -81,6 +82,7 @@ function rowToSession(row: Row): SessionState {
     lastBotMessageId: row.last_bot_message_id ?? undefined,
     sessionName: row.session_name ?? undefined,
     lastModel: row.last_model ?? undefined,
+    lastTurnEndedAt: row.last_turn_ended_at ?? undefined,
   };
 }
 
@@ -120,6 +122,10 @@ export function upsert(chatId: string, session: SessionState): void {
       num(usage?.totalResponseMs),
       num(usage?.lastResponseMs),
       typeof fastest === "number" && Number.isFinite(fastest) ? fastest : null,
+      typeof session.lastTurnEndedAt === "number" &&
+        Number.isFinite(session.lastTurnEndedAt)
+        ? session.lastTurnEndedAt
+        : null,
       JSON.stringify(session.metrics ?? emptyMetrics()),
     );
 }

package/src/storage/session-record.ts

@@ -56,12 +56,14 @@ export type MetricsLatencyAgg = {
 
 /**
  * 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.
+ * chat's FIFO, resolving the warp, retrieving this turn's memory, until
+ * the backend's first event, the whole stream, and the slice of it spent
+ * inside frontend delivery.
  */
 export const TURN_PHASES = [
   "queueWait",
   "warpResolve",
+  "memory",
   "firstToken",
   "stream",
   "delivery",
@@ -104,6 +106,14 @@ export type SessionState = {
   sessionName?: string;
   /** Model used for this session's cost tracking. */
   lastModel?: string;
+  /**
+   * When the last turn of this chat finished (ms epoch), or undefined when
+   * no turn has completed yet. Distinct from `lastActive`, which any
+   * session write moves: this one only ever means "the transcript stopped
+   * growing here", which is what the prompt cache's TTL runs against —
+   * warm iff `now - lastTurnEndedAt < ttl` (docs/cache-economics.md).
+   */
+  lastTurnEndedAt?: number;
 };
 
 export const emptyUsage = (): SessionUsage => ({
@@ -146,6 +156,7 @@ export const emptyLatency = (): MetricsLatencyAgg => ({
 export const emptyPhases = (): MetricsPhaseAggs => ({
   queueWait: emptyLatency(),
   warpResolve: emptyLatency(),
+  memory: emptyLatency(),
   firstToken: emptyLatency(),
   stream: emptyLatency(),
   delivery: emptyLatency(),

package/src/storage/sessions.ts

@@ -480,6 +480,10 @@ export function recordUsage(
     session.usage.estimatedCostUsd += turn.costUsd;
   }
   if (turn.model) session.lastModel = turn.model;
+  // A turn just ended — this is the timestamp the prompt cache ages
+  // against (docs/cache-economics.md). Set on the one seam every backend
+  // funnels a finished turn through, failed-but-billed turns included.
+  session.lastTurnEndedAt = Date.now();
   if (turn.durationMs && turn.durationMs > 0) {
     session.usage.totalResponseMs =
       (session.usage.totalResponseMs || 0) + turn.durationMs;
@@ -580,6 +584,12 @@ export type SessionInfo = {
   lastModel?: string;
   /** True when a turn is currently streaming and `usage` includes its live so-far counts. */
   turnInProgress?: boolean;
+  /**
+   * When this chat's last turn finished (ms epoch), or undefined when none
+   * has. `/status` reports the idle gap from it; `lastActive` can't stand in
+   * because any session write moves that.
+   */
+  lastTurnEndedAt?: number;
 };
 
 export function getSessionInfo(chatId: string): SessionInfo {
@@ -594,6 +604,7 @@ export function getSessionInfo(chatId: string): SessionInfo {
     sessionName: session?.sessionName,
     lastModel: session?.lastModel,
     turnInProgress: liveTurns.has(chatId),
+    lastTurnEndedAt: session?.lastTurnEndedAt,
   };
 }
 
@@ -615,6 +626,7 @@ export function getAllSessions(): Array<{ chatId: string; info: SessionInfo }> {
       sessionName: session.sessionName,
       lastModel: session.lastModel,
       turnInProgress: liveTurns.has(chatId),
+      lastTurnEndedAt: session.lastTurnEndedAt,
     },
   }));
 }

package/src/storage/sql/db.sql

@@ -25,3 +25,8 @@ ALTER TABLE sessions ADD COLUMN metrics TEXT NOT NULL DEFAULT '{"lifetime":{"cou
 -- carry more than one attachment. Fresh databases get the column via
 -- schema.sql.
 ALTER TABLE history_messages ADD COLUMN attachments TEXT
+
+-- name: addSessionsLastTurnEndedAtColumn
+-- Column reconciliation for databases that shipped before the cache-age
+-- signal existed. Fresh databases get the column via schema.sql.
+ALTER TABLE sessions ADD COLUMN last_turn_ended_at INTEGER

package/src/storage/sql/schema.sql

@@ -161,6 +161,10 @@ CREATE TABLE IF NOT EXISTS sessions (
   total_response_ms   REAL    NOT NULL DEFAULT 0,
   last_response_ms    REAL    NOT NULL DEFAULT 0,
   fastest_response_ms REAL,
+  -- When the chat's last turn finished; NULL until one has. Read as the
+  -- prompt cache's age signal (docs/cache-economics.md), which is why it
+  -- is separate from last_active (moved by any session write).
+  last_turn_ended_at  INTEGER,
   metrics             TEXT    NOT NULL DEFAULT '{"lifetime":{"counters":{"queries":0,"toolCalls":0,"turnsWithTools":0,"apiCalls":0,"inputTokens":0,"outputTokens":0,"cacheReadTokens":0,"cacheWriteTokens":0,"failedTurns":0,"flowViolationRetries":0,"flowViolationCapExhausted":0,"trailingTextDropped":0},"latency":{"count":0,"sumMs":0,"minMs":null,"maxMs":0},"toolCallsByName":{},"backend":{},"cacheHitPercent":{"count":0,"sumMs":0,"minMs":null,"maxMs":0},"toolCallsPerTurn":{"count":0,"sumMs":0,"minMs":null,"maxMs":0},"apiCallsPerTurn":{"count":0,"sumMs":0,"minMs":null,"maxMs":0}},"buckets":{}}'
 );
 

package/src/storage/sql/sessions.sql

@@ -7,15 +7,15 @@ INSERT OR REPLACE INTO sessions
    created_at, last_bot_message_id, total_input_tokens, total_output_tokens,
    total_cache_read, total_cache_write, last_prompt_tokens, context_tokens,
    context_window, num_api_calls, estimated_cost_usd, total_response_ms,
-   last_response_ms, fastest_response_ms, metrics)
-VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+   last_response_ms, fastest_response_ms, last_turn_ended_at, metrics)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
 
 -- name: all
 SELECT chat_id, session_id, session_name, last_model, turns, last_active,
        created_at, last_bot_message_id, total_input_tokens, total_output_tokens,
        total_cache_read, total_cache_write, last_prompt_tokens, context_tokens,
        context_window, num_api_calls, estimated_cost_usd, total_response_ms,
-       last_response_ms, fastest_response_ms, metrics
+       last_response_ms, fastest_response_ms, last_turn_ended_at, metrics
 FROM sessions
 
 -- name: remove

package/src/storage/sql/statements.generated.ts

@@ -166,6 +166,10 @@ CREATE TABLE IF NOT EXISTS sessions (
   total_response_ms   REAL    NOT NULL DEFAULT 0,
   last_response_ms    REAL    NOT NULL DEFAULT 0,
   fastest_response_ms REAL,
+  -- When the chat's last turn finished; NULL until one has. Read as the
+  -- prompt cache's age signal (docs/cache-economics.md), which is why it
+  -- is separate from last_active (moved by any session write).
+  last_turn_ended_at  INTEGER,
   metrics             TEXT    NOT NULL DEFAULT '{"lifetime":{"counters":{"queries":0,"toolCalls":0,"turnsWithTools":0,"apiCalls":0,"inputTokens":0,"outputTokens":0,"cacheReadTokens":0,"cacheWriteTokens":0,"failedTurns":0,"flowViolationRetries":0,"flowViolationCapExhausted":0,"trailingTextDropped":0},"latency":{"count":0,"sumMs":0,"minMs":null,"maxMs":0},"toolCallsByName":{},"backend":{},"cacheHitPercent":{"count":0,"sumMs":0,"minMs":null,"maxMs":0},"toolCallsPerTurn":{"count":0,"sumMs":0,"minMs":null,"maxMs":0},"apiCallsPerTurn":{"count":0,"sumMs":0,"minMs":null,"maxMs":0}},"buckets":{}}'
 );
 
@@ -414,6 +418,9 @@ ALTER TABLE sessions ADD COLUMN metrics TEXT NOT NULL DEFAULT '{"lifetime":{"cou
 -- carry more than one attachment. Fresh databases get the column via
 -- schema.sql.
 ALTER TABLE history_messages ADD COLUMN attachments TEXT`,
+  addSessionsLastTurnEndedAtColumn: `-- Column reconciliation for databases that shipped before the cache-age
+-- signal existed. Fresh databases get the column via schema.sql.
+ALTER TABLE sessions ADD COLUMN last_turn_ended_at INTEGER`,
 } as const;
 
 export const goalsSql = {
@@ -657,13 +664,13 @@ export const sessionsSql = {
    created_at, last_bot_message_id, total_input_tokens, total_output_tokens,
    total_cache_read, total_cache_write, last_prompt_tokens, context_tokens,
    context_window, num_api_calls, estimated_cost_usd, total_response_ms,
-   last_response_ms, fastest_response_ms, metrics)
-VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+   last_response_ms, fastest_response_ms, last_turn_ended_at, metrics)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
   all: `SELECT chat_id, session_id, session_name, last_model, turns, last_active,
        created_at, last_bot_message_id, total_input_tokens, total_output_tokens,
        total_cache_read, total_cache_write, last_prompt_tokens, context_tokens,
        context_window, num_api_calls, estimated_cost_usd, total_response_ms,
-       last_response_ms, fastest_response_ms, metrics
+       last_response_ms, fastest_response_ms, last_turn_ended_at, metrics
 FROM sessions`,
   remove: `DELETE FROM sessions WHERE chat_id = ?`,
 } as const;

package/src/storage/sql/turn-meta.sql

@@ -1,4 +1,4 @@
--- Statements for the turn_meta table (see frontend/native/turn-meta.ts).
+-- Statements for the turn_meta table (see frontend/native/turn/turn-meta.ts).
 
 -- name: get
 SELECT meta FROM turn_meta WHERE chat_id = ? AND msg_id = ?

package/src/util/log.ts

@@ -62,7 +62,7 @@ export type LogComponent =
   | "mempalace"
   | "mem0"
   | "playwright"
-  | "soul"
+  | "memory"
   | "stickers"
   | "backend-controller";
 

package/src/util/paths.ts

@@ -116,8 +116,6 @@ export const files = {
   triggers: resolve(TALON_ROOT, "data", "triggers.json"),
   /** Legacy JSON native turn meta (imported into talon.db on first boot) */
   nativeTurnMeta: resolve(TALON_ROOT, "data", "native-turn-meta.json"),
-  /** Soul kernel state: ~/.talon/data/soul.json (overridable via config.soul.path) */
-  soul: resolve(TALON_ROOT, "data", "soul.json"),
   /** Legacy JSON media index (imported into talon.db on first boot) */
   mediaIndex: resolve(TALON_ROOT, "data", "media-index.json"),
   /** Persistent memory: ~/.talon/workspace/memory/memory.md */

package/src/util/runtime.ts

@@ -11,7 +11,7 @@
  *
  * Bun-COMPILED binaries are a third shape detected separately (argv[1]
  * points into the embedded virtual fs) — see the existing `$bunfs`
- * checks at the spawn sites and in `util/mcp-launcher.ts`.
+ * checks at the spawn sites and in `core/mcp-hub/launcher.ts`.
  */
 
 /** True when the current process is executing under the Bun runtime. */