@agentprojectcontext/apx 1.25.0 → 1.27.1

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

@@ -0,0 +1,284 @@
+// Agent CRUD + per-agent memory.
+//   GET  /projects/:pid/agents
+//   GET  /projects/:pid/agents/:slug                — also returns memory.md
+//   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/parser.js";
+import {
+  writeAgentFile,
+  writeVaultAgentFile,
+  removeVaultAgent,
+  restoreVaultAgent,
+  ensureAgentDir,
+} from "../../../core/scaffold.js";
+import { agentToResponse } from "./shared.js";
+
+// Lowercase the patch keys we accept on the vault and turn skills/tools into
+// arrays. The writer takes either case but normalizes; passing this through
+// it keeps the on-disk format consistent.
+const VAULT_PATCH_FIELDS = ["role", "model", "language", "description", "skills", "tools", "is_master"];
+function normalizeVaultPatch(input = {}) {
+  const out = {};
+  for (const k of VAULT_PATCH_FIELDS) {
+    const lower = k;
+    const title = k.charAt(0).toUpperCase() + k.slice(1);
+    const v = input[lower] ?? input[title];
+    if (v === undefined || v === null) continue;
+    if (k === "skills" || k === "tools") {
+      out[title] = Array.isArray(v)
+        ? v.map(String).map((s) => s.trim()).filter(Boolean)
+        : String(v).split(",").map((s) => s.trim()).filter(Boolean);
+    } else {
+      out[title] = v;
+    }
+  }
+  return out;
+}
+
+export function register(app, { projects, project }) {
+  // Vault = global agent templates. Two-layer: bundled defaults shipped with
+  // APX (assets/agent-vault-defaults/) + user overrides/new ones in
+  // ~/.apx/agents/. The user layer wins per slug; tombstones in .removed.json
+  // hide bundled entries. GET merges both with `source` set per item.
+  app.get("/agents/vault", (req, res) => {
+    const includeRemoved = req.query?.include_removed === "1";
+    res.json(readVaultAgents({ includeRemoved }).map((a) => ({
+      ...agentToResponse(a),
+      source: a.source, // "bundled" | "user" | "user-override"
+    })));
+  });
+
+  // Create or replace a vault template (user layer / copy-on-write).
+  app.post("/agents/vault", (req, res) => {
+    const { slug, fields, body = "" } = req.body || {};
+    if (!slug || !/^[a-z][a-z0-9_-]*$/.test(slug)) {
+      return res.status(400).json({ error: "valid slug required" });
+    }
+    try {
+      writeVaultAgentFile(slug, normalizeVaultPatch(fields || {}), body);
+      const created = readVaultAgent(slug);
+      res.status(201).json(created ? agentToResponse(created) : { slug });
+    } catch (e) {
+      res.status(400).json({ error: e.message });
+    }
+  });
+
+  // Patch a vault template. If the slug is bundled-only, copy it to the user
+  // layer first (the writer already does this), then apply the merged fields.
+  app.patch("/agents/vault/:slug", (req, res) => {
+    const { slug } = req.params;
+    const current = readVaultAgent(slug);
+    if (!current) return res.status(404).json({ error: `vault agent ${slug} not found` });
+    const patch = normalizeVaultPatch(req.body?.fields || req.body || {});
+    const mergedFields = { ...(current.fields || {}), ...patch };
+    const body = req.body?.body !== undefined ? String(req.body.body) : (current.body || "");
+    try {
+      writeVaultAgentFile(slug, mergedFields, body);
+      const after = readVaultAgent(slug);
+      res.json(after ? agentToResponse(after) : { slug });
+    } catch (e) {
+      res.status(400).json({ error: e.message });
+    }
+  });
+
+  // Delete a vault template. Tombstones bundled slugs so they stay hidden;
+  // deletes the user-layer file otherwise. POST .../restore lifts a tombstone.
+  app.delete("/agents/vault/:slug", (req, res) => {
+    const { slug } = req.params;
+    const out = removeVaultAgent(slug);
+    if (!out.removed) return res.status(404).json({ error: `vault agent ${slug} not found` });
+    res.json({ ok: true, ...out });
+  });
+
+  app.post("/agents/vault/:slug/restore", (req, res) => {
+    const { slug } = req.params;
+    const out = restoreVaultAgent(slug);
+    if (!out.restored) return res.status(404).json({ error: `slug ${slug} was not tombstoned` });
+    const after = readVaultAgent(slug);
+    res.json({ ok: true, agent: after ? agentToResponse(after) : null });
+  });
+
+  // Import a vault template into a project (copies it to .apc/agents/<slug>.md).
+  app.post("/projects/:pid/agents/import", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const { slug } = req.body || {};
+    if (!slug) return res.status(400).json({ error: "slug required" });
+    const vault = readVaultAgents().find((a) => a.slug === slug);
+    if (!vault) return res.status(404).json({ error: `vault agent ${slug} not found` });
+    if (readAgents(p.path).find((a) => a.slug === slug))
+      return res.status(400).json({ error: `agent ${slug} already exists in project` });
+    try {
+      writeAgentFile(p.path, slug, vault.fields || {}, vault.body || "");
+      ensureAgentDir(p.path, slug);
+      projects.rebuild(p.id);
+      res.status(201).json(agentToResponse(readAgents(p.path).find((a) => a.slug === slug)));
+    } catch (e) {
+      res.status(400).json({ error: e.message });
+    }
+  });
+
+  app.get("/projects/:pid/agents", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    res.json(readAgents(p.path).map(agentToResponse));
+  });
+
+  app.get("/projects/:pid/agents/:slug", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const agents = readAgents(p.path);
+    const a = agents.find((x) => x.slug === req.params.slug);
+    if (!a) return res.status(404).json({ error: "agent not found" });
+    const memPath = path.join(p.path, ".apc", "agents", a.slug, "memory.md");
+    const memory = fs.existsSync(memPath)
+      ? fs.readFileSync(memPath, "utf8")
+      : "";
+    res.json({ ...agentToResponse(a), memory, system: a.body || "" });
+  });
+
+  app.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 } =
+      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` });
+    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,
+      });
+      ensureAgentDir(p.path, slug);
+      projects.rebuild(p.id);
+      const created = readAgents(p.path).find((a) => a.slug === slug);
+      res.status(201).json(agentToResponse(created));
+    } catch (e) {
+      res.status(400).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).
+  app.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);
+    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 || "");
+    try {
+      writeAgentFile(p.path, slug, fields, body);
+      ensureAgentDir(p.path, slug);
+      projects.rebuild(p.id);
+      const updated = readAgents(p.path).find((a) => a.slug === slug);
+      res.json(agentToResponse(updated));
+    } catch (e) {
+      res.status(400).json({ error: e.message });
+    }
+  });
+
+  // Delete an agent: removes .apc/agents/<slug>.md and its data dir.
+  app.delete("/projects/:pid/agents/:slug", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const slug = req.params.slug;
+    const file = path.join(p.path, ".apc", "agents", `${slug}.md`);
+    const dir = path.join(p.path, ".apc", "agents", slug);
+    if (!fs.existsSync(file) && !fs.existsSync(dir))
+      return res.status(404).json({ error: "agent not found" });
+    try {
+      if (fs.existsSync(file)) fs.rmSync(file);
+      if (fs.existsSync(dir)) fs.rmSync(dir, { recursive: true, force: true });
+      projects.rebuild(p.id);
+      res.json({ ok: true });
+    } catch (e) {
+      res.status(400).json({ error: e.message });
+    }
+  });
+
+  // ---- Project-level memory (.apc/memory.md) ----
+  app.get("/projects/:pid/memory", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const memPath = path.join(p.path, ".apc", "memory.md");
+    const body = fs.existsSync(memPath) ? fs.readFileSync(memPath, "utf8") : "";
+    res.json({ body, path: memPath });
+  });
+
+  app.put("/projects/:pid/memory", (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 apcDir = path.join(p.path, ".apc");
+    fs.mkdirSync(apcDir, { recursive: true });
+    const memPath = path.join(apcDir, "memory.md");
+    fs.writeFileSync(memPath, body);
+    try { projects.rebuild(p.id); } catch {}
+    res.json({ ok: true, bytes: Buffer.byteLength(body, "utf8") });
+  });
+
+  // ---- Per-agent memory ----
+  app.get("/projects/:pid/agents/:slug/memory", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const memPath = path.join(
+      p.path,
+      ".apc",
+      "agents",
+      req.params.slug,
+      "memory.md"
+    );
+    if (!fs.existsSync(memPath)) return res.json({ body: "" });
+    res.json({ body: fs.readFileSync(memPath, "utf8") });
+  });
+
+  app.put("/projects/:pid/agents/:slug/memory", (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 dir = path.join(p.path, ".apc", "agents", req.params.slug);
+    fs.mkdirSync(path.join(dir, "sessions"), { recursive: true });
+    const memPath = path.join(dir, "memory.md");
+    fs.writeFileSync(memPath, body);
+    projects.rebuild(p.id);
+    res.json({ ok: true, bytes: Buffer.byteLength(body, "utf8") });
+  });
+}

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

@@ -0,0 +1,52 @@
+// Project-scoped managed files (storagePath/artifacts/).
+//   GET    /projects/:pid/artifacts
+//   POST   /projects/:pid/artifacts
+//   GET    /projects/:pid/artifacts/:name
+//   DELETE /projects/:pid/artifacts/:name
+import {
+  createArtifact,
+  listArtifacts,
+  readArtifact,
+  removeArtifact,
+} from "../../../core/artifacts-store.js";
+
+export function register(app, { project }) {
+  app.get("/projects/:pid/artifacts", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    res.json(listArtifacts(p.storagePath));
+  });
+
+  app.post("/projects/:pid/artifacts", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const { name, content = "" } = req.body || {};
+    if (!name) return res.status(400).json({ error: "name required" });
+    try {
+      const filePath = createArtifact(p.storagePath, name, content);
+      res.status(201).json({ name, path: filePath });
+    } catch (e) {
+      res.status(400).json({ error: e.message });
+    }
+  });
+
+  app.get("/projects/:pid/artifacts/:name", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    try {
+      res.json(readArtifact(p.storagePath, decodeURIComponent(req.params.name)));
+    } catch (e) {
+      res.status(404).json({ error: e.message });
+    }
+  });
+
+  app.delete("/projects/:pid/artifacts/:name", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const ok = removeArtifact(
+      p.storagePath,
+      decodeURIComponent(req.params.name)
+    );
+    res.status(ok ? 204 : 404).end();
+  });
+}

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

@@ -0,0 +1,351 @@
+// Code module API — persistent OpenCode-style coding sessions per project.
+//
+//   GET    /projects/:pid/code/sessions
+//   POST   /projects/:pid/code/sessions                 { title?, model?, mode? }
+//   GET    /projects/:pid/code/sessions/:sid
+//   PATCH  /projects/:pid/code/sessions/:sid            { title?, model?, mode? }
+//   DELETE /projects/:pid/code/sessions/:sid
+//   POST   /projects/:pid/code/sessions/:sid/chat/stream   { prompt }   NDJSON
+//   GET    /projects/:pid/code/sessions/:sid/changes
+//
+// Unlike the stateless super-agent endpoint, these sessions are server-side
+// stateful: the turn handler rebuilds `previousMessages` from the stored
+// transcript, runs the super-agent on the `code` channel (with plan/build mode
+// + per-mode tool gating), then persists the rich assistant turn.
+import { runSuperAgent } from "../super-agent.js";
+import { appendSuperAgentErrorTrace } from "./shared.js";
+import {
+  listCodeSessions,
+  getCodeSession,
+  createCodeSession,
+  updateCodeSession,
+  removeCodeSession,
+  appendTurn,
+} from "../../../core/code-sessions-store.js";
+import { captureBaseline, diffAgainstBaseline, initGitRepo } from "../../../core/git-baseline.js";
+import { loggerFor } from "../../../core/logging.js";
+
+const log = loggerFor("code");
+
+// Read-only tool allowlist for PLAN mode: the agent can explore the repo but
+// not mutate it (no write/edit/shell/delegation/side-effects). Build mode gets
+// the unrestricted set ("*"). Names must match super-agent-tools/index.js.
+const PLAN_TOOLS = [
+  "read_file",
+  "list_files",
+  "search_files",
+  "grep",
+  "glob",
+  "list_projects",
+  "list_agents",
+  "list_mcps",
+  "read_agent_memory",
+  "read_self_memory",
+  "search_sessions",
+  "search_messages",
+  "tail_messages",
+  "list_skills",
+  "load_skill",
+  "list_tasks",
+  "ask_questions",
+  "fetch",
+  "search",
+];
+
+function modeGuidanceFor(mode) {
+  if (mode === "plan") {
+    return [
+      "MODE: plan. Investigate the codebase (read/list/search/grep) and propose",
+      "an approach with the EXACT changes you would make (files + diffs/snippets).",
+      "Do NOT write or edit files and do NOT run mutating shell commands — your",
+      "editing tools are disabled in this mode. End with a concise, ordered plan.",
+    ].join(" ");
+  }
+  return [
+    "MODE: build. Make the changes directly using your file and shell tools",
+    "(read_file, write_file, edit_file, run_shell, …). Do not ask for",
+    "confirmation and do not stop after one step — keep calling tools until the",
+    "entire task is done, then briefly summarize what you changed and why.",
+    "Prefer surgical edits over rewrites.",
+  ].join(" ");
+}
+
+// Build the [{role, content}] history the super-agent expects from the stored
+// rich transcript: flatten each turn's text parts (tool parts are internal).
+function historyFrom(session) {
+  return (session.messages || []).map((m) => ({
+    role: m.role,
+    content: (m.parts || [])
+      .filter((p) => p && p.kind === "text" && p.text)
+      .map((p) => p.text)
+      .join("\n\n")
+      .trim(),
+  }));
+}
+
+// Accumulate stream events into the rich ChatPart shape so the persisted
+// assistant turn matches exactly what the UI rendered live. Mirrors the
+// front-end reducer in hooks/useChat.ts (applyStreamEvent).
+function makeTurnAccumulator() {
+  const parts = [];
+  const notes = [];
+  let model = null;
+  let usage = null;
+  const findTool = (id) => parts.find((p) => p.kind === "tool" && p.id === id);
+  return {
+    apply(ev) {
+      switch (ev?.type) {
+        case "model_start":
+          if (ev.model) model = ev.model;
+          break;
+        case "model_routed":
+          if (ev.model) model = ev.model;
+          if (ev.from_fallback) notes.push(`routing fell back → ${ev.model}`);
+          break;
+        case "engine_failed":
+          notes.push(`engine ${ev.model || "?"} failed → ${ev.retry_with || "retry"}`);
+          break;
+        case "model_retry":
+          notes.push(`retry (${ev.reason || "?"})`);
+          break;
+        case "tools_suppressed":
+          notes.push(`tools suppressed: ${(ev.tools || []).join(", ")}`);
+          break;
+        case "assistant_text":
+          if (ev.text) parts.push({ kind: "text", text: ev.text });
+          break;
+        case "tool_start":
+          if (ev.trace)
+            parts.push({
+              kind: "tool",
+              id: ev.trace.id,
+              tool: ev.trace.tool,
+              args: ev.trace.args,
+              status: "running",
+            });
+          break;
+        case "tool_deduped": {
+          const t = ev.trace && findTool(ev.trace.id);
+          if (t) t.status = "deduped";
+          break;
+        }
+        case "tool_result": {
+          const t = ev.trace && findTool(ev.trace.id);
+          if (t) {
+            t.result = ev.trace.result;
+            const errored =
+              ev.trace.result && typeof ev.trace.result === "object" && ev.trace.result.error;
+            t.status = errored ? "error" : t.status === "deduped" ? "deduped" : "done";
+          }
+          break;
+        }
+        case "final":
+          usage = ev.result?.usage ?? usage;
+          if (!model) model = ev.result?.name || null;
+          break;
+        default:
+          break;
+      }
+    },
+    build() {
+      return { parts, notes, model, usage };
+    },
+  };
+}
+
+export function register(app, { projects, project, config, registries, plugins }) {
+  const findProject = (req, res) => project(req, res);
+
+  // ---- List ----------------------------------------------------------------
+  app.get("/projects/:pid/code/sessions", (req, res) => {
+    const p = findProject(req, res);
+    if (!p) return;
+    res.json({ sessions: listCodeSessions(p.storagePath) });
+  });
+
+  // ---- Create (captures git baseline) --------------------------------------
+  app.post("/projects/:pid/code/sessions", (req, res) => {
+    const p = findProject(req, res);
+    if (!p) return;
+    const { title, model, mode } = req.body || {};
+    let git = captureBaseline(p.path);
+    // No baseline because the project isn't a git repo yet. For real projects
+    // (not the default apx home, id 0) init one so the "changes" diff works —
+    // a coding surface is expected to be version-controlled. Best-effort.
+    if (!git && String(p.id) !== "0") {
+      if (initGitRepo(p.path)) {
+        git = captureBaseline(p.path);
+        log.info(`code: initialized git repo for diff tracking at ${p.path}`, {
+          pid: p.id,
+        });
+      }
+    }
+    const session = createCodeSession(p.storagePath, {
+      projectId: p.id,
+      title,
+      model,
+      mode,
+      git,
+    });
+    res.status(201).json(session);
+  });
+
+  // ---- Get full transcript -------------------------------------------------
+  app.get("/projects/:pid/code/sessions/:sid", (req, res) => {
+    const p = findProject(req, res);
+    if (!p) return;
+    const session = getCodeSession(p.storagePath, req.params.sid);
+    if (!session) return res.status(404).json({ error: "session not found" });
+    res.json(session);
+  });
+
+  // ---- Patch (rename / model / mode) ---------------------------------------
+  app.patch("/projects/:pid/code/sessions/:sid", (req, res) => {
+    const p = findProject(req, res);
+    if (!p) return;
+    const session = updateCodeSession(p.storagePath, req.params.sid, req.body || {});
+    if (!session) return res.status(404).json({ error: "session not found" });
+    res.json(session);
+  });
+
+  // ---- Delete --------------------------------------------------------------
+  app.delete("/projects/:pid/code/sessions/:sid", (req, res) => {
+    const p = findProject(req, res);
+    if (!p) return;
+    const ok = removeCodeSession(p.storagePath, req.params.sid);
+    if (!ok) return res.status(404).json({ error: "session not found" });
+    res.json({ ok: true });
+  });
+
+  // ---- Changes (diff vs baseline) ------------------------------------------
+  app.get("/projects/:pid/code/sessions/:sid/changes", (req, res) => {
+    const p = findProject(req, res);
+    if (!p) return;
+    const session = getCodeSession(p.storagePath, req.params.sid);
+    if (!session) return res.status(404).json({ error: "session not found" });
+    if (!session.git || !session.git.baselineTree) {
+      return res.json({ git: false, files: [] });
+    }
+    try {
+      const files = diffAgainstBaseline(p.path, session.git.baselineTree);
+      res.json({ git: true, files });
+    } catch (e) {
+      res.status(500).json({ error: e.message, git: true, files: [] });
+    }
+  });
+
+  // ---- Streaming turn ------------------------------------------------------
+  app.post("/projects/:pid/code/sessions/:sid/chat/stream", async (req, res) => {
+    const p = findProject(req, res);
+    if (!p) return;
+    const session = getCodeSession(p.storagePath, req.params.sid);
+    if (!session) return res.status(404).json({ error: "session not found" });
+    const { prompt } = req.body || {};
+    if (!prompt) return res.status(400).json({ error: "prompt required" });
+
+    const mode = session.mode === "plan" ? "plan" : "build";
+    const previousMessages = historyFrom(session);
+
+    // Persist the user turn immediately so a crash mid-stream still records it.
+    appendTurn(p.storagePath, session.id, {
+      role: "user",
+      parts: [{ kind: "text", text: prompt }],
+      mode,
+    });
+
+    res.setHeader("content-type", "application/x-ndjson; charset=utf-8");
+    res.setHeader("cache-control", "no-cache, no-transform");
+    res.setHeader("x-accel-buffering", "no");
+    res.flushHeaders?.();
+
+    const send = (event) => res.write(JSON.stringify(event) + "\n");
+    const acc = makeTurnAccumulator();
+    const onEvent = (event) => {
+      acc.apply(event);
+      send(event);
+    };
+
+    try {
+      const saResult = await runSuperAgent({
+        globalConfig: config,
+        projects,
+        plugins,
+        registries,
+        prompt,
+        channel: "code",
+        channelMeta: {
+          projectId: String(p.id),
+          projectName: p.name,
+          projectPath: p.path,
+          mode,
+          modeGuidance: modeGuidanceFor(mode),
+        },
+        previousMessages,
+        overrideModel: session.model || undefined,
+        allowedTools: mode === "plan" ? PLAN_TOOLS : "*",
+        // Coding tasks are multi-step: give the loop a high safety ceiling so it
+        // can chain 20-30+ tools (read → edit → run → verify …) and a real
+        // output budget for substantial code / explanations per turn. The
+        // completion contract (build mode) is what actually keeps it going until
+        // done — maxIters is just the runaway backstop.
+        maxIters: 100,
+        maxTokens: 8192,
+        // Build mode = the model must keep calling tools until it calls `finish`.
+        // Plan mode is read-only investigation that ends with a written plan, so
+        // it keeps the normal "text ends the turn" behavior.
+        completionContract: mode === "build",
+        onEvent,
+      });
+      projects.rebuild(p.id);
+
+      const turn = acc.build();
+      // Persist the final text unless it's already the last text part we
+      // streamed. Previously this only appended when there was NO text part at
+      // all, so a trailing summary that came AFTER a tool call (the model's
+      // closing words) was silently dropped from the stored transcript.
+      if (
+        saResult.text &&
+        !turn.parts.some((p2) => p2.kind === "text" && p2.text === saResult.text)
+      ) {
+        turn.parts.push({ kind: "text", text: saResult.text });
+      }
+      appendTurn(p.storagePath, session.id, {
+        role: "assistant",
+        parts: turn.parts,
+        notes: turn.notes,
+        model: turn.model || saResult.name,
+        mode,
+        usage: saResult.usage || turn.usage,
+      });
+
+      send({
+        type: "final",
+        result: {
+          text: saResult.text,
+          usage: saResult.usage,
+          name: saResult.name,
+          trace: saResult.trace,
+        },
+      });
+      res.end();
+    } catch (e) {
+      log.warn(`code session turn failed: ${e.message}`, {
+        trace_id: req.apxTraceId,
+        sid: session.id,
+      });
+      appendSuperAgentErrorTrace(req, e, {
+        prompt,
+        channel: "code",
+        previousMessages,
+        model: session.model,
+        stream: true,
+      });
+      send({
+        type: "error",
+        trace_id: req.apxTraceId,
+        error: `${e.message} (trace: ${req.apxTraceId})`,
+      });
+      res.end();
+    }
+  });
+}