talon-agent 4.6.1 → 5.0.1

package/src/core/tools/content/memory.ts

@@ -0,0 +1,128 @@
+/**
+ * Memory tools — one typed claim at a time, in band.
+ *
+ * `remember` / `recall` / `forget` are the write path of
+ * docs/memory-persona-plan.md §3.2: a claim costs ~50 tokens and a
+ * transaction instead of a 23 KB file rewrite mid-conversation, and a
+ * restatement is offered back as a supersede candidate rather than
+ * silently becoming a second row.
+ */
+
+import { z } from "zod";
+import type { ToolDefinition } from "../types.js";
+import type { MemoryKind } from "../../../storage/memory.js";
+
+/**
+ * The store's kinds, spelled out here rather than imported.
+ * `core/tools/` holds pure definitions; importing `storage/memory.js`
+ * for one constant would pull SQLite (and `db.ts`'s top-level await)
+ * into every backend that imports the tool registry. The `MemoryKind`
+ * annotation is the compile-time link, and `memory-actions.test.ts`
+ * asserts this list still equals `MEMORY_KINDS` exactly.
+ */
+const MEMORY_KIND_NAMES: readonly [MemoryKind, ...MemoryKind[]] = [
+  "directive",
+  "fact",
+  "state",
+  "episode",
+  "relationship",
+  "reflection",
+];
+
+const kindSchema = z
+  .enum(MEMORY_KIND_NAMES)
+  .describe(
+    "directive = standing instruction; fact = durable and supersedable; state = keyed, replaced on write; episode = dated, decays; relationship = how a person works; reflection = your own diary, never a fact source",
+  );
+
+export const memoryTools: ToolDefinition[] = [
+  {
+    name: "remember",
+    description: `Store one durable claim in long-term memory. Cheap — prefer it to editing memory files.
+
+One claim per call, written as a standalone sentence that will still parse months from now.
+If a near-duplicate already exists the call is REFUSED and lists the matching rows: re-issue with replace_id=<that id> to fold your wording into it (the old row stays readable), or force=true only when the new claim genuinely stands beside the old one.
+subject is who/what the claim is about; it defaults to this chat for episode and relationship. state also needs a key (e.g. "release.status") and replaces that key's live row.`,
+    schema: {
+      kind: kindSchema,
+      text: z
+        .string()
+        .describe(
+          "The claim itself, self-contained and specific (max 4000 chars)",
+        ),
+      subject: z
+        .string()
+        .optional()
+        .describe(
+          "Who or what this is about — a person, a project, a topic. Required except for episode/relationship, which default to this chat.",
+        ),
+      key: z
+        .string()
+        .optional()
+        .describe(
+          'Required for kind="state": lowercase dotted namespace (e.g. "heartbeat.health"). Writing a key replaces its live row.',
+        ),
+      confidence: z
+        .number()
+        .min(0)
+        .max(1)
+        .optional()
+        .describe("How sure you are, 0–1 (default 1)"),
+      replace_id: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe(
+          "Supersede this existing memory with the new text instead of adding a row — the answer to a near-duplicate refusal",
+        ),
+      force: z
+        .boolean()
+        .optional()
+        .describe(
+          "Store anyway despite a near-duplicate. Only when the claims really are distinct.",
+        ),
+    },
+    execute: (params, bridge) => bridge("remember", params),
+    tag: "memory",
+  },
+
+  {
+    name: "recall",
+    description: `Search long-term memory for stored claims — full-text, best match first.
+
+Use it when you need more than the memory already in this prompt, before asking the user to repeat something. Returns lines prefixed with an id you can pass to remember(replace_id) or forget.`,
+    schema: {
+      query: z
+        .string()
+        .describe("Words to search for — names, topics, distinctive phrases"),
+      kind: kindSchema.optional().describe("Restrict to one kind"),
+      limit: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Max rows to return (default and max 20)"),
+    },
+    execute: (params, bridge) => bridge("recall", params),
+    tag: "memory",
+  },
+
+  {
+    name: "forget",
+    description: `Retire a stored memory by id. It goes to the graveyard — readable and revertible, not erased.
+
+The reason is required and is kept with the row. Use this for claims that are wrong or that the user asked you to drop; to correct a claim that is merely out of date, use remember with replace_id so the correction supersedes it.
+A claim can only be retired from a context at least as trusted as the one that recorded it: operator memories are never droppable this way, and a group chat cannot drop what was learned in a DM.`,
+    schema: {
+      id: z.number().int().positive().describe("Memory id, as shown by recall"),
+      reason: z
+        .string()
+        .describe(
+          "Why it is being dropped — required, stored in the audit log",
+        ),
+    },
+    execute: (params, bridge) => bridge("forget", params),
+    tag: "memory",
+  },
+];

