Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

33.6 KB
Raw Blame
/**
 * The Memory routes (agent_state/memory/).
 *
 * Reading and curating:
 * - The overview reports the Agent-level switch and one entry per scope, the user scope first
 *   (created on demand for an Agent that predates Memory; a Workspace key with no directory is
 *   still a 404), accepting a key that starts with an underscore.
 * - Topic files are listed and read with their frontmatter (the `.workspace` marker and the
 *   MEMORY.md index are not topic files, under any casing), a non-ASCII one included; deleting
 *   one prunes its index lines and leaves the others; traversal, non-Markdown names, a symlinked
 *   topic file or scope and an unknown Workspace are refused.
 * - The switch and the memory prompts round-trip through the Agent config without touching a
 *   file; a template missing the {{MEMORY}} placeholder is reported and fixed on request; the
 *   Agent list counts memories across scopes minus the indexes.
 * - A non-member gets 404 on every route.
 *
 * Moving a scope (export/import):
 * - An export carries every topic file and the index as one attachment (the user scope too, with
 *   no workspace path) and imports into another scope.
 * - Import defaults to skip; overwrite and replace need confirmation that names what would be
 *   lost, unless nothing would be; replace deletes what the document does not carry and prunes
 *   the index.
 * - The untrusted document is checked whole before anything is written: a path-like name, a
 *   non-text entry, absurd counts or sizes, a foreign or future format; no temporary file stays.
 * - Any member exports, only the owner imports, and a non-member learns nothing.
 *
 * One app for the file and one Project per describe; every case works in a plain Agent of its
 * own.
 */
import fs from "node:fs/promises";
import path from "node:path";
import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
import { MEMORY_INDEX_FILENAME, USER_SCOPE_KEY, memoryDir, memoryScopeDir } from "@adelie/core";
import type {
  AgentConfigResponse,
  MemoryFileResponse,
  MemoryFilesResponse,
  MemoryImportMode,
  MemoryImportResponse,
  MemoryOverviewResponse,
  MemoryScopeExport,
  MemoryTransferFile,
  ProjectCreateResponse,
} from "../src/api/types.js";
import { apiClient, canCreateSymlink, createTestApp, provisionUser } from "./helpers.js";
import type { TestApp } from "./helpers.js";

// Symlink creation needs a privilege or Developer Mode on Windows; canCreateSymlink()
// probes once and caches, so these cases still run where the capability exists.
const itWithSymlinks = it.skipIf(!canCreateSymlink());

const WORKSPACE_KEY = "my-app-a81f32c4";
// The `type:` line is the retired field earlier files may still carry — listing must ignore it.
const TOPIC = `---
name: testing-conventions
description: how tests are run here
type: feedback
updated_at: 2026-08-07
---

- Integration tests talk to a real database.
`;

/** The file's app and its three users; each describe below works in a Project of its own. */
let t: TestApp;
let owner: ReturnType<typeof apiClient>;
let member: ReturnType<typeof apiClient>;
let outsider: ReturnType<typeof apiClient>;

beforeAll(async () => {
  t = await createTestApp();
  const a = await provisionUser(t.app, "owner_a");
  const b = await provisionUser(t.app, "member_b");
  const c = await provisionUser(t.app, "outsider_c");
  owner = apiClient(t.app, a.cookie);
  member = apiClient(t.app, b.cookie);
  outsider = apiClient(t.app, c.cookie);
});
afterAll(async () => {
  await t.cleanup();
});

describe("memory api", () => {
  let projectId: string;
  let memoryPath: string;
  let configPath: string;
  /** The Workspace Memory directory a Session would have created. */
  let wsDir: string;

  // Every case reads and writes the Memory of a plain Agent of its own, in the one Project.
  let agentId: string;
  let agents = 0;
  beforeAll(async () => {
    const created = (await (
      await owner.post("/api/projects", { projectId: "owner_a-memory", name: "memory project" })
    ).json()) as ProjectCreateResponse;
    projectId = created.project.projectId;
  });
  beforeEach(async () => {
    agents += 1;
    agentId = `memory_${agents}`;
    const made = await owner.post(`/api/projects/${projectId}/agents`, { agentId });
    expect(made.status, await made.text()).toBe(201);
    memoryPath = `/api/projects/${projectId}/agents/${agentId}/memory`;
    configPath = `/api/projects/${projectId}/agents/${agentId}/config`;
    wsDir = memoryScopeDir(t.root, projectId, agentId, WORKSPACE_KEY);
    await fs.mkdir(wsDir, { recursive: true });
    await fs.writeFile(path.join(wsDir, ".workspace"), "/home/dev/my-app\n", "utf8");
  });

  const filesPath = (key = WORKSPACE_KEY) => `${memoryPath}/scopes/${key}/files`;

  it("overview reports the switch, the user scope, and one entry per Workspace", async () => {
    await fs.writeFile(path.join(wsDir, "testing-conventions.md"), TOPIC, "utf8");

    const body = (await (await owner.get(memoryPath)).json()) as MemoryOverviewResponse;
    expect(body.enabled).toBe(true);
    // A freshly created Agent gets the current default template, which carries {{MEMORY}}.
    expect(body.templateHasMemory).toBe(true);
    expect(body.memoryDir).toBe(memoryDir(t.root, projectId, agentId));
    expect(body.scopes).toHaveLength(2);
    // The user scope leads the list (the Agent was initialized with it on disk).
    expect(body.scopes[0]).toMatchObject({
      scopeKey: USER_SCOPE_KEY,
      kind: "user",
      fileCount: 0,
    });
    expect(body.scopes[0]?.workspacePath).toBeUndefined();
    expect(body.scopes[1]).toMatchObject({
      scopeKey: WORKSPACE_KEY,
      kind: "workspace",
      workspacePath: "/home/dev/my-app",
      fileCount: 1,
    });
    expect(body.scopes[1]?.updatedAt).toBeTruthy();
  });

  it("does not count a scope's MEMORY.md index as a topic file", async () => {
    await fs.writeFile(path.join(wsDir, MEMORY_INDEX_FILENAME), "- [t](t.md) — hook\n", "utf8");
    const list = (await (await owner.get(filesPath())).json()) as MemoryFilesResponse;
    expect(list.files).toHaveLength(0);
    // Nor can the index be fetched or deleted as a topic file — under any casing, since
    // macOS/Windows resolve memory.md to MEMORY.md.
    expect((await owner.get(`${filesPath()}/${MEMORY_INDEX_FILENAME}`)).status).toBe(400);
    expect((await owner.delete(`${filesPath()}/${MEMORY_INDEX_FILENAME}`)).status).toBe(400);
    expect((await owner.get(`${filesPath()}/memory.md`)).status).toBe(400);
    expect((await owner.delete(`${filesPath()}/Memory.Md`)).status).toBe(400);
  });

  it("accepts a workspace key starting with an underscore, as core generates for _site-style directories", async () => {
    const key = "_site-1a2b3c4d";
    const dir = memoryScopeDir(t.root, projectId, agentId, key);
    await fs.mkdir(dir, { recursive: true });
    await fs.writeFile(path.join(dir, "notes.md"), "---\nname: n\n---\nbody\n", "utf8");
    const list = (await (await owner.get(filesPath(key))).json()) as MemoryFilesResponse;
    expect(list.files.map((f) => f.name)).toEqual(["notes.md"]);
  });

  it("lists, reads and deletes a non-ASCII topic file the model wrote", async () => {
    const name = "项目背景.md";
    await fs.writeFile(path.join(wsDir, name), "---\nname: 项目背景\n---\n正文\n", "utf8");
    const list = (await (await owner.get(filesPath())).json()) as MemoryFilesResponse;
    expect(list.files.map((f) => f.name)).toContain(name);
    const encoded = `${filesPath()}/${encodeURIComponent(name)}`;
    expect((await owner.get(encoded)).status).toBe(200);
    expect((await owner.delete(encoded)).status).toBe(204);
    expect(await fs.readdir(wsDir)).not.toContain(name);
  });

  itWithSymlinks("neither lists nor follows a symlinked topic file", async () => {
    const outside = path.join(t.root, `${agentId}-outside-secret.txt`);
    await fs.writeFile(outside, "secret", "utf8");
    await fs.symlink(outside, path.join(wsDir, "leak.md"));
    const list = (await (await owner.get(filesPath())).json()) as MemoryFilesResponse;
    expect(list.files.map((f) => f.name)).not.toContain("leak.md");
    // Direct addressing must not follow the link either.
    expect((await owner.get(`${filesPath()}/leak.md`)).status).toBe(404);
  });

  itWithSymlinks("404s a scope directory smuggled in as a symlink", async () => {
    const outside = path.join(t.root, `${agentId}-outside-dir`);
    await fs.mkdir(outside, { recursive: true });
    await fs.writeFile(path.join(outside, "loot.md"), "---\nname: l\n---\nx\n", "utf8");
    await fs.symlink(outside, memoryScopeDir(t.root, projectId, agentId, "evil-12345678"));
    expect((await owner.get(filesPath("evil-12345678"))).status).toBe(404);
  });

  it("lists the user scope of an Agent that predates Memory, creating it on demand", async () => {
    // A Workspace directory comes from a Session, but the user scope belongs to the Agent.
    await fs.rm(memoryScopeDir(t.root, projectId, agentId, USER_SCOPE_KEY), {
      recursive: true,
      force: true,
    });
    const list = (await (await owner.get(filesPath(USER_SCOPE_KEY))).json()) as MemoryFilesResponse;
    expect(list.files).toHaveLength(0);
    await expect(
      fs.stat(memoryScopeDir(t.root, projectId, agentId, USER_SCOPE_KEY)),
    ).resolves.toBeTruthy();
  });

  it("still 404s a Workspace key with no directory, so only the user scope is auto-created", async () => {
    const res = await owner.get(filesPath("never-run-0badc0de"));
    expect(res.status).toBe(404);
  });

  it("lists and reads topic files with their frontmatter, ignoring the .workspace marker", async () => {
    await fs.writeFile(path.join(wsDir, "testing-conventions.md"), TOPIC, "utf8");

    const list = (await (await owner.get(filesPath())).json()) as MemoryFilesResponse;
    expect(list.files).toHaveLength(1);
    expect(list.files[0]).toMatchObject({
      name: "testing-conventions.md",
      title: "testing-conventions",
      description: "how tests are run here",
      updatedAt: "2026-08-07",
    });
    // The retired type field stays out of the DTO even when the file still declares it.
    expect(list.files[0]).not.toHaveProperty("type");

    const read = (await (
      await owner.get(`${filesPath()}/testing-conventions.md`)
    ).json()) as MemoryFileResponse;
    expect(read.content).toBe(TOPIC);
  });

  it("deletes a topic file and prunes its index lines, leaving other lines alone", async () => {
    await fs.writeFile(path.join(wsDir, "testing-conventions.md"), TOPIC, "utf8");
    await fs.writeFile(path.join(wsDir, "release-process.md"), "---\nname: r\n---\nbody\n", "utf8");
    await fs.writeFile(
      path.join(wsDir, MEMORY_INDEX_FILENAME),
      "- [Testing](./testing-conventions.md) — how tests are run here\n" +
        "- [Release](release-process.md) — release steps\n" +
        "Prose mentioning testing-conventions.md survives.\n",
      "utf8",
    );

    expect((await owner.delete(`${filesPath()}/testing-conventions.md`)).status).toBe(204);
    expect(await fs.readdir(wsDir)).not.toContain("testing-conventions.md");
    const index = await fs.readFile(path.join(wsDir, MEMORY_INDEX_FILENAME), "utf8");
    expect(index).not.toContain("](testing-conventions.md)");
    expect(index).toContain("- [Release](release-process.md) — release steps");
    // A plain-prose mention is not a link to the file; the mechanical edit leaves it be.
    expect(index).toContain("Prose mentioning testing-conventions.md survives.");

    expect((await owner.delete(`${filesPath()}/testing-conventions.md`)).status).toBe(404);
  });

  it("rejects traversal and non-Markdown names, and an unknown Workspace", async () => {
    // A key or file name that could climb out of the Memory directory never reaches the filesystem
    // (the separator is percent-encoded, so it arrives as one path segment and is ours to reject).
    expect((await owner.get(filesPath("..%2Fescape"))).status).toBe(400);
    expect((await owner.get(`${filesPath()}/..%2Fescape.md`)).status).toBe(400);
    expect((await owner.get(`${filesPath()}/notes.txt`)).status).toBe(400);
    expect((await owner.delete(`${filesPath()}/.workspace`)).status).toBe(400);
    expect((await owner.get(filesPath("never-seen-0badc0de"))).status).toBe(404);
  });

  it("toggles the Agent-level switch through the config route without touching any file", async () => {
    await fs.writeFile(path.join(wsDir, "testing-conventions.md"), TOPIC, "utf8");

    const off = await owner.put(configPath, { config: { memory: { enabled: false } } });
    expect(off.status).toBe(200);
    expect(((await off.json()) as AgentConfigResponse).config.memory.enabled).toBe(false);

    // Turning Memory off keeps the files and the management API working; it only stops Memory
    // from reaching the model's context.
    const body = (await (await owner.get(memoryPath)).json()) as MemoryOverviewResponse;
    expect(body.enabled).toBe(false);
    expect(body.scopes.find((s) => s.scopeKey === WORKSPACE_KEY)?.fileCount).toBe(1);

    const on = await owner.put(configPath, { config: { memory: { enabled: true } } });
    expect(((await on.json()) as AgentConfigResponse).config.memory.enabled).toBe(true);
  });

  it("reports a template without the {{MEMORY}} placeholder and inserts it on request", async () => {
    // Simulate an Agent from before Memory: replace the template with one lacking the placeholder.
    const put = await owner.put(configPath, {
      config: { systemPrompt: "# Role\nDo things.\n# Environment" },
    });
    expect(put.status).toBe(200);
    let body = (await (await owner.get(memoryPath)).json()) as MemoryOverviewResponse;
    expect(body.templateHasMemory).toBe(false);

    const inserted = await owner.post(`${memoryPath}/template-placeholder`, {});
    expect(inserted.status).toBe(200);
    body = (await inserted.json()) as MemoryOverviewResponse;
    expect(body.templateHasMemory).toBe(true);

    const cfg = (await (await owner.get(configPath)).json()) as AgentConfigResponse;
    // Inserted at the position the default template gives it: before # Environment.
    expect(cfg.config.systemPrompt.indexOf("{{MEMORY}}")).toBeGreaterThan(-1);
    expect(cfg.config.systemPrompt.indexOf("{{MEMORY}}")).toBeLessThan(
      cfg.config.systemPrompt.indexOf("# Environment"),
    );

    // Idempotent: a second call changes nothing and still succeeds.
    const again = await owner.post(`${memoryPath}/template-placeholder`, {});
    expect(again.status).toBe(200);
    const cfgAgain = (await (await owner.get(configPath)).json()) as AgentConfigResponse;
    expect(cfgAgain.config.systemPrompt).toBe(cfg.config.systemPrompt);
  });

  it("round-trips the memory prompts through the config route, reporting defaults until set", async () => {
    const before = (await (await owner.get(configPath)).json()) as AgentConfigResponse;
    // A fresh default agent stores the built-in prompts in its own yaml.
    expect(before.config.memory.prompt).toContain("{{USER_MEMORY_INDEX}}");
    expect(before.config.memory.workspacePrompt).toContain("## Workspace memory");

    const put = await owner.put(configPath, {
      config: { memory: { prompt: "# Memory\ncustom {{USER_MEMORY_INDEX}}" } },
    });
    expect(put.status).toBe(200);
    const after = (await put.json()) as AgentConfigResponse;
    expect(after.config.memory.prompt).toBe("# Memory\ncustom {{USER_MEMORY_INDEX}}");
    // The untouched half keeps its value.
    expect(after.config.memory.workspacePrompt).toContain("## Workspace memory");
  });

  it("reports the memory count on the Agent list, summed across scopes minus the indexes", async () => {
    await fs.writeFile(path.join(wsDir, "testing-conventions.md"), TOPIC, "utf8");
    await fs.writeFile(path.join(wsDir, MEMORY_INDEX_FILENAME), "- [t](t.md) — hook\n", "utf8");
    const userDir = memoryScopeDir(t.root, projectId, agentId, USER_SCOPE_KEY);
    await fs.mkdir(userDir, { recursive: true });
    await fs.writeFile(path.join(userDir, "prefers-pnpm.md"), "---\nname: p\n---\nx\n", "utf8");

    const body = (await (await owner.get(`/api/projects/${projectId}/agents`)).json()) as {
      agents: { agentId: string; memoryCount: number }[];
    };
    const agent = body.agents.find((a) => a.agentId === agentId);
    expect(agent?.memoryCount).toBe(2);
  });

  it("404s for a non-member on every Memory route", async () => {
    expect((await outsider.get(memoryPath)).status).toBe(404);
    expect((await outsider.post(`${memoryPath}/template-placeholder`, {})).status).toBe(404);
    expect((await outsider.get(filesPath())).status).toBe(404);
    expect((await outsider.get(`${filesPath()}/x.md`)).status).toBe(404);
    expect((await outsider.delete(`${filesPath()}/x.md`)).status).toBe(404);
  });
});

describe("memory scope export/import", () => {
  let projectId: string;
  let memoryPath: string;
  let wsDir: string;

  // Every case moves memories in and out of a plain Agent of its own, in the one Project.
  let agentId: string;
  let agents = 0;
  beforeAll(async () => {
    const created = (await (
      await owner.post("/api/projects", { projectId: "owner_a-transfer", name: "transfer" })
    ).json()) as ProjectCreateResponse;
    projectId = created.project.projectId;
    expect(
      (await owner.post(`/api/projects/${projectId}/members`, { userId: "member_b" })).status,
    ).toBe(201);
  });
  beforeEach(async () => {
    agents += 1;
    agentId = `transfer_${agents}`;
    const made = await owner.post(`/api/projects/${projectId}/agents`, { agentId });
    expect(made.status, await made.text()).toBe(201);
    memoryPath = `/api/projects/${projectId}/agents/${agentId}/memory`;
    wsDir = memoryScopeDir(t.root, projectId, agentId, WORKSPACE_KEY);
    await fs.mkdir(wsDir, { recursive: true });
    await fs.writeFile(path.join(wsDir, ".workspace"), "/home/dev/my-app\n", "utf8");
  });

  const exportPath = (key = WORKSPACE_KEY) => `${memoryPath}/scopes/${key}/export`;
  const importPath = (key = WORKSPACE_KEY) => `${memoryPath}/scopes/${key}/import`;

  /** A transfer document carrying the given files; its index links each of them unless one is given. */
  const document = (files: MemoryTransferFile[], index?: string | null): MemoryScopeExport => ({
    format: "penguin-memory-scope",
    version: 1,
    scopeKey: WORKSPACE_KEY,
    kind: "workspace",
    exportedAt: "2026-08-20T00:00:00.000Z",
    index:
      index === undefined
        ? `# Memories\n\n${files.map((f) => `- [${f.name}](${f.name}) — imported`).join("\n")}\n`
        : index,
    files,
  });

  const topic = (name: string, body: string): MemoryTransferFile => ({
    name,
    content: `---\nname: ${name}\n---\n${body}\n`,
  });

  const runImport = async (
    payload: unknown,
    opts: { mode?: MemoryImportMode; confirm?: boolean; key?: string } = {},
  ) =>
    owner.post(importPath(opts.key), {
      payload,
      ...(opts.mode !== undefined ? { mode: opts.mode } : {}),
      ...(opts.confirm !== undefined ? { confirm: opts.confirm } : {}),
    });

  const namesOnDisk = async (): Promise<string[]> =>
    (await fs.readdir(wsDir))
      .filter((n) => n.endsWith(".md") && n !== MEMORY_INDEX_FILENAME)
      .sort();

  const readIndex = (): Promise<string> =>
    fs.readFile(path.join(wsDir, MEMORY_INDEX_FILENAME), "utf8");

  it("exports every topic file plus the scope's index, as one attachment", async () => {
    await fs.writeFile(path.join(wsDir, "testing-conventions.md"), TOPIC, "utf8");
    await fs.writeFile(path.join(wsDir, "项目背景.md"), "---\nname: 项目背景\n---\n正文\n", "utf8");
    await fs.writeFile(path.join(wsDir, MEMORY_INDEX_FILENAME), "- [t](t.md) — hook\n", "utf8");

    const res = await owner.get(exportPath());
    expect(res.status).toBe(200);
    expect(res.headers.get("content-disposition")).toMatch(
      new RegExp(`filename="${agentId}-${WORKSPACE_KEY}-memory-\\d{8}-\\d{4}\\.json"`),
    );
    const doc = (await res.json()) as MemoryScopeExport;
    expect(doc.format).toBe("penguin-memory-scope");
    expect(doc.version).toBe(1);
    expect(doc.kind).toBe("workspace");
    expect(doc.workspacePath).toBe("/home/dev/my-app");
    // The index travels with the files: only the index enters the model's context.
    expect(doc.index).toBe("- [t](t.md) — hook\n");
    expect(doc.files.map((f) => f.name)).toEqual(["testing-conventions.md", "项目背景.md"]);
    expect(doc.files[0]?.content).toBe(TOPIC);
    // The .workspace marker is the Harness's, not a memory.
    expect(doc.files.map((f) => f.name)).not.toContain(".workspace");
  });

  it("exports the user scope, creating it on demand, with no workspace path", async () => {
    const doc = (await (await owner.get(exportPath(USER_SCOPE_KEY))).json()) as MemoryScopeExport;
    expect(doc.kind).toBe("user");
    expect(doc.workspacePath).toBeUndefined();
    // A provisioned Agent starts with an empty user index on disk, so the document carries an
    // empty string; null is reserved for a scope that has no MEMORY.md at all — as this
    // Workspace scope, created by hand above, does not.
    expect(doc.index).toBe("");
    expect(doc.files).toEqual([]);
    expect(((await (await owner.get(exportPath())).json()) as MemoryScopeExport).index).toBeNull();
  });

  it("round-trips one scope's export into another scope", async () => {
    await fs.writeFile(path.join(wsDir, "testing-conventions.md"), TOPIC, "utf8");
    await fs.writeFile(path.join(wsDir, MEMORY_INDEX_FILENAME), "- [T](testing-conventions.md)\n");
    const doc = (await (await owner.get(exportPath())).json()) as MemoryScopeExport;

    const res = await runImport(doc, { key: USER_SCOPE_KEY });
    expect(res.status).toBe(200);
    expect((await res.json()) as MemoryImportResponse).toMatchObject({
      scopeKey: USER_SCOPE_KEY,
      mode: "skip",
      added: ["testing-conventions.md"],
      indexWritten: true,
    });
    const userDir = memoryScopeDir(t.root, projectId, agentId, USER_SCOPE_KEY);
    expect(await fs.readFile(path.join(userDir, "testing-conventions.md"), "utf8")).toBe(TOPIC);
    expect(await fs.readFile(path.join(userDir, MEMORY_INDEX_FILENAME), "utf8")).toBe(
      "- [T](testing-conventions.md)\n",
    );
  });

  // —— The collision policy, branch by branch ——

  it("defaults to skip: an existing memory is kept and the newcomer is indexed beside it", async () => {
    await fs.writeFile(path.join(wsDir, "keep.md"), "on disk\n", "utf8");
    await fs.writeFile(path.join(wsDir, MEMORY_INDEX_FILENAME), "- [Keep](keep.md) — mine\n");

    const res = await runImport(
      document([topic("keep.md", "from the file"), topic("new.md", "n")]),
    );
    expect(res.status).toBe(200);
    const body = (await res.json()) as MemoryImportResponse;
    expect(body).toMatchObject({ mode: "skip", added: ["new.md"], skipped: ["keep.md"] });
    expect(body.overwritten).toEqual([]);
    expect(body.removed).toEqual([]);
    // Nothing was lost: the file on disk is untouched.
    expect(await fs.readFile(path.join(wsDir, "keep.md"), "utf8")).toBe("on disk\n");
    // The index keeps its own line and gains one for the file that arrived — an unindexed
    // memory would be one the Agent never reads.
    const index = await readIndex();
    expect(index).toContain("- [Keep](keep.md) — mine");
    expect(index).toContain("- [new.md](new.md) — imported");
    expect(body.indexWritten).toBe(true);
  });

  it("refuses overwrite and replace without confirmation, naming what would be lost", async () => {
    await fs.writeFile(path.join(wsDir, "keep.md"), "on disk\n", "utf8");
    const doc = document([topic("keep.md", "from the file")]);

    for (const mode of ["overwrite", "replace"] as const) {
      const res = await runImport(doc, { mode });
      expect(res.status).toBe(409);
      const body = (await res.json()) as { error: { code: string; message: string } };
      expect(body.error.code).toBe("memory_import_confirm_required");
      expect(body.error.message).toContain("overwrite 1");
    }
    expect(await fs.readFile(path.join(wsDir, "keep.md"), "utf8")).toBe("on disk\n");
  });

  it("overwrites same-named memories on confirmation and leaves the rest alone", async () => {
    await fs.writeFile(path.join(wsDir, "keep.md"), "on disk\n", "utf8");
    await fs.writeFile(path.join(wsDir, "untouched.md"), "not in the document\n", "utf8");

    const res = await runImport(document([topic("keep.md", "from the file")]), {
      mode: "overwrite",
      confirm: true,
    });
    expect(res.status).toBe(200);
    expect((await res.json()) as MemoryImportResponse).toMatchObject({
      mode: "overwrite",
      added: [],
      overwritten: ["keep.md"],
      removed: [],
    });
    expect(await fs.readFile(path.join(wsDir, "keep.md"), "utf8")).toContain("from the file");
    // overwrite is a merge: a memory the document does not carry survives.
    expect(await namesOnDisk()).toEqual(["keep.md", "untouched.md"]);
  });

  it("replaces the whole scope on confirmation, deleting what the document does not carry", async () => {
    await fs.writeFile(path.join(wsDir, "keep.md"), "on disk\n", "utf8");
    await fs.writeFile(path.join(wsDir, "gone.md"), "not in the document\n", "utf8");
    await fs.writeFile(
      path.join(wsDir, MEMORY_INDEX_FILENAME),
      "- [Keep](keep.md) — mine\n- [Gone](gone.md) — mine\n",
      "utf8",
    );

    const res = await runImport(document([topic("keep.md", "from the file")]), {
      mode: "replace",
      confirm: true,
    });
    expect(res.status).toBe(200);
    expect((await res.json()) as MemoryImportResponse).toMatchObject({
      mode: "replace",
      overwritten: ["keep.md"],
      removed: ["gone.md"],
      indexWritten: true,
    });
    expect(await namesOnDisk()).toEqual(["keep.md"]);
    // The document's index replaces the old one wholesale; no line survives for a deleted file.
    const index = await readIndex();
    expect(index).toContain("- [keep.md](keep.md) — imported");
    expect(index).not.toContain("gone.md");
  });

  it("prunes the index of a replace whose document carries none", async () => {
    await fs.writeFile(path.join(wsDir, "gone.md"), "x\n", "utf8");
    await fs.writeFile(path.join(wsDir, MEMORY_INDEX_FILENAME), "- [Gone](gone.md) — mine\n");

    const res = await runImport(document([topic("new.md", "n")], null), {
      mode: "replace",
      confirm: true,
    });
    expect(res.status).toBe(200);
    expect(((await res.json()) as MemoryImportResponse).removed).toEqual(["gone.md"]);
    expect(await readIndex()).not.toContain("gone.md");
  });

  it("needs no confirmation for a destructive mode that would destroy nothing", async () => {
    // The gate is what the import would actually cost, not the mode's name: an empty scope
    // loses nothing either way, and a confirmation naming nothing is just a click.
    const res = await runImport(document([topic("new.md", "n")]), { mode: "replace" });
    expect(res.status).toBe(200);
    expect((await res.json()) as MemoryImportResponse).toMatchObject({
      added: ["new.md"],
      removed: [],
      overwritten: [],
    });
  });

  // —— Rejections on the untrusted write path ——

  /** The NUL byte, built rather than typed: an invisible byte in a source file is nobody's friend. */
  const NUL = String.fromCharCode(0);

  /** Posts a document (or a whole raw body) that must be refused with 400, having written nothing. */
  const rejects = async (files: unknown, hint: string): Promise<void> => {
    const res = await runImport(
      Array.isArray(files) ? document(files as MemoryTransferFile[]) : files,
    );
    expect(res.status, hint).toBe(400);
  };

  it("rejects a name that is a path, climbs out, or is not a topic file", async () => {
    const outside = path.join(t.root, `${agentId}-outside-target.md`);
    await rejects([topic("../escape.md", "x")], "parent traversal");
    await rejects([topic("..\\escape.md", "x")], "windows traversal");
    await rejects([topic("sub/notes.md", "x")], "nested path");
    await rejects([topic(outside, "x")], "absolute path");
    await rejects([topic(MEMORY_INDEX_FILENAME, "x")], "the index is not a topic file");
    await rejects([topic("memory.md", "x")], "the index under another casing");
    await rejects([topic("notes.txt", "x")], "not markdown");
    await rejects([topic(".workspace", "x")], "the workspace marker");
    await rejects([topic("", "x")], "empty name");
    await rejects([topic(`bad${NUL}.md`, "x")], "NUL in the name");
    // Not one of them reached the filesystem, inside the scope or out.
    expect(await namesOnDisk()).toEqual([]);
    await expect(fs.stat(outside)).rejects.toThrow();
  });

  it("writes nothing at all when one entry in the document is bad", async () => {
    const res = await runImport(document([topic("fine.md", "ok"), topic("../escape.md", "x")]));
    expect(res.status).toBe(400);
    expect(await namesOnDisk()).toEqual([]);
  });

  it("rejects entries that are not text", async () => {
    await rejects([{ name: "n.md", content: 42 }], "number content");
    await rejects([{ name: "n.md", content: { body: "x" } }], "object content");
    await rejects([{ name: "n.md" }], "missing content");
    await rejects([{ name: 7, content: "x" }], "non-string name");
    await rejects(["n.md"], "entry is not an object");
    await rejects([{ name: "n.md", content: `binary${NUL}payload` }], "NUL in the content");
    await rejects({ ...document([topic("n.md", "x")]), index: 5 }, "non-string index");
    expect(await namesOnDisk()).toEqual([]);
  });

  it("rejects absurd counts and sizes", async () => {
    await rejects(
      Array.from({ length: 501 }, (_, i) => topic(`m${i}.md`, "x")),
      "too many entries",
    );
    await rejects([{ name: "huge.md", content: "x".repeat(512 * 1024 + 1) }], "one oversized file");
    // Longer than a path component may be: the write would fail with ENAMETOOLONG, which is a
    // 500 for what is plainly a bad request.
    await rejects([topic(`${"a".repeat(253)}.md`, "x")], "an oversized name");
    // Individually legal, together over the whole-document budget.
    const half = "y".repeat(512 * 1024);
    await rejects(
      Array.from({ length: 17 }, (_, i) => ({ name: `big${i}.md`, content: half })),
      "over the total budget",
    );
    expect(await namesOnDisk()).toEqual([]);
  });

  it("rejects a foreign or future document, and a body with no document at all", async () => {
    await rejects({ ...document([]), format: "some-other-tool" }, "foreign format");
    await rejects({ ...document([]), version: 2 }, "future version");
    await rejects({ ...document([]), files: "not-an-array" }, "files is not an array");
    await rejects([topic("a.md", "1"), topic("a.md", "2")], "the same name twice");
    expect((await owner.post(importPath(), {})).status).toBe(400);
    expect((await owner.post(importPath(), { payload: "text" })).status).toBe(400);
    expect((await owner.post(importPath(), { payload: document([]), mode: "wipe" })).status).toBe(
      400,
    );
  });

  itWithSymlinks(
    "replaces a symlink standing at a memory's name instead of writing through it",
    async () => {
      const outside = path.join(t.root, `${agentId}-outside-secret.md`);
      await fs.writeFile(outside, "secret\n", "utf8");
      await fs.symlink(outside, path.join(wsDir, "leak.md"));

      const res = await runImport(document([topic("leak.md", "imported body")]), {
        mode: "overwrite",
        confirm: true,
      });
      expect(res.status).toBe(200);
      // The link is gone, the memory is a real file inside the scope, and the file it pointed at
      // never saw the write.
      expect((await fs.lstat(path.join(wsDir, "leak.md"))).isSymbolicLink()).toBe(false);
      expect(await fs.readFile(path.join(wsDir, "leak.md"), "utf8")).toContain("imported body");
      expect(await fs.readFile(outside, "utf8")).toBe("secret\n");
    },
  );

  it("leaves no temporary file behind in the scope directory", async () => {
    expect((await runImport(document([topic("a.md", "x")]))).status).toBe(200);
    expect((await fs.readdir(wsDir)).filter((n) => n.endsWith(".tmp"))).toEqual([]);
  });

  itWithSymlinks(
    "rejects a bad scope key and a scope smuggled in as a symlink, on both routes",
    async () => {
      expect((await owner.get(exportPath("..%2Fescape"))).status).toBe(400);
      expect((await runImport(document([]), { key: "..%2Fescape" })).status).toBe(400);
      expect((await owner.get(exportPath("never-run-0badc0de"))).status).toBe(404);
      expect((await runImport(document([]), { key: "never-run-0badc0de" })).status).toBe(404);

      const outside = path.join(t.root, `${agentId}-outside-dir`);
      await fs.mkdir(outside, { recursive: true });
      await fs.symlink(outside, memoryScopeDir(t.root, projectId, agentId, "evil-12345678"));
      expect((await owner.get(exportPath("evil-12345678"))).status).toBe(404);
      expect(
        (await runImport(document([topic("a.md", "x")]), { key: "evil-12345678" })).status,
      ).toBe(404);
      expect(await fs.readdir(outside)).toEqual([]);
    },
  );

  // —— Authorization ——

  it("lets any member export but only the owner import", async () => {
    await fs.writeFile(path.join(wsDir, "testing-conventions.md"), TOPIC, "utf8");
    // Export is reading Agent State, which every Project member may already do file by file.
    expect((await member.get(exportPath())).status).toBe(200);
    // Import can cost the Agent memories, so it follows the Agent State snapshot's owner gate.
    const denied = await member.post(importPath(), { payload: document([topic("a.md", "x")]) });
    expect(denied.status).toBe(403);
    expect(((await denied.json()) as { error: { code: string } }).error.code).toBe(
      "owner_required",
    );
    expect(await namesOnDisk()).toEqual(["testing-conventions.md"]);
  });

  it("404s both routes for a non-member, without leaking that the scope exists", async () => {
    expect((await outsider.get(exportPath())).status).toBe(404);
    const res = await outsider.post(importPath(), { payload: document([topic("a.md", "x")]) });
    expect(res.status).toBe(404);
    expect(await namesOnDisk()).toEqual([]);
  });
});