talon-agent 4.6.1 → 5.0.1

package/src/core/engine/gateway-actions/memory.ts

@@ -0,0 +1,335 @@
+/**
+ * Memory — the in-band write path over the typed store: remember /
+ * recall / forget (docs/memory-persona-plan.md §3.2).
+ *
+ * Three rules shape this module, and none of them live in the store:
+ *
+ *   - **Single claim, supersede-candidate.** A `remember` that restates
+ *     something already on file does NOT insert a second row. The FTS
+ *     near-duplicate probe runs first, and a hit comes back as a refusal
+ *     naming the rows to supersede. The caller then either picks one
+ *     (`replace_id`) or declares the claim genuinely separate (`force`).
+ *   - **Trust comes from the chat, not the caller.** Anything learned on
+ *     a multi-party surface is `group_chat` — never pinnable, never in
+ *     the core view (plan §5) — and a `directive` cannot be planted from
+ *     one at all. The tier also gates what a context may *overwrite*:
+ *     a claim may only be superseded or forgotten from a context at its
+ *     own tier or stronger. Without that, both `replace_id` and `forget`
+ *     are escalations — the first because `supersedeMemory` copies the
+ *     old row's trust onto the successor, the second because the store
+ *     drops whatever id it is handed.
+ *   - **Writes never invalidate the prompt cache.** This module must not
+ *     import `core/prompt/invalidation.js`. A `remember` that dropped
+ *     every live session's prompt snapshot would turn a ~50-token claim
+ *     into a 60–90 k cache write (plan §3.6). A fact learned mid-session
+ *     reaches the model through turn retrieval, not the frozen core view.
+ */
+
+import {
+  assertMemory,
+  dropMemory,
+  findSimilarMemories,
+  formatMemory,
+  getMemory,
+  isMemoryKind,
+  replaceStateKey,
+  searchMemories,
+  supersedeMemory,
+  touchMemory,
+  MEMORY_KINDS,
+  type MemoryKind,
+  type MemoryRow,
+  type MemorySource,
+  type MemoryTrust,
+} from "../../../storage/memory.js";
+import { chatScope } from "../../frontend-runtime/chat-id.js";
+import { log } from "../../../util/log.js";
+import type { ActionResult } from "../../types.js";
+import type { SharedActionHandlers } from "./types.js";
+
+/** `source.actor` on every row this path writes — the ownership marker. */
+const REMEMBER_ACTOR = "remember";
+
+/** Kinds whose subject is the chat itself when the caller names none. */
+const CHAT_SCOPED_KINDS: readonly MemoryKind[] = ["episode", "relationship"];
+
+/** Hard ceiling on `recall`, regardless of what the caller asks for. */
+const MAX_RECALL_LIMIT = 20;
+
+const KIND_LIST = MEMORY_KINDS.join(", ");
+
+/**
+ * The trust tier for a claim learned in this chat.
+ *
+ * A group chat is a multi-party surface: any participant can assert
+ * anything, so what is learned there is `group_chat` — a tier the store
+ * refuses to pin and the core view never carries (plan §5). A DM with
+ * the operator, or a local terminal/native session, is the agent writing
+ * for its own principal, so that is `agent`.
+ *
+ * "Group" is read off the canonical chat-id grammar (`chatScope` in
+ * core/frontend-runtime/chat-id.ts), which is the only identity a gateway action holds.
+ * When the grammar cannot tell — Teams' `teams_chat_…` is 1:1 and group
+ * alike — this fails closed to `group_chat`: over-restricting a claim
+ * costs a pin, under-restricting one is a permanent prompt injection.
+ */
+function trustForChat(chatKey: string): MemoryTrust {
+  return chatScope(chatKey) === "dm" ? "agent" : "group_chat";
+}
+
+/** The trust tiers, weakest first. */
+const TRUST_ORDER: readonly MemoryTrust[] = [
+  "group_chat",
+  "user_claim",
+  "agent",
+  "operator",
+];
+
+function trustRank(trust: MemoryTrust): number {
+  const rank = TRUST_ORDER.indexOf(trust);
+  // A tier this module does not know is treated as the strongest, so an
+  // unrecognised row is protected rather than freely overwritten.
+  return rank === -1 ? TRUST_ORDER.length : rank;
+}
+
+/**
+ * Whether a claim made in `context` may overwrite or retire a row
+ * recorded at `row` trust — its own tier or weaker, never stronger.
+ *
+ * This is what keeps `replace_id` from being an escalation:
+ * `supersedeMemory` inherits the old row's frame, trust included, so
+ * without this check a group participant could hand new text to an
+ * `agent` row and have it land live at `agent` trust. `forget` needs the
+ * same guard for the mirror reason — the store drops whatever id it is
+ * given, so the policy has to sit here.
+ */
+function outranks(context: MemoryTrust, row: MemoryTrust): boolean {
+  return trustRank(context) >= trustRank(row);
+}
+
+function fail(error: string): ActionResult {
+  return { ok: false, error };
+}
+
+/** Never let a store error escape as a throw — the gateway wants a result. */
+function attempt(run: () => ActionResult): ActionResult {
+  try {
+    return run();
+  } catch (err) {
+    return fail(err instanceof Error ? err.message : String(err));
+  }
+}
+
+function storedLine(id: number): ActionResult {
+  const row = getMemory(id);
+  return { ok: true, id, line: row ? formatMemory(row) : `#${id}` };
+}
+
+/** Clamp a caller-supplied limit into 1..max, defaulting to max. */
+function clampLimit(raw: unknown, max: number): number {
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 1) return max;
+  return Math.min(Math.floor(n), max);
+}
+
+/** `episode` / `relationship` default to the chat; everything else must say. */
+function resolveSubject(
+  kind: MemoryKind,
+  raw: unknown,
+  chatKey: string,
+): string {
+  const given = raw === undefined ? "" : String(raw).trim();
+  if (given) return given;
+  return CHAT_SCOPED_KINDS.includes(kind) ? chatKey : "";
+}
+
+/** The parts of a `remember` body that survive validation. */
+type RememberClaim = {
+  kind: MemoryKind;
+  subject: string;
+  text: string;
+  trust: MemoryTrust;
+  source: MemorySource;
+  confidence?: number;
+};
+
+function parseClaim(
+  body: Record<string, unknown>,
+  chatKey: string,
+): RememberClaim | ActionResult {
+  const kind = body.kind;
+  if (!isMemoryKind(kind))
+    return fail(
+      `Unknown kind "${String(kind ?? "")}" (expected one of ${KIND_LIST})`,
+    );
+  const text = String(body.text ?? "").trim();
+  if (!text) return fail("Missing text — a memory is one written claim");
+  const subject = resolveSubject(kind, body.subject, chatKey);
+  if (!subject)
+    return fail(`A ${kind} memory needs a subject (who or what it is about)`);
+  const trust = trustForChat(chatKey);
+  if (kind === "directive" && trust !== "agent")
+    return fail(
+      "A directive cannot be recorded from a group chat — durable standing " +
+        "intent only comes from a direct conversation with the operator. " +
+        "Record it as a fact instead, or ask the operator in a DM.",
+    );
+  const confidence =
+    body.confidence === undefined ? undefined : Number(body.confidence);
+  return {
+    kind,
+    subject,
+    text,
+    trust,
+    source: { chat: chatKey, actor: REMEMBER_ACTOR },
+    ...(confidence !== undefined ? { confidence } : {}),
+  };
+}
+
+/** The keyed-state path: a write replaces the live row for that key. */
+function rememberState(
+  body: Record<string, unknown>,
+  claim: RememberClaim,
+): ActionResult {
+  if (body.replace_id !== undefined)
+    return fail(
+      "A state memory replaces the live row for its key — omit replace_id",
+    );
+  const key = String(body.key ?? "").trim();
+  if (!key)
+    return fail("A state memory requires a key (e.g. heartbeat.health)");
+  const id = replaceStateKey(key, claim.text, claim.source, {
+    subject: claim.subject,
+    trust: claim.trust,
+    ...(claim.confidence !== undefined ? { confidence: claim.confidence } : {}),
+    reason: "remember: state",
+  });
+  return storedLine(id);
+}
+
+/** The explicit supersede: fold the new text into an existing live row. */
+function rememberReplacing(
+  replaceId: number,
+  claim: RememberClaim,
+): ActionResult {
+  const target = getMemory(replaceId);
+  if (!target) return fail(`No memory with id ${replaceId}`);
+  if (target.droppedAt !== undefined)
+    return fail(`Memory #${replaceId} is dropped; it cannot be superseded`);
+  if (target.supersededBy !== undefined)
+    return fail(
+      `Memory #${replaceId} is already superseded by #${target.supersededBy}`,
+    );
+  if (!outranks(claim.trust, target.trust))
+    return fail(
+      `Memory #${replaceId} was recorded at ${target.trust} trust; a ${claim.trust} context cannot replace it — record a separate claim instead`,
+    );
+  if (target.kind !== claim.kind)
+    return fail(
+      `Memory #${replaceId} is a ${target.kind}, not a ${claim.kind} — a supersede keeps the row's kind`,
+    );
+  return storedLine(
+    supersedeMemory(replaceId, claim.text, "remember: replaced"),
+  );
+}
+
+/** The refusal that offers supersede-instead-of-append (plan §3.2). */
+function nearDuplicate(similar: MemoryRow[]): ActionResult {
+  return {
+    ok: false,
+    error: `Near-duplicate of #${similar[0]!.id}`,
+    similar: similar.map((row) => formatMemory(row)),
+    hint: "pass replace_id to supersede it, or force: true to store a separate claim",
+  };
+}
+
+function rememberClaim(
+  body: Record<string, unknown>,
+  chatKey: string,
+): ActionResult {
+  const parsed = parseClaim(body, chatKey);
+  if ("ok" in parsed) return parsed;
+  if (parsed.kind === "state") return rememberState(body, parsed);
+
+  if (body.replace_id !== undefined) {
+    const replaceId = Number(body.replace_id);
+    if (!Number.isInteger(replaceId) || replaceId <= 0)
+      return fail(`Invalid replace_id "${String(body.replace_id)}"`);
+    return rememberReplacing(replaceId, parsed);
+  }
+
+  if (body.force !== true) {
+    const similar = findSimilarMemories(
+      parsed.kind,
+      parsed.subject,
+      parsed.text,
+    );
+    if (similar.length > 0) return nearDuplicate(similar);
+  }
+  const { id } = assertMemory(parsed);
+  log("gateway", `remember: [${parsed.kind}] ${parsed.subject} #${id}`);
+  return storedLine(id);
+}
+
+function recallRows(body: Record<string, unknown>): ActionResult {
+  const query = String(body.query ?? "").trim();
+  if (!query) return fail("Missing query");
+  const kind = body.kind;
+  if (kind !== undefined && !isMemoryKind(kind))
+    return fail(
+      `Unknown kind "${String(kind)}" (expected one of ${KIND_LIST})`,
+    );
+  const rows = searchMemories(query, {
+    ...(kind !== undefined ? { kind } : {}),
+    limit: clampLimit(body.limit, MAX_RECALL_LIMIT),
+  });
+  if (rows.length === 0)
+    return { ok: true, rows: [], note: "nothing stored matches" };
+  // A retrieval hit is ranking feedback, not a content change: `touchMemory`
+  // writes no history row, and nothing here invalidates the prompt cache.
+  for (const row of rows) touchMemory(row.id);
+  return { ok: true, rows: rows.map((row) => formatMemory(row)) };
+}
+
+/** Why a context is not allowed to retire this row. */
+function forgetRefusal(
+  id: number,
+  rowTrust: MemoryTrust,
+  context: MemoryTrust,
+): string {
+  // No chat context ever reaches `operator`, so an operator row can only
+  // be retired out of band — name the command rather than stonewalling.
+  if (rowTrust === "operator")
+    return `Memory #${id} is an operator memory — only the operator can forget it (talon memory forget ${id})`;
+  return `Memory #${id} was recorded at ${rowTrust} trust; a ${context} context cannot forget it`;
+}
+
+function forgetRow(
+  body: Record<string, unknown>,
+  chatKey: string,
+): ActionResult {
+  const id = Number(body.id);
+  if (!Number.isInteger(id) || id <= 0)
+    return fail(`Invalid id "${String(body.id ?? "")}"`);
+  const reason = String(body.reason ?? "").trim();
+  if (!reason)
+    return fail(
+      "A reason is required — every drop is auditable and reversible",
+    );
+  const row = getMemory(id);
+  if (!row) return fail(`No memory with id ${id}`);
+  const context = trustForChat(chatKey);
+  if (!outranks(context, row.trust))
+    return fail(forgetRefusal(id, row.trust, context));
+  dropMemory(id, reason);
+  log("gateway", `forget: #${id} (${reason})`);
+  return { ok: true, id, text: `Dropped #${id} to the graveyard: ${reason}` };
+}
+
+export const memoryHandlers: SharedActionHandlers = {
+  remember: (body, _chatId, _backend, chatKey) =>
+    attempt(() => rememberClaim(body, chatKey)),
+  recall: (body) => attempt(() => recallRows(body)),
+  forget: (body, _chatId, _backend, chatKey) =>
+    attempt(() => forgetRow(body, chatKey)),
+};

package/src/core/engine/gateway-actions/native/exec-background.ts

@@ -0,0 +1,129 @@
+/**
+ * `native_bash` with background:true — the detached local launch.
+ *
+ * POSIX-only by contract (own process group, `kill -- -pid` to stop, survives
+ * a daemon restart), with a short settle window so a command that dies
+ * immediately still reports like a normal foreground run.
+ */
+
+import { spawn } from "node:child_process";
+import { closeSync, openSync } from "node:fs";
+import { mkdir, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { renderExec, type Result } from "./results.js";
+
+/** How long a background launch waits to catch fast failures. */
+const BACKGROUND_SETTLE_MS = 1_200;
+/** Where background job output lands (one log file per job). */
+const BACKGROUND_LOG_DIR = join(tmpdir(), "talon-bash");
+
+/**
+ * Launch a command detached from the request cycle: its own process group,
+ * stdout+stderr appended to a per-job log file, tool returns immediately.
+ * This is the sanctioned path for streaming/long-running commands (adb
+ * logcat, dev servers, watchers) that would otherwise burn the whole
+ * foreground timeout and come back "killed".
+ *
+ * A short settle window catches fast failures (typo'd binary, instant
+ * non-zero exit) so those still surface as a normal error instead of a
+ * "started" message pointing at a log with one line in it.
+ */
+export async function bashBackground(
+  cmd: string,
+  cwd: string | undefined,
+): Promise<Result> {
+  // The background contract is POSIX-shaped end to end: detached process
+  // group, `kill -- -pid` to stop, survives daemon restarts. Windows has
+  // none of those (and the CI legs showed the detached writer's output not
+  // reaching the log) — refuse loudly with the native alternative instead
+  // of pretending.
+  if (process.platform === "win32") {
+    return {
+      ok: false,
+      text:
+        "background:true needs POSIX process groups and isn't supported on a Windows " +
+        "daemon host. Run it foreground with a bound command (`timeout 30 …`, `head -n 200`) " +
+        "or start it yourself: `powershell Start-Process -WindowStyle Hidden` with output redirected to a file.",
+    };
+  }
+  try {
+    await mkdir(BACKGROUND_LOG_DIR, { recursive: true });
+  } catch (err) {
+    return {
+      ok: false,
+      text: `Cannot create log dir ${BACKGROUND_LOG_DIR}: ${(err as Error).message}`,
+    };
+  }
+  const slug =
+    cmd
+      .replace(/[^a-zA-Z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .slice(0, 40) || "job";
+  const logPath = join(BACKGROUND_LOG_DIR, `${Date.now()}-${slug}.log`);
+  let fd: number;
+  try {
+    fd = openSync(logPath, "a");
+  } catch (err) {
+    return {
+      ok: false,
+      text: `Cannot open log file ${logPath}: ${(err as Error).message}`,
+    };
+  }
+  // Always detached: the win32 guard above returned already, so this only
+  // runs on POSIX where the job gets its own process group.
+  const child = spawn("bash", ["-c", cmd], {
+    ...(cwd ? { cwd } : {}),
+    env: process.env,
+    detached: true,
+    stdio: ["ignore", fd, fd],
+  });
+  return new Promise((resolvePromise) => {
+    let settled = false;
+    const done = (r: Result) => {
+      if (settled) return;
+      settled = true;
+      try {
+        closeSync(fd);
+      } catch {
+        // parent's dup only; the child keeps its own copy either way
+      }
+      resolvePromise(r);
+    };
+    child.on("error", (err) =>
+      done({ ok: false, text: `Failed to start: ${err.message}` }),
+    );
+    // Fast failure inside the settle window → report it like a normal run.
+    child.on("close", (code) => {
+      void (async () => {
+        let logged = "";
+        try {
+          logged = await readFile(logPath, "utf8");
+        } catch {
+          // log unreadable — report the exit alone
+        }
+        done({
+          ok: (code ?? 0) === 0,
+          text:
+            `Background command exited almost immediately (exit ${code ?? 0}).\n` +
+            renderExec("local", `exit ${code ?? 0}`, logged, "") +
+            `\nFull log: ${logPath}`,
+        });
+      })();
+    });
+    setTimeout(() => {
+      if (settled) return;
+      child.unref();
+      done({
+        ok: true,
+        text: [
+          `🚀 Started in background [local] — pid ${child.pid}.`,
+          `Output (stdout+stderr) → ${logPath}`,
+          `Follow it with read/bash (e.g. \`tail -n 50 ${logPath}\`).`,
+          `Stop it with \`kill -- -${child.pid}\` (whole process group).`,
+          `Unsupervised: it keeps running until it exits or is killed — it even survives a Talon restart.`,
+        ].join("\n"),
+      });
+    }, BACKGROUND_SETTLE_MS);
+  });
+}

package/src/core/engine/gateway-actions/native/exec-remote.ts

@@ -0,0 +1,85 @@
+/**
+ * `native_bash` on a teleported device — dispatched over the mesh exec
+ * channel.
+ *
+ * The command is wrapped so the shell's resulting working directory comes
+ * back in markers and persists across calls (a `cd` carries forward) without
+ * disturbing the real exit code. glob/search reuse this path for their
+ * on-device rg/find/grep fallbacks.
+ */
+
+import { getMeshService } from "../../../mesh/index.js";
+import { getTeleport, setTeleportCwd } from "../../../mesh/teleport.js";
+import { renderExec, type Result } from "./results.js";
+import { shellQuote } from "./shell.js";
+
+/** Same self-correction hint, phrased for a teleported (on-device) run. */
+const TELEPORT_TIMEOUT_HINT =
+  "(Streaming/never-ending commands can't ride a teleported foreground call — " +
+  "background it in-shell instead: `cmd > /tmp/out.log 2>&1 &`, then poll the log " +
+  "with read, or bound the command itself: `logcat -d`, `timeout 30 …`, `head -n 200`.)";
+/** Markers used to recover the post-command working dir from a teleport shell. */
+const CWD_OPEN = "__TALON_CWD__";
+const CWD_CLOSE = "__TALON_CWD_END__";
+
+export async function bashTeleported(
+  chatId: number,
+  deviceId: string,
+  cmd: string,
+  timeoutMs: number,
+): Promise<Result> {
+  const active = await getTeleport(chatId);
+  const cwd = active?.cwd;
+  // Wrap so the resulting working dir is reported back and persists across
+  // calls (a `cd` in `cmd` carries forward), while the real exit code is
+  // preserved. printf can't fail in a way that masks the command's status.
+  const wrapped =
+    `${cwd ? `cd ${shellQuote(cwd)} 2>/dev/null; ` : ""}` +
+    `{ ${cmd}\n}; __talon_rc=$?; ` +
+    `printf '${CWD_OPEN}%s${CWD_CLOSE}' "$(pwd 2>/dev/null)"; exit $__talon_rc`;
+  const dispatched = await getMeshService().dispatchCommand(
+    deviceId,
+    "exec",
+    { cmd: wrapped, timeoutMs },
+    timeoutMs + 5_000,
+  );
+  if ("error" in dispatched) return { ok: false, text: dispatched.error };
+  const { target, result } = dispatched;
+  const data = result.data ?? {};
+  let stdout = typeof data.stdout === "string" ? data.stdout : "";
+  const stderr = typeof data.stderr === "string" ? data.stderr : "";
+  const via =
+    typeof data.via === "string" && data.via ? ` via ${data.via}` : "";
+  const exitCode =
+    typeof data.exitCode === "number" ? data.exitCode : undefined;
+  // Recover + strip the trailing cwd marker.
+  const open = stdout.lastIndexOf(CWD_OPEN);
+  if (open !== -1) {
+    const close = stdout.indexOf(CWD_CLOSE, open);
+    if (close !== -1) {
+      const newCwd = stdout.slice(open + CWD_OPEN.length, close).trim();
+      stdout = stdout.slice(0, open);
+      if (newCwd) await setTeleportCwd(chatId, newCwd);
+    }
+  }
+  if (!result.ok && exitCode === undefined) {
+    return {
+      ok: false,
+      text: result.message ?? `${target.name} could not run the command.`,
+    };
+  }
+  // The device marks a command it had to kill at its own exec budget with
+  // this stderr marker (see the companion's device_exec) — surface the same
+  // self-correction hint the local timeout path gets.
+  const timedOutOnDevice = stderr.includes("[killed: timeout]");
+  const body = renderExec(
+    `${target.name}${via}`,
+    `exit ${exitCode ?? "?"}`,
+    stdout,
+    stderr,
+  );
+  return {
+    ok: exitCode === 0,
+    text: timedOutOnDevice ? `${body}\n${TELEPORT_TIMEOUT_HINT}` : body,
+  };
+}