package/src/core/tools/{web.ts → content/web.ts}

@@ -8,7 +8,7 @@
  */
 
 import { z } from "zod";
-import type { ToolDefinition } from "./types.js";
+import type { ToolDefinition } from "../types.js";
 
 export const webTools: ToolDefinition[] = [
   {

package/src/core/tools/index.ts

@@ -7,25 +7,26 @@
 
 import type { ToolDefinition, ToolFrontend, ToolTag } from "./types.js";
 
-import { messagingTools } from "./messaging.js";
-import { chatTools } from "./chat.js";
-import { historyTools } from "./history.js";
-import { memberTools } from "./members.js";
-import { mediaTools } from "./media.js";
-import { stickerTools } from "./stickers.js";
-import { schedulingTools } from "./scheduling.js";
-import { triggerTools } from "./triggers.js";
-import { goalTools } from "./goals.js";
-import { scriptTools } from "./scripts.js";
-import { skillTools } from "./skills.js";
-import { webTools } from "./web.js";
-import { adminTools } from "./admin.js";
-import { modelTools } from "./models.js";
-import { meshTools } from "./mesh.js";
-import { crossSendTools } from "./cross-send.js";
-import { whatsappTools } from "./whatsapp.js";
-import { moderationTools } from "./moderation.js";
-import { nativeTools } from "./native.js";
+import { messagingTools } from "./chat/messaging.js";
+import { chatTools } from "./chat/chat.js";
+import { historyTools } from "./chat/history.js";
+import { memberTools } from "./chat/members.js";
+import { mediaTools } from "./chat/media.js";
+import { stickerTools } from "./chat/stickers.js";
+import { schedulingTools } from "./ops/scheduling.js";
+import { triggerTools } from "./ops/triggers.js";
+import { goalTools } from "./ops/goals.js";
+import { memoryTools } from "./content/memory.js";
+import { scriptTools } from "./ops/scripts.js";
+import { skillTools } from "./ops/skills.js";
+import { webTools } from "./content/web.js";
+import { adminTools } from "./ops/admin.js";
+import { modelTools } from "./ops/models.js";
+import { meshTools } from "./ops/mesh.js";
+import { crossSendTools } from "./chat/cross-send.js";
+import { whatsappTools } from "./chat/whatsapp.js";
+import { moderationTools } from "./chat/moderation.js";
+import { nativeTools } from "./ops/native.js";
 
 /** All built-in tool definitions. */
 export const ALL_TOOLS: readonly ToolDefinition[] = [
@@ -38,6 +39,7 @@ export const ALL_TOOLS: readonly ToolDefinition[] = [
   ...schedulingTools,
   ...triggerTools,
   ...goalTools,
+  ...memoryTools,
   ...scriptTools,
   ...skillTools,
   ...webTools,

package/src/core/tools/{admin.ts → ops/admin.ts}

@@ -5,7 +5,7 @@
  * messaging or content. Available on all frontends.
  */
 
-import type { ToolDefinition } from "./types.js";
+import type { ToolDefinition } from "../types.js";
 
 export const adminTools: ToolDefinition[] = [
   {

package/src/core/tools/{bridge.ts → ops/bridge.ts}

@@ -6,8 +6,8 @@
  */
 
 import { Agent, fetch as undiciFetch } from "undici";
-import { isBunRuntime } from "../../util/runtime.js";
-import type { BridgeFunction } from "./types.js";
+import { isBunRuntime } from "../../../util/runtime.js";
+import type { BridgeFunction } from "../types.js";
 
 /** Default wall-clock budget for a bridge action. */
 const DEFAULT_TIMEOUT_MS = 120_000;

package/src/core/tools/{goals.ts → ops/goals.ts}

@@ -10,8 +10,8 @@
  */
 
 import { z } from "zod";
-import type { ToolDefinition } from "./types.js";
-import { chatIdSchema } from "./schemas.js";
+import type { ToolDefinition } from "../types.js";
+import { chatIdSchema } from "../schemas.js";
 
 /**
  * Heartbeat-mode routing: like `send`, every goal tool threads an

package/src/core/tools/{mesh.ts → ops/mesh.ts}

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { ToolDefinition } from "./types.js";
+import type { ToolDefinition } from "../types.js";
 
 /**
  * Device-mesh tools. Deliberately NOT frontend-restricted: the mesh is

package/src/core/tools/{models.ts → ops/models.ts}

@@ -9,7 +9,7 @@
  */
 
 import { z } from "zod";
-import type { ToolDefinition } from "./types.js";
+import type { ToolDefinition } from "../types.js";
 
 export const modelTools: ToolDefinition[] = [
   {

package/src/core/tools/{native.ts → ops/native.ts}

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { ToolDefinition } from "./types.js";
+import type { ToolDefinition } from "../types.js";
 
 /**
  * Native tools — Talon's own shell/filesystem primitives, the replacement

package/src/core/tools/{scheduling.ts → ops/scheduling.ts}

@@ -3,7 +3,7 @@
  */
 
 import { z } from "zod";
-import type { ToolDefinition } from "./types.js";
+import type { ToolDefinition } from "../types.js";
 
 export const schedulingTools: ToolDefinition[] = [
   {

package/src/core/tools/{scripts.ts → ops/scripts.ts}

@@ -10,7 +10,7 @@
  */
 
 import { z } from "zod";
-import type { ToolDefinition } from "./types.js";
+import type { ToolDefinition } from "../types.js";
 
 export const scriptTools: ToolDefinition[] = [
   {

package/src/core/tools/{skills.ts → ops/skills.ts}

@@ -11,7 +11,7 @@
  */
 
 import { z } from "zod";
-import type { ToolDefinition } from "./types.js";
+import type { ToolDefinition } from "../types.js";
 
 export const skillTools: ToolDefinition[] = [
   {

package/src/core/tools/{triggers.ts → ops/triggers.ts}

@@ -9,7 +9,7 @@
  */
 
 import { z } from "zod";
-import type { ToolDefinition } from "./types.js";
+import type { ToolDefinition } from "../types.js";
 
 const TRIGGER_DESCRIPTION = `Create a long-running watcher script. The script runs as a supervised
 subprocess and signals back via stdout or its exit code.

package/src/core/tools/types.ts

@@ -22,6 +22,7 @@ export type ToolTag =
   | "scheduling"
   | "triggers"
   | "goals"
+  | "memory"
   | "scripts"
   | "skills"
   | "web"

package/src/{util → core/vfs}/workspace.ts

@@ -20,8 +20,8 @@ import {
 } from "node:fs";
 import { createHash } from "node:crypto";
 import { join, resolve } from "node:path";
-import { log } from "./log.js";
-import { dirs, files as pathFiles } from "./paths.js";
+import { log } from "../../util/log.js";
+import { dirs, files as pathFiles } from "../../util/paths.js";
 import { listSeedPrompts, readPromptAsset } from "#prompt-assets";
 
 const IDENTITY_SEED = `# Identity

package/src/core/weaver/turn-cpu.ts

@@ -0,0 +1,32 @@
+/**
+ * Per-turn CPU accounting — how much of a turn the daemon itself spends
+ * on a CPU, as opposed to waiting on a model or a chat platform.
+ *
+ * This is the number Phase 0's kill criterion is written against
+ * (docs/ts-migration-plan.md): the TS control plane's share of turn
+ * latency is `turn.cpu_ms / response_latency_ms`, and if that share is
+ * small then a port buys latency nothing. `turn.stream_ms` is the wall
+ * clock over the identical bracket, so the two divide cleanly.
+ *
+ * `process.cpuUsage()` is process-wide, not per-turn: with concurrent
+ * turns each one's delta includes the others' work. That is the honest
+ * upper bound for "what the daemon costs while a turn is in flight", and
+ * it is the direction that matters — a small number stays small.
+ */
+
+import { recordHistogram } from "../../storage/metrics.js";
+
+/**
+ * Bracket a turn's backend stream. Returns the stop function; calling it
+ * records `turn.cpu_ms` (user + system, milliseconds).
+ */
+export function startTurnCpu(): () => void {
+  const startedAt = process.cpuUsage();
+  return () => {
+    const used = process.cpuUsage(startedAt);
+    recordHistogram(
+      "turn.cpu_ms",
+      Math.round((used.user + used.system) / 1000),
+    );
+  };
+}

package/src/core/weaver/weaver.ts

@@ -24,12 +24,15 @@ import type { ContextManager, ExecuteParams, ExecuteResult } from "../types.js";
 import { bus } from "../bus/index.js";
 import { taskTable, type TaskHandle } from "../tasks/index.js";
 import { log, logDebug, logWarn } from "../../util/log.js";
+import { recordHistogram } from "../../storage/metrics.js";
 import { recordSessionTurnPhases } from "../../storage/sessions.js";
 import type { TurnPhase } from "../../storage/session-record.js";
+import { retrieveForTurn, type TurnMemory } from "../memory/turn-retrieval.js";
 import { TalonError } from "../errors.js";
 import { Loom } from "./loom.js";
 import { carryTurnEvents, startShuttleTiming } from "./shuttle.js";
 import type { Thread, ThreadSnapshot } from "./thread.js";
+import { startTurnCpu } from "./turn-cpu.js";
 import { startTypingLoop } from "./typing-loop.js";
 import { resolveWarp } from "./warp-resolver.js";
 
@@ -244,6 +247,7 @@ export class Weaver {
         );
       }
 
+      const memory = resolveTurnMemory(params, phases);
       const stream = backend.chat.runChatTurn({
         chatId: params.chatId,
         model: warp.ref,
@@ -252,11 +256,17 @@ export class Weaver {
         senderHandle: params.senderHandle,
         isGroup: params.isGroup,
         messageId: params.messageId,
+        retrievedMemory: memory?.text,
       });
       const timing = startShuttleTiming();
+      // CPU and wall clock over the same bracket, so `turn.cpu_ms` can be
+      // divided by `turn.stream_ms` (see turn-cpu.ts). Recorded on the
+      // same path `phases.stream` is, so both cover one population.
+      const stopCpu = startTurnCpu();
       const streamStartedAt = Date.now();
       const agentResult = await carryTurnEvents(stream, params.onEvent, timing);
       phases.stream = Date.now() - streamStartedAt;
+      stopCpu();
       phases.delivery = timing.deliveryMs;
       if (timing.firstEventAt !== undefined) {
         phases.firstToken = timing.firstEventAt - streamStartedAt;
@@ -321,11 +331,37 @@ export class Weaver {
   }
 }
 
+/**
+ * This turn's retrieved memory (`core/memory/turn-retrieval.ts`) — off
+ * unless `TALON_MEMORY_STORE=1`, fail-closed, and a pure read: nothing
+ * here may invalidate the frozen system prompt (plan §3.6), because the
+ * block travels in the USER turn, after all cached history.
+ *
+ * The size goes out as `turn.memory_chars` on every turn, zero
+ * included, so the flag's before/after populations are comparable next
+ * to `prompt.memory_chars` (the static core-view tier from #943).
+ */
+function resolveTurnMemory(
+  params: ExecuteParams,
+  phases: Partial<Record<TurnPhase, number>>,
+): TurnMemory | undefined {
+  const startedAt = Date.now();
+  const memory = retrieveForTurn({
+    chatId: params.chatId,
+    text: params.prompt,
+    isGroup: params.isGroup ?? false,
+  });
+  phases.memory = Date.now() - startedAt;
+  recordHistogram("turn.memory_chars", memory?.chars ?? 0);
+  return memory;
+}
+
 /** `queue=12ms warp=3ms ttft=1840ms stream=6200ms delivery=310ms` */
 function formatPhases(phases: Partial<Record<TurnPhase, number>>): string {
   const labels: Record<TurnPhase, string> = {
     queueWait: "queue",
     warpResolve: "warp",
+    memory: "memory",
     firstToken: "ttft",
     stream: "stream",
     delivery: "delivery",

package/src/frontend/discord/admin.ts

@@ -21,7 +21,7 @@ import {
   nextRunAt,
 } from "../../storage/cron.js";
 import { getActiveCount } from "../../core/engine/dispatcher.js";
-import { getPulseStatus } from "../../core/background/pulse.js";
+import { getPulseStatus } from "../../core/background/pulse/pulse.js";
 import { getHealthStatus, getRecentErrors } from "../../util/watchdog.js";
 import { formatDuration, formatModelLabel } from "./render.js";
 import {

package/src/frontend/discord/callbacks/components/backend-select.ts

@@ -21,7 +21,7 @@ import {
 } from "../../../../core/engine/backend-controller/index.js";
 import { resetSession } from "../../../../storage/sessions.js";
 import { clearHistory } from "../../../../storage/history.js";
-import { resetPulseCheckpoint } from "../../../../core/background/pulse.js";
+import { resetPulseCheckpoint } from "../../../../core/background/pulse/pulse.js";
 import { resolveActiveModelForChat } from "../../../../core/models/active-model.js";
 import { logError } from "../../../../util/log.js";
 import { safeSlice } from "../../formatting.js";

package/src/frontend/discord/callbacks/components/effort.ts

@@ -14,7 +14,7 @@ import {
 import {
   getActiveReasoningLevels,
   supportsReasoningLevel,
-} from "../../../shared/reasoning-levels.js";
+} from "../../../presentation/reasoning-levels.js";
 import type { ComponentContext, ComponentInteraction } from "./types.js";
 
 async function selectEffort(

package/src/frontend/discord/callbacks/components/index.ts

@@ -24,7 +24,7 @@
 import { MessageFlags } from "discord.js";
 import type { TalonConfig } from "../../../../core/config/index.js";
 import type { Gateway } from "../../../../core/engine/gateway.js";
-import { deriveNumericChatId } from "../../../../util/chat-id.js";
+import { deriveNumericChatId } from "../../../../core/frontend-runtime/chat-id.js";
 import { logError } from "../../../../util/log.js";
 import {
   isInteractionAllowed,

package/src/frontend/discord/callbacks/components/pulse.ts

@@ -19,7 +19,7 @@ import {
   disablePulse,
   enablePulse,
   isPulseEnabled,
-} from "../../../../core/background/pulse.js";
+} from "../../../../core/background/pulse/pulse.js";
 import type { ComponentContext, ComponentInteraction } from "./types.js";
 
 // ── /pulse "Set interval…" button → opens modal ───────────────────────

package/src/frontend/discord/callbacks/components/settings.ts

@@ -30,7 +30,7 @@ import {
   disablePulse,
   enablePulse,
   isPulseEnabled,
-} from "../../../../core/background/pulse.js";
+} from "../../../../core/background/pulse/pulse.js";
 import { renderSettingsText, EFFORT_DESCRIPTIONS } from "../../render.js";
 import {
   getBackendIdForChat,
@@ -41,7 +41,7 @@ import {
   displayReasoningEffort,
   getActiveReasoningLevels,
   supportsReasoningLevel,
-} from "../../../shared/reasoning-levels.js";
+} from "../../../presentation/reasoning-levels.js";
 import { logError } from "../../../../util/log.js";
 import { safeSlice } from "../../formatting.js";
 import type { ComponentContext, ComponentInteraction } from "./types.js";

package/src/frontend/discord/callbacks/modals.ts

@@ -6,7 +6,10 @@ import { type ModalSubmitInteraction, MessageFlags } from "discord.js";
 import type { TalonConfig } from "../../../core/config/index.js";
 import type { Gateway } from "../../../core/engine/gateway.js";
 import { setChatPulseInterval } from "../../../storage/chat-settings.js";
-import { registerChat, enablePulse } from "../../../core/background/pulse.js";
+import {
+  registerChat,
+  enablePulse,
+} from "../../../core/background/pulse/pulse.js";
 import { isInteractionAllowed } from "../handlers/index.js";
 import { parseInterval, formatDuration } from "../render.js";
 import { logError } from "../../../util/log.js";

package/src/frontend/discord/commands/admin.ts

@@ -12,15 +12,14 @@ import {
 } from "discord.js";
 import type { TalonConfig } from "../../../core/config/index.js";
 import type { Gateway } from "../../../core/engine/gateway.js";
-import { respawnSelf } from "../../../util/respawn.js";
-import { forceDream } from "../../../core/background/dream.js";
+import { respawnSelf } from "../../../core/daemon/respawn.js";
+import { forceDream } from "../../../core/background/dream/index.js";
 import {
   formatDuration,
   renderMetricsMessages,
   renderDoctorMessages,
 } from "../render.js";
 import { collectDoctorReport } from "../../../core/doctor/index.js";
-import { getSoul } from "../../../core/soul/service.js";
 import { getMetrics, getTodayMetrics } from "../../../storage/metrics.js";
 import { handleAdminSubcommand } from "../admin.js";
 import { isAdmin } from "../handlers/index.js";
@@ -130,39 +129,6 @@ export async function handleDoctor(
   }
 }
 
-/**
- * /soul — read-only introspection of the compiled identity. `action:dream`
- * runs the organic maintenance pass and is admin-only. Inert while the soul
- * is disabled, so it is safe to ship dormant.
- */
-export async function handleSoul(
-  i: ChatInputCommandInteraction,
-): Promise<void> {
-  const soul = getSoul();
-  if (!soul.enabled) {
-    await reply(
-      i,
-      "Soul is disabled (set TALON_SOUL_ENABLED to enable).",
-      true,
-    );
-    return;
-  }
-  if (i.options.getString("action") === "dream") {
-    if (!isAdmin(i.user.id)) {
-      await reply(i, "Not authorized.", true);
-      return;
-    }
-    await i.deferReply({ flags: MessageFlags.Ephemeral });
-    await i.editReply("🧠 Soul dreaming...");
-    soul
-      .dream()
-      .then(() => i.editReply("🧠 Soul dream complete."))
-      .catch(() => undefined);
-    return;
-  }
-  await reply(i, suppressMentions(soul.introspect()), true);
-}
-
 export async function handleDream(
   i: ChatInputCommandInteraction,
 ): Promise<void> {

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

@@ -114,17 +114,6 @@ function buildCommandDefinitions(devBuild = false): unknown[] {
       .setName("mesh")
       .setDescription("Ping and list mesh devices")
       .toJSON(),
-    new SlashCommandBuilder()
-      .setName("soul")
-      .setDescription("Inspect the compiled identity")
-      .addStringOption((o) =>
-        o
-          .setName("action")
-          .setDescription("Leave empty to introspect")
-          .setRequired(false)
-          .addChoices({ name: "dream", value: "dream" }),
-      )
-      .toJSON(),
     // /update only exists on developer builds running from a git checkout —
     // a packaged binary has no source tree to pull into, so the command is
     // never registered there (same gate as the Telegram handler).

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

@@ -13,7 +13,7 @@ import {
   renderUsageMessage,
 } from "../render.js";
 import type { TalonConfig } from "../../../core/config/index.js";
-import { collectPlanUsage } from "../../shared/plan-usage-report.js";
+import { collectPlanUsage } from "../../presentation/plan-usage-report.js";
 import { getLoadedPlugins } from "../../../core/plugin/index.js";
 import { getMeshService } from "../../../core/mesh/index.js";
 import type { MeshPingResult } from "../../../core/mesh/service.js";

package/src/frontend/discord/commands/interaction.ts

@@ -4,7 +4,7 @@
  */
 
 import { type ChatInputCommandInteraction, MessageFlags } from "discord.js";
-import { deriveNumericChatId } from "../../../util/chat-id.js";
+import { deriveNumericChatId } from "../../../core/frontend-runtime/chat-id.js";
 import {
   suppressMentions,
   splitMessage,

package/src/frontend/discord/commands/router.ts

@@ -43,7 +43,6 @@ import {
   handleDream,
   handleAdmin,
   handleDoctor,
-  handleSoul,
   handleUpdate,
 } from "./admin.js";
 
@@ -159,8 +158,6 @@ async function routeSlashCommand(
       return handleDoctor(interaction, config);
     case "mesh":
       return handleMesh(interaction);
-    case "soul":
-      return handleSoul(interaction);
     case "update":
       return handleUpdate(interaction, config);
     case "admin":