@agentprojectcontext/apx 1.81.0 → 1.89.1

package/src/core/voice/transcription.js

@@ -33,6 +33,10 @@ export const DEFAULT_LOCAL = {
   language: "auto",
   beam_size: 5,
   idle_minutes: 10,
+  // The daemon re-warms the model inside this window so the first utterance of
+  // the day isn't the one that pays the ~10s load. Set false to let the server
+  // idle out and hand the RAM back instead.
+  keep_warm: true,
   // Long audio (Telegram voice notes > 10 min) can take several minutes on
   // CPU. 20 minutes covers ~60-minute notes on a small int8 model.
   timeout_ms: 20 * 60_000,

package/src/core/voice/tts.js

@@ -13,12 +13,13 @@ import { TTS_TMP_DIR } from "#core/config/paths.js";
 export { TTS_TMP_DIR };
 import { readConfig } from "../config/index.js";
 import {
-  selectTtsEngine,
+  resolveTtsCandidates,
   listAvailableTtsEngines,
   resolveMode,
   resolveChainOrder,
 } from "./engines/index.js";
 import { emotionConfigFor, stripEmotionTags } from "./emotions.js";
+import { logWarn } from "#core/logging.js";
 
 
 
@@ -28,8 +29,11 @@ export function ensureTtsTmpDir() {
 }
 
 /**
- * Generate speech audio for `text`. Throws on real errors. Falls back to mock
- * silently only when provider="auto" AND nothing real is configured.
+ * Generate speech audio for `text`. In chain mode every configured engine is
+ * tried in order until one answers, so a dead local server costs a retry and
+ * not the voice. The returned `provider` says who actually spoke: "mock" means
+ * nothing did and the audio is silence — check it before presenting the result
+ * as speech.
  *
  * @param {object} opts
  * @param {string} opts.text       Text to speak. Required.
@@ -44,6 +48,47 @@ export function ensureTtsTmpDir() {
  * @param {object} [opts.globalConfig]  Pass-in for tests; falls back to readConfig().
  * @returns {Promise<{audio_path, duration_s, mime, provider}>}
  */
+/**
+ * Duration of a PCM WAV, read from its header. Most engines don't report one —
+ * mock and piper were the only two that did, which is how the desktop ended up
+ * able to play its silent placeholder and nothing else — and a player that
+ * doesn't know how long the clip is can't draw a progress bar.
+ *
+ * The chunks are walked rather than read at fixed offsets. Only the canonical
+ * 44-byte layout puts `fmt ` at 12 and `data` at 36; a float32 wav carries a
+ * `fact` chunk between them, and reading offset 40 there lands mid-chunk and
+ * yields a confident wrong answer — a 12.4s clip reported as 3.0s.
+ *
+ * Returns null for anything that isn't a readable RIFF/WAVE (mp3, ogg).
+ */
+function wavDurationSeconds(filePath) {
+  try {
+    const head = Buffer.alloc(4096);
+    const fd = fs.openSync(filePath, "r");
+    const read = fs.readSync(fd, head, 0, head.length, 0);
+    fs.closeSync(fd);
+    if (read < 12) return null;
+    if (head.toString("ascii", 0, 4) !== "RIFF" || head.toString("ascii", 8, 12) !== "WAVE") return null;
+
+    let byteRate = 0;
+    let pos = 12;
+    while (pos + 8 <= read) {
+      const id = head.toString("ascii", pos, pos + 4);
+      const size = head.readUInt32LE(pos + 4);
+      const body = pos + 8;
+      if (id === "fmt " && body + 16 <= read) byteRate = head.readUInt32LE(body + 8);
+      // `data` is the last chunk read: its size is the sample bytes, and by
+      // now `fmt ` has been seen, since a wav that ordered them the other way
+      // would be unplayable everywhere else too.
+      if (id === "data") return byteRate ? size / byteRate : null;
+      pos = body + size + (size % 2); // chunks are word-aligned
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
 export async function synthesize({
   text,
   voice,
@@ -58,29 +103,74 @@ export async function synthesize({
     throw new Error("synthesize: text required");
   }
   const cfg = globalConfig || readConfig() || {};
-  const { provider: selectedProvider, adapter, engineConfig } = await selectTtsEngine({
-    globalConfig: cfg,
-    provider,
-  });
+  const candidates = await resolveTtsCandidates({ globalConfig: cfg, provider });
+  const outDir = ensureTtsTmpDir();
 
-  // Safety net: if the engine that will speak does NOT support inline emotion
-  // tags, scrub any stray [tag] markers so they're never read aloud literally.
-  const speakText = emotionConfigFor(cfg, selectedProvider).enabled
-    ? text
-    : stripEmotionTags(text);
+  // Walk the chain. An engine that throws (local server down, key revoked,
+  // quota) hands the text to the next one — being available and answering are
+  // different questions, and only the request settles the second.
+  let lastError = null;
+  for (const { provider: selectedProvider, adapter, engineConfig } of candidates) {
+    // Safety net: if the engine that will speak does NOT support inline emotion
+    // tags, scrub any stray [tag] markers so they're never read aloud literally.
+    const speakText = emotionConfigFor(cfg, selectedProvider).enabled
+      ? text
+      : stripEmotionTags(text);
+    try {
+      const r = await adapter.synthesize({
+        text: speakText,
+        voice,
+        language,
+        format,
+        style,
+        outDir,
+        config: engineConfig,
+        parentEnginesCfg: cfg.engines,
+        signal,
+      });
+      return {
+        ...r,
+        // Fill in what the engine didn't measure, so every caller sees the same
+        // shape whoever spoke.
+        duration_s: r.duration_s ?? (r.audio_path ? wavDurationSeconds(r.audio_path) : null),
+        provider: selectedProvider || r.provider,
+      };
+    } catch (e) {
+      lastError = e;
+      // An aborted turn is the caller changing its mind, not an engine fault —
+      // trying the next voice would speak a reply nobody is waiting for.
+      if (e?.name === "AbortError" || signal?.aborted) throw e;
+      logWarn("tts", `${selectedProvider} failed — ${e?.message || e}`);
+    }
+  }
+  throw lastError || new Error("synthesize: no TTS engine available");
+}
 
-  const outDir = ensureTtsTmpDir();
-  return adapter.synthesize({
-    text: speakText,
-    voice,
-    language,
-    format,
-    style,
-    outDir,
-    config: engineConfig,
-    parentEnginesCfg: cfg.engines,
-    signal,
-  }).then((r) => ({ ...r, provider: selectedProvider || r.provider }));
+/**
+ * Ask whoever is about to speak to get ready, if they can.
+ *
+ * Only the engine that would actually handle the next synthesize() is warmed —
+ * warming the whole chain would spin up fallbacks that are not going to be
+ * used. Engines with nothing to warm (every cloud API) simply have no warmup()
+ * and are skipped.
+ *
+ * Fire-and-forget by contract: a warmup that fails costs a slower first reply,
+ * never a failed one, so this resolves rather than throws.
+ */
+export async function warmupTts({ globalConfig } = {}) {
+  const cfg = globalConfig || readConfig() || {};
+  const [first] = await resolveTtsCandidates({ globalConfig: cfg });
+  if (!first) return { ok: false, error: "no TTS engine" };
+  if (typeof first.adapter.warmup !== "function") {
+    return { ok: true, provider: first.provider, skipped: "engine has no warmup" };
+  }
+  try {
+    const r = await first.adapter.warmup(first.engineConfig, cfg.engines);
+    return { ok: true, provider: first.provider, ...r };
+  } catch (e) {
+    logWarn("tts", `warmup of ${first.provider} failed — ${e?.message || e}`);
+    return { ok: false, provider: first.provider, error: e?.message || String(e) };
+  }
 }
 
 /** List engines and whether they look usable right now. */

package/src/host/daemon/active-turns.js

@@ -0,0 +1,188 @@
+// In-progress chat turns, so streaming survives the tab that started it.
+//
+// The per-request NDJSON stream belongs to the sender: refresh the page or walk
+// to another chat and it is gone, even though the turn keeps running on the
+// daemon. This registry is the daemon's own record of what is being written
+// right now — the accumulated text plus who/where — so ANY surface can be caught
+// up (via the conversation GET) and then followed live (via the events-ws
+// "turn" frames the chat handlers broadcast). It is pure in-memory runtime
+// state: if the daemon restarts mid-turn the turn is gone anyway.
+//
+// Key is the conversation's identity as the client already addresses it:
+//   project agent  → `${projectId}:conv:${conversationId}`
+//   super-agent    → `${projectId}:thread:${channel}:${threadId}`
+// so a client on that conversation can match a frame without extra plumbing.
+
+let seq = 0;
+const byId = new Map();  // turnId -> record
+const byKey = new Map(); // key -> turnId  (the latest turn on that conversation)
+
+/** Public client shape. Abort hooks and internal keys never leave this module. */
+function publicTurn(rec) {
+  if (!rec) return null;
+  return {
+    turn_id: rec.id,
+    text: rec.text,
+    project_id: rec.project_id ?? null,
+    agent_slug: rec.agent_slug,
+    conversation_id: rec.conversation_id,
+    channel: rec.channel,
+    thread_id: rec.thread_id,
+    model: rec.model,
+    started_at: rec.started_at,
+    // The text alone is not enough to re-open a multi-step turn: it loses the
+    // actual tools and makes a still-working turn look idle. Keep the compact,
+    // render-ready timeline alongside it; abort hooks and private keys remain
+    // inside this module.
+    ...(rec.parts?.length
+      ? {
+          parts: rec.parts.map((part) => {
+            const copy = { ...part };
+            if (copy.streaming === false) delete copy.streaming;
+            return copy;
+          }),
+        }
+      : {}),
+  };
+}
+
+/** Key for a project-agent conversation turn. */
+export function convTurnKey(projectId, conversationId) {
+  return `${projectId}:conv:${conversationId}`;
+}
+/** Key for a super-agent channel-thread turn. */
+export function threadTurnKey(projectId, channel, threadId) {
+  return `${projectId}:thread:${channel}:${threadId}`;
+}
+/** Key for a super-agent chat turn. Roby's web chat has no conversation id —
+ *  its thread IS the channel (the ledger is written per channel+day), so there
+ *  is one live turn per project+channel, exactly as Telegram keys one live turn
+ *  per chat_id. */
+export function superAgentTurnKey(projectId, channel) {
+  return `${projectId}:sa:${channel}`;
+}
+
+/** Begin tracking a turn. `meta` is echoed to clients (agent_slug, model, …),
+ *  except `abort`: a function that stops the run, kept private to this module
+ *  and to abortActiveTurn. */
+export function startActiveTurn(key, meta = {}) {
+  const id = `turn_${Date.now().toString(36)}_${++seq}`;
+  const rec = { id, key, text: "", started_at: new Date().toISOString(), ...meta, parts: [] };
+  byId.set(id, rec);
+  byKey.set(key, id);
+  return rec;
+}
+
+function syncText(rec) {
+  rec.text = rec.parts
+    .filter((part) => part.kind === "text")
+    .map((part) => part.text || "")
+    .join("");
+}
+
+/** Grow the accumulated text as tokens arrive. */
+export function appendActiveTurn(id, delta) {
+  const rec = byId.get(id);
+  if (!rec || !delta) return;
+  const last = rec.parts.at(-1);
+  if (last?.kind === "text" && last.streaming) last.text += delta;
+  else rec.parts.push({ kind: "text", text: delta, streaming: true });
+  syncText(rec);
+}
+
+/** Record the visible work timeline of a live turn. This is deliberately a
+ * small transport shape: text segments plus tool starts/results, never hidden
+ * reasoning or the abort hook. A refresh can therefore show the same tools the
+ * original pane was watching. */
+export function recordActiveTurnEvent(id, event) {
+  const rec = byId.get(id);
+  if (!rec || !event) return;
+  if (event.type === "assistant_text" && event.text) {
+    const last = rec.parts.at(-1);
+    if (last?.kind === "text" && last.streaming) {
+      last.text = event.text;
+      last.streaming = false;
+    } else {
+      rec.parts.push({ kind: "text", text: event.text });
+    }
+    syncText(rec);
+    return;
+  }
+  if (event.type === "tool_start" && event.trace?.id) {
+    rec.parts.push({
+      kind: "tool",
+      id: event.trace.id,
+      tool: event.trace.tool || "tool",
+      args: event.trace.args,
+      status: "running",
+    });
+    return;
+  }
+  if (event.type === "tool_result" && event.trace?.id) {
+    const failed = !!event.trace.result && typeof event.trace.result === "object" && !!event.trace.result.error;
+    const part = rec.parts.findLast((item) => item.kind === "tool" && item.id === event.trace.id);
+    if (part) {
+      part.result = event.trace.result;
+      part.status = failed ? "error" : "done";
+    } else {
+      rec.parts.push({
+        kind: "tool",
+        id: event.trace.id,
+        tool: event.trace.tool || "tool",
+        args: event.trace.args,
+        result: event.trace.result,
+        status: failed ? "error" : "done",
+      });
+    }
+  }
+}
+
+/** Stop tracking. Idempotent — the finally block and an error path both call it. */
+export function endActiveTurn(id) {
+  const rec = byId.get(id);
+  if (!rec) return;
+  byId.delete(id);
+  if (byKey.get(rec.key) === id) byKey.delete(rec.key);
+}
+
+/**
+ * Stop the turn running on that conversation. Returns false when there is
+ * nothing to stop — no live turn, or one registered without an abort hook.
+ *
+ * This is what makes "stop" and "interrupt" real. A client closing its NDJSON
+ * socket deliberately does NOT end the run (that is what lets a refresh catch
+ * up on it), so cancelling has to be said out loud: the surface asks for it,
+ * the run's AbortController is signalled here, and the loop notices at its next
+ * iteration boundary. Same shape Telegram has had all along — one controller
+ * per live conversation, aborted when a newer message says "no, do this
+ * instead" (see core/channels/telegram/dispatch.js).
+ */
+export function abortActiveTurn(key) {
+  const id = byKey.get(key);
+  const rec = id ? byId.get(id) : null;
+  if (!rec || typeof rec.abort !== "function") return false;
+  rec.aborted = true;
+  try {
+    rec.abort();
+  } catch {
+    /* the run is already gone; the caller only needs to know we tried */
+  }
+  return true;
+}
+
+/** The turn currently being written on that conversation, if any — the partial
+ *  a just-arrived client renders before it starts following the live frames. */
+export function getActiveTurnByKey(key) {
+  const id = byKey.get(key);
+  const rec = id ? byId.get(id) : null;
+  return publicTurn(rec);
+}
+
+/** Every live turn, optionally scoped to one project. Used by aggregate list
+ *  surfaces (Inbox / Chats) so they all render the same daemon-owned status. */
+export function listActiveTurns({ projectId } = {}) {
+  const want = projectId === undefined || projectId === null ? null : String(projectId);
+  return [...byId.values()]
+    .filter((rec) => want === null || String(rec.project_id) === want)
+    .map(publicTurn);
+}

package/src/host/daemon/api/admin-config.js

@@ -15,6 +15,8 @@ import {
   mergeRedactedChannels,
 } from "#core/config/redact.js";
 import { collectSecretValues, registerSecretValues } from "#core/config/secret-values.js";
+import { isBlobKey, resolveSuperAgentBlob } from "#core/apc/agent-identity.js";
+import { broadcastSuperAgentAvatar } from "../events-ws.js";
 
 export function register(api, { config, scheduler, plugins }) {
   api.get("/admin/config", (_req, res) => {
@@ -28,6 +30,11 @@ export function register(api, { config, scheduler, plugins }) {
 
   api.patch("/admin/config", (req, res) => {
     const { set, unset } = req.body || {};
+    const avatarTouched = (set && Object.hasOwn(set, "super_agent.icon"))
+      || (Array.isArray(unset) && unset.includes("super_agent.icon"));
+    if (set && Object.hasOwn(set, "super_agent.icon") && !isBlobKey(set["super_agent.icon"])) {
+      return res.status(400).json({ error: "Invalid super-agent avatar" });
+    }
     let cfg;
     try {
       cfg = readConfig();
@@ -64,6 +71,7 @@ export function register(api, { config, scheduler, plugins }) {
     registerSecretValues(collectSecretValues(fresh));
     if (scheduler) scheduler.globalConfig = config;
     if (plugins) plugins.config = config;
+    if (avatarTouched) broadcastSuperAgentAvatar(fresh);
     res.json({ ok: true, config: redact(fresh) });
   });
 
@@ -75,6 +83,7 @@ export function register(api, { config, scheduler, plugins }) {
       res.json({
         enabled: !!sa.enabled,
         name: resolveAgentName(fresh),
+        icon: resolveSuperAgentBlob(fresh),
         model: sa.model || "",
         system: sa.system || "",
         permission_mode: sa.permission_mode || PERMISSION_MODES.PERMISO,

package/src/host/daemon/api/agents.js

@@ -4,10 +4,17 @@
 //   POST /projects/:pid/agents                      — create from slug
 //   GET  /projects/:pid/agents/:slug/memory
 //   PUT  /projects/:pid/agents/:slug/memory
-import fs from "node:fs";
-import path from "node:path";
 import { readAgents, readVaultAgents, readVaultAgent } from "#core/apc/parser.js";
-import { apcAgentFile, apcDir, apcMemoryFile } from "#core/apc/paths.js";
+import {
+  readProjectMemory,
+  writeProjectMemory,
+  projectMemoryPath,
+} from "#core/apc/project-memory.js";
+import {
+  readProjectLocalMemory,
+  writeProjectLocalMemory,
+  projectLocalMemoryPath,
+} from "#core/stores/project-memory.js";
 import {
   writeAgentFile,
   writeVaultAgentFile,
@@ -19,15 +26,14 @@ import {
   ensureAgentRuntimeDir,
   readAgentMemory,
   writeAgentMemory,
-  agentMemoryPath,
-  legacyAgentMemoryPath,
 } from "#core/agent/memory.js";
-import { agentToResponse } from "./shared.js";
+import { createAgent, cloneAgent, setAgentConfig, removeAgent, renameAgent } from "#core/apc/agent-write.js";
+import { agentToResponse, asyncRoute } from "./shared.js";
 import { normalizeVaultPatch } from "#core/apc/agents-vault.js";
-import { PERMISSION_MODES } from "#core/constants/permissions.js";
 import { listConversations } from "#core/stores/conversations.js";
 import { listTasks } from "#core/stores/tasks.js";
 import { listRoutines } from "#core/stores/routines.js";
+import { slugifyName } from "#core/stores/organization.js";
 import { readProjectMessages } from "#core/stores/messages.js";
 
 // Attach a per-agent activity summary ({ threads, records, tasks, heartbeats })
@@ -60,16 +66,6 @@ function attachAgentStats(p, agents) {
   }
 }
 
-// Autonomy mirrors the super-agent permission modes (total/automatico/permiso).
-// An invalid value is dropped rather than persisted so a typo can't silently
-// widen an agent's autonomy.
-const AUTONOMY_VALUES = new Set(Object.values(PERMISSION_MODES));
-function normalizeAutonomy(v) {
-  if (v === undefined) return undefined;
-  if (v === null || v === "") return null;
-  return AUTONOMY_VALUES.has(v) ? v : undefined;
-}
-
 export function register(api, { projects, project }) {
   // Vault = global agent templates. Two-layer: bundled defaults shipped with
   // APX (assets/agent-vault-defaults/) + user overrides/new ones in
@@ -175,34 +171,12 @@ export function register(api, { projects, project }) {
   api.post("/projects/:pid/agents", (req, res) => {
     const p = project(req, res);
     if (!p) return;
-    const {
-      slug, role, model, skills, language, description, tools, is_master,
-      parent, type, area, emoji, autonomy,
-    } = req.body || {};
-    if (!slug) return res.status(400).json({ error: "slug required" });
-    if (!/^[a-z][a-z0-9_-]*$/.test(slug))
-      return res.status(400).json({ error: "invalid slug" });
-    const existing = readAgents(p.path).find((a) => a.slug === slug);
-    if (existing)
-      return res.status(400).json({ error: `agent ${slug} already exists` });
-    const autonomyVal = normalizeAutonomy(autonomy);
+    // Field normalization, avatar pick, slug/type validation and the file write
+    // all live in core (agent-write.js), shared with the super-agent's
+    // create_agent tool so the two surfaces can never drift. The route only
+    // resolves the project, rebuilds the registry, and shapes the response.
     try {
-      writeAgentFile(p.path, slug, {
-        Role: role || null,
-        Model: model || null,
-        Language: language || null,
-        Description: description || null,
-        Skills: skills || [],
-        Tools: tools || [],
-        Master: is_master ? true : null,
-        Parent: parent || null,
-        Type: type || null,
-        Area: area || null,
-        Emoji: emoji || null,
-        Autonomy: autonomyVal || null,
-      });
-      ensureAgentDir(p.path, slug);
-      ensureAgentRuntimeDir(p, slug);
+      const slug = createAgent(p, req.body || {});
       projects.rebuild(p.id);
       const created = readAgents(p.path).find((a) => a.slug === slug);
       res.status(201).json(agentToResponse(created));
@@ -211,41 +185,36 @@ export function register(api, { projects, project }) {
     }
   });
 
+  // Duplicate an agent (frontmatter + prompt + memory) into a fresh "<slug>-n"
+  // whose display Name gains a " (n)" suffix. Clone/naming live in core
+  // (agent-write.js); the route resolves the project, rebuilds, and returns the
+  // new agent so the UI can jump straight to it.
+  api.post("/projects/:pid/agents/:slug/clone", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    try {
+      const newSlug = cloneAgent(p, req.params.slug);
+      projects.rebuild(p.id);
+      const created = readAgents(p.path).find((a) => a.slug === newSlug);
+      res.status(201).json(agentToResponse(created));
+    } catch (e) {
+      const status = /not found/.test(e.message) ? 404 : 400;
+      res.status(status).json({ error: e.message });
+    }
+  });
+
   // Edit an existing agent. Merges provided fields into the AGENT.md
   // frontmatter; `system` rewrites the body (the agent's system prompt).
   api.patch("/projects/:pid/agents/:slug", (req, res) => {
     const p = project(req, res);
     if (!p) return;
     const slug = req.params.slug;
-    const existing = readAgents(p.path).find((a) => a.slug === slug);
-    if (!existing) return res.status(404).json({ error: "agent not found" });
-    const b = req.body || {};
-    const fields = { ...(existing.fields || {}) };
-    const setStr = (key, val) => {
-      if (val === undefined) return;
-      if (val === null || val === "") delete fields[key];
-      else fields[key] = val;
-    };
-    setStr("Role", b.role);
-    setStr("Model", b.model);
-    setStr("Language", b.language);
-    setStr("Description", b.description);
-    setStr("Parent", b.parent);
-    setStr("Type", b.type);
-    setStr("Area", b.area);
-    setStr("Emoji", b.emoji);
-    setStr("Autonomy", normalizeAutonomy(b.autonomy));
-    if (b.skills !== undefined) fields.Skills = Array.isArray(b.skills) ? b.skills : [];
-    if (b.tools !== undefined) fields.Tools = Array.isArray(b.tools) ? b.tools : [];
-    if (b.is_master !== undefined) {
-      if (b.is_master) fields.Master = true;
-      else { delete fields.Master; delete fields.Primary; }
-    }
-    const body = b.system !== undefined ? b.system : (existing.body || "");
+    if (!readAgents(p.path).some((a) => a.slug === slug))
+      return res.status(404).json({ error: "agent not found" });
+    // Field normalization + write live in core (agent-write.js), shared with the
+    // super-agent's configure_agent / set_agent_prompt tools.
     try {
-      writeAgentFile(p.path, slug, fields, body);
-      ensureAgentDir(p.path, slug);
-      ensureAgentRuntimeDir(p, slug);
+      setAgentConfig(p, slug, req.body || {});
       projects.rebuild(p.id);
       const updated = readAgents(p.path).find((a) => a.slug === slug);
       res.json(agentToResponse(updated));
@@ -254,34 +223,59 @@ export function register(api, { projects, project }) {
     }
   });
 
+  // Rename an agent's slug — moves its .apc/agents/<slug>.md and runtime dir and
+  // repoints every live reference to it (child `Parent`, routines, group
+  // rosters, tasks, deliveries, code sessions, telegram routes, the RAG scope).
+  // Distinct from PATCH on purpose: it's an irreversible file move and it
+  // changes the resource URL, so the UI must navigate to the returned slug
+  // rather than revalidate in place. The new slug can be sent raw (`{ slug }`)
+  // or derived from a name (`{ name }`) — the caller-side slugify is mirrored
+  // here so either surface yields the same key. The whole registry goes in so
+  // the sweep can reach rooms hosted by ANOTHER project that include this agent.
+  api.post("/projects/:pid/agents/:slug/rename", asyncRoute(async (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const body = req.body || {};
+    const target = body.slug ? String(body.slug) : slugifyName(body.name || "");
+    if (!target || !/^[a-z][a-z0-9_-]*$/.test(target)) {
+      return res.status(400).json({ error: "valid target slug required" });
+    }
+    try {
+      const finalSlug = await renameAgent(p, req.params.slug, target, { projects: projects.list() });
+      projects.rebuild(p.id);
+      const updated = readAgents(p.path).find((a) => a.slug === finalSlug);
+      res.json(agentToResponse(updated));
+    } catch (e) {
+      const status = /not found/.test(e.message) ? 404 : 400;
+      res.status(status).json({ error: e.message });
+    }
+  }));
+
   // Delete an agent: removes .apc/agents/<slug>.md and runtime data dir.
   api.delete("/projects/:pid/agents/:slug", (req, res) => {
     const p = project(req, res);
     if (!p) return;
-    const slug = req.params.slug;
-    const file = apcAgentFile(p.path, slug);
-    const runtimeDir = path.dirname(agentMemoryPath(p, slug));
-    const legacyDir = path.dirname(legacyAgentMemoryPath(p.path, slug));
-    if (!fs.existsSync(file) && !fs.existsSync(runtimeDir) && !fs.existsSync(legacyDir))
-      return res.status(404).json({ error: "agent not found" });
     try {
-      if (fs.existsSync(file)) fs.rmSync(file);
-      if (fs.existsSync(runtimeDir)) fs.rmSync(runtimeDir, { recursive: true, force: true });
-      if (fs.existsSync(legacyDir)) fs.rmSync(legacyDir, { recursive: true, force: true });
+      removeAgent(p, req.params.slug);
       projects.rebuild(p.id);
       res.json({ ok: true });
     } catch (e) {
-      res.status(400).json({ error: e.message });
+      const status = /not found/.test(e.message) ? 404 : 400;
+      res.status(status).json({ error: e.message });
     }
   });
 
-  // ---- Project-level memory (.apc/memory.md) ----
+  // ---- Project-level memory ----
+  // Two files, one boundary: `.apc/memory.md` is committed and only a person
+  // writes it (core/apc/project-memory.js); `~/.apx/projects/<id>/memory.md` is
+  // local, never committed, and is what the `remember` tool appends to
+  // (core/stores/project-memory.js). Both are served here so the Memories screen
+  // can show them side by side — a memory nothing displays is the bug this pair
+  // of routes exists to prevent.
   api.get("/projects/:pid/memory", (req, res) => {
     const p = project(req, res);
     if (!p) return;
-    const memPath = apcMemoryFile(p.path);
-    const body = fs.existsSync(memPath) ? fs.readFileSync(memPath, "utf8") : "";
-    res.json({ body, path: memPath });
+    res.json({ body: readProjectMemory(p.path), path: projectMemoryPath(p.path) });
   });
 
   api.put("/projects/:pid/memory", (req, res) => {
@@ -290,11 +284,26 @@ export function register(api, { projects, project }) {
     const { body } = req.body || {};
     if (typeof body !== "string")
       return res.status(400).json({ error: "body must be string" });
-    fs.mkdirSync(apcDir(p.path), { recursive: true });
-    const memPath = apcMemoryFile(p.path);
-    fs.writeFileSync(memPath, body);
+    const { bytes } = writeProjectMemory(p.path, body);
     try { projects.rebuild(p.id); } catch {}
-    res.json({ ok: true, bytes: Buffer.byteLength(body, "utf8") });
+    res.json({ ok: true, bytes });
+  });
+
+  // The local half — agent-written, never committed.
+  api.get("/projects/:pid/memory/local", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    res.json({ body: readProjectLocalMemory(p), path: projectLocalMemoryPath(p) });
+  });
+
+  api.put("/projects/:pid/memory/local", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const { body } = req.body || {};
+    if (typeof body !== "string")
+      return res.status(400).json({ error: "body must be string" });
+    const { bytes } = writeProjectLocalMemory(p, body);
+    res.json({ ok: true, bytes });
   });
 
   // ---- Per-agent memory ----