Skip to content

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

20.6 KB
Raw Blame
/**
 * Composer file attachments: POST /api/sessions/:id/tasks with `{type:"file"}` input parts.
 *
 * - The bytes land in the Session's scratchpad and the Prompt gains an `[attached file: <path>]`
 *   line after the user's text, so the model reaches the file by path.
 * - A files-only Prompt still reaches the model (the lines become the message), and a Prompt
 *   whose only text is a `[handoff_from]` origin block keeps that block parseable.
 * - Two uploads of one name coexist; unsafe names are sanitized (keeping the extension,
 *   non-ASCII kept, the stem capped by UTF-8 bytes, Windows device names prefixed).
 * - A media type with parameters is accepted; malformed parts are 400s and write nothing.
 * - A file over the per-file cap, more files or more bytes than one request may carry are 413s
 *   that write nothing; what /api/me advertises is exactly what is enforced; an inline image
 *   has its own cap, independent of the attachment limit.
 * - Goal mode, and a busy Session without queueIfBusy, refuse before anything is written.
 * - A Task that never starts leaves no orphaned bytes, and a scratchpad directory resolving
 *   outside the Agent's scratchpad root is refused, not written through.
 */
import fs from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest";
import {
  assistantText,
  buildHandoffMessage,
  modelVisiblePath,
  parseHandoffMessage,
  scratchpadDir,
} from "@adelie/core";
import type { OmniMessage } from "@adelie/core";
import type { SessionRow } from "../src/db/repos/sessions.js";
import type { RuntimeSession } from "../src/runtime/session-manager.js";
import { MAX_ATTACHMENT_COUNT } from "../src/services/attachment-limits.js";
import { adoptSession, fakeSession, sessionRow, uniqueSessionId } from "./fixtures/session.js";
import { apiClient, createTestApp, provisionUser, waitFor } from "./helpers.js";
import type { TestApp } from "./helpers.js";

const PROJECT_ID = "attacher-default_project";

/**
 * Deliberately tiny limits for the cap tests (see beforeAll), in whole MB and in bytes. The
 * total is kept below twice the per-file cap so that "two individually legal files that together
 * cross the aggregate" is expressible — with total >= 2x per-file, each half would trip the
 * per-file check first and the aggregate cap would never be the thing under test.
 */
const TEST_MAX_MB = 2;
const TEST_TOTAL_MB = 3;
const TEST_MAX_BYTES = TEST_MAX_MB * 1024 * 1024;
const TEST_TOTAL_BYTES = TEST_TOTAL_MB * 1024 * 1024;

/** Fake Session that records each run's input and finishes immediately (no LLM, no approvals). */
function recordingFakeSession(sessionId: string, runs: OmniMessage[][]): RuntimeSession {
  return fakeSession(sessionId, {
    async *run(input: OmniMessage[]) {
      runs.push(input);
      yield assistantText("done");
    },
  });
}

/** Fake Session whose run parks until `until` resolves, so the Session stays busy while the test posts. */
function parkingFakeSession(sessionId: string, until: Promise<void>): RuntimeSession {
  return fakeSession(sessionId, {
    async *run() {
      await until;
      yield assistantText("done");
    },
  });
}

/** Base64 data URL of some bytes, the shape the composer submits. */
function dataUrl(content: string, mime = "application/octet-stream"): string {
  return `data:${mime};base64,${Buffer.from(content).toString("base64")}`;
}

/** All text of a recorded Prompt, joined the way the model would read it. */
function promptText(input: OmniMessage[]): string {
  return input
    .map((m) => (m.payload as { text?: string }).text ?? "")
    .filter(Boolean)
    .join("\n");
}

describe("task input file attachments", () => {
  let t: TestApp;
  let api: ReturnType<typeof apiClient>;
  let SID: string;
  let runs: OmniMessage[][];
  let dir: string;
  let row: SessionRow;

  beforeAll(async () => {
    t = await createTestApp();
    api = apiClient(t.app, (await provisionUser(t.app, "attacher")).cookie);
    // The shipped defaults are 100MB/120MB — allocating buffers that size to prove a cap works
    // would cost hundreds of megabytes per assertion. The caps are read from the settings repo
    // per request, so the tests turn them down instead: that also makes these the tests of the
    // *configured* limit rather than of a compiled-in constant.
    t.deps.serverSettingsRepo.setAttachmentMaxMb(TEST_MAX_MB);
    t.deps.serverSettingsRepo.setAttachmentTotalMb(TEST_TOTAL_MB);
  });
  afterAll(async () => {
    await t.cleanup();
  });
  beforeEach(() => {
    SID = uniqueSessionId();
    runs = [];
    row = adoptSession(t.deps, recordingFakeSession(SID, runs), { projectId: PROJECT_ID });
    dir = path.join(scratchpadDir(t.root, PROJECT_ID, "default_agent"), SID);
  });

  it("writes the file into the session scratchpad and appends the marker line to the text", async () => {
    const res = await api.post(`/api/sessions/${SID}/tasks`, {
      input: [
        { type: "text", text: "look at this" },
        { type: "file", fileName: "report.pdf", dataUrl: dataUrl("PDF-BYTES") },
      ],
    });
    expect(res.status).toBe(202);
    await waitFor(() => runs.length === 1);

    const text = promptText(runs[0]!);
    const marker = /\[attached file: (.+)\]/.exec(text);
    expect(marker).not.toBeNull();
    const filePath = marker![1]!;
    // Marker lines carry the model-visible spelling (forward slashes on Windows).
    expect(filePath).toBe(modelVisiblePath(path.join(dir, "report.pdf")));
    expect(await fs.readFile(filePath, "utf8")).toBe("PDF-BYTES");
    // The line trails the user's own text — it must not replace or reframe the message.
    expect(text.startsWith("look at this")).toBe(true);
    // One text message carries both (no extra message per file).
    expect(runs[0]!).toHaveLength(1);
  });

  it("files-only input becomes a message of attachment lines; same names do not overwrite", async () => {
    const res = await api.post(`/api/sessions/${SID}/tasks`, {
      input: [
        { type: "file", fileName: "notes.txt", dataUrl: dataUrl("first") },
        { type: "file", fileName: "notes.txt", dataUrl: dataUrl("second") },
      ],
    });
    expect(res.status).toBe(202);
    await waitFor(() => runs.length === 1);

    const paths = [...promptText(runs[0]!).matchAll(/\[attached file: (.+)\]/g)].map((m) => m[1]!);
    expect(paths).toHaveLength(2);
    expect(paths[0]).toBe(modelVisiblePath(path.join(dir, "notes.txt")));
    // The second upload gets a random suffix rather than clobbering the first.
    expect(paths[1]).not.toBe(paths[0]);
    expect(path.basename(paths[1]!)).toMatch(/^notes-[0-9a-f]{6}\.txt$/);
    expect(await fs.readFile(paths[0]!, "utf8")).toBe("first");
    expect(await fs.readFile(paths[1]!, "utf8")).toBe("second");
  });

  it("unsafe characters in the name are sanitized, keeping the extension", async () => {
    const res = await api.post(`/api/sessions/${SID}/tasks`, {
      input: [{ type: "file", fileName: "my report (final).csv", dataUrl: dataUrl("a,b") }],
    });
    expect(res.status).toBe(202);
    await waitFor(() => runs.length === 1);
    const filePath = /\[attached file: (.+)\]/.exec(promptText(runs[0]!))![1]!;
    expect(path.basename(filePath)).toBe("my-report--final-.csv");
    expect(await fs.readFile(filePath, "utf8")).toBe("a,b");
  });

  it("keeps a non-ASCII name instead of flattening it, and caps the stem by UTF-8 bytes", async () => {
    // A CJK character costs three bytes: 40 of them are 120 bytes, well past the 80-byte cap,
    // so the name is cut on a character boundary rather than mid-character (a split would leave
    // an invalid sequence on disk and an unopenable path in the message).
    const long = "报".repeat(40);
    const res = await api.post(`/api/sessions/${SID}/tasks`, {
      input: [
        { type: "file", fileName: "报告 2026.pdf", dataUrl: dataUrl("cjk") },
        { type: "file", fileName: `${long}.txt`, dataUrl: dataUrl("long") },
      ],
    });
    expect(res.status).toBe(202);
    await waitFor(() => runs.length === 1);

    const paths = [...promptText(runs[0]!).matchAll(/\[attached file: (.+)\]/g)].map((m) => m[1]!);
    // The words survive; only the space (shell-hostile, and ASCII) is replaced.
    expect(path.basename(paths[0]!)).toBe("报告-2026.pdf");
    expect(await fs.readFile(paths[0]!, "utf8")).toBe("cjk");
    const capped = path.basename(paths[1]!);
    expect(capped).toBe(`${"报".repeat(26)}.txt`);
    expect(Buffer.byteLength(capped.slice(0, capped.length - 4))).toBeLessThanOrEqual(80);
    expect(await fs.readFile(paths[1]!, "utf8")).toBe("long");
  });

  it("prefixes a Windows device name and falls back when the stem sanitizes away", async () => {
    const res = await api.post(`/api/sessions/${SID}/tasks`, {
      input: [
        { type: "file", fileName: "con.txt", dataUrl: dataUrl("device") },
        // Zero-width joiner only (spelled by code point — an invisible character in the source
        // would read as an empty string): category C, so nothing is left to name the file with.
        {
          type: "file",
          fileName: `${String.fromCodePoint(0x200d)}.bin`,
          dataUrl: dataUrl("invisible"),
        },
      ],
    });
    expect(res.status).toBe(202);
    await waitFor(() => runs.length === 1);

    const paths = [...promptText(runs[0]!).matchAll(/\[attached file: (.+)\]/g)].map((m) => m[1]!);
    expect(path.basename(paths[0]!)).toBe("_con.txt");
    expect(path.basename(paths[1]!)).toBe("file.bin");
  });

  it("accepts a data URL whose media type carries parameters", async () => {
    const res = await api.post(`/api/sessions/${SID}/tasks`, {
      input: [
        {
          type: "file",
          fileName: "notes.txt",
          dataUrl: dataUrl("hello", "text/plain;charset=utf-8"),
        },
      ],
    });
    expect(res.status).toBe(202);
    await waitFor(() => runs.length === 1);
    const filePath = /\[attached file: (.+)\]/.exec(promptText(runs[0]!))![1]!;
    expect(await fs.readFile(filePath, "utf8")).toBe("hello");
  });

  it("malformed parts are 400s and write nothing", async () => {
    const bad = [
      { type: "file", dataUrl: dataUrl("x") }, // no fileName
      { type: "file", fileName: "", dataUrl: dataUrl("x") },
      { type: "file", fileName: "../escape.txt", dataUrl: dataUrl("x") },
      { type: "file", fileName: "sub/dir.txt", dataUrl: dataUrl("x") },
      { type: "file", fileName: "a.txt", dataUrl: "https://example.com/a.txt" },
      { type: "file", fileName: "a.txt", dataUrl: "data:text/plain,not-base64" },
      { type: "file", fileName: "a.txt" }, // no dataUrl
      { type: "blob", fileName: "a.txt", dataUrl: dataUrl("x") }, // unknown part type
    ];
    for (const part of bad) {
      const res = await api.post(`/api/sessions/${SID}/tasks`, { input: [part] });
      expect(res.status, JSON.stringify(part)).toBe(400);
    }
    await expect(fs.access(dir)).rejects.toThrow();
    expect(runs).toHaveLength(0);
  });

  it("a file over the per-file cap is a 413", async () => {
    const res = await api.post(`/api/sessions/${SID}/tasks`, {
      input: [
        {
          type: "file",
          fileName: "big.bin",
          dataUrl: `data:application/octet-stream;base64,${Buffer.alloc(
            TEST_MAX_BYTES + 1,
          ).toString("base64")}`,
        },
      ],
    });
    expect(res.status).toBe(413);
    expect(((await res.json()) as { error: { code: string } }).error.code).toBe("file_too_large");
    await expect(fs.access(dir)).rejects.toThrow();
  });

  it("what /api/me advertises is exactly what the upload path enforces", async () => {
    // The composer refuses an oversize pick using the number this endpoint hands it, so the two
    // must agree on the boundary itself, not merely be "about the same". A file of exactly the
    // advertised limit has to be accepted and one byte more has to be refused — if the server
    // were stricter by a byte, the composer would upload a file the server then rejects, which is
    // precisely the failure the client-side check exists to prevent.
    const me = (await api.get("/api/me")).clone();
    const { uploadLimits } = (await me.json()) as {
      uploadLimits: { attachmentMaxMb: number; attachmentTotalMb: number; imageMaxMb: number };
    };
    expect(uploadLimits.attachmentMaxMb).toBe(TEST_MAX_MB);
    expect(uploadLimits.attachmentTotalMb).toBe(TEST_TOTAL_MB);

    const atLimit = await api.post(`/api/sessions/${SID}/tasks`, {
      input: [
        {
          type: "file",
          fileName: "exact.bin",
          dataUrl: `data:application/octet-stream;base64,${Buffer.alloc(
            uploadLimits.attachmentMaxMb * 1024 * 1024,
          ).toString("base64")}`,
        },
      ],
    });
    expect(atLimit.status).toBe(202);
    await waitFor(() => runs.length === 1);

    const overLimit = await api.post(`/api/sessions/${SID}/tasks`, {
      input: [
        {
          type: "file",
          fileName: "over.bin",
          dataUrl: `data:application/octet-stream;base64,${Buffer.alloc(
            uploadLimits.attachmentMaxMb * 1024 * 1024 + 1,
          ).toString("base64")}`,
        },
      ],
    });
    expect(overLimit.status).toBe(413);
  });

  it("an inline image over its own cap is a 413, and the cap does not follow the attachment limit", async () => {
    // Images are bounded separately and far lower: they enter the conversation and the Trace,
    // where the bytes are paid again on every history page and every resume. Raising the
    // attachment ceiling must not raise this one — so the image here is well under the
    // attachment cap that the surrounding suite configured, and still refused.
    const me = (await api.get("/api/me")).clone();
    const { uploadLimits } = (await me.json()) as { uploadLimits: { imageMaxMb: number } };
    const oversize = Buffer.alloc(uploadLimits.imageMaxMb * 1024 * 1024 + 1).toString("base64");
    const res = await api.post(`/api/sessions/${SID}/tasks`, {
      input: [{ type: "image_url", imageUrl: `data:image/png;base64,${oversize}` }],
    });
    expect(res.status).toBe(413);
    expect(((await res.json()) as { error: { code: string } }).error.code).toBe("image_too_large");
    expect(runs).toHaveLength(0);
  });

  it("goal mode rejects attachments before anything is written", async () => {
    const res = await api.post(`/api/sessions/${SID}/tasks`, {
      input: [
        { type: "text", text: "ship the report" },
        { type: "file", fileName: "spec.md", dataUrl: dataUrl("# spec") },
      ],
      goal: {},
    });
    expect(res.status).toBe(400);
    await expect(fs.access(dir)).rejects.toThrow();
  });

  it("files with only a handoff origin block: the block stays parseable, the lines get their own message", async () => {
    // The composer's "attachments, no text, staged /agent handoff" shape. `[handoff_from]` only
    // parses when the block is the WHOLE message, so appending the marker line to it would put
    // the raw block in a user bubble instead of a one-line banner.
    const block = buildHandoffMessage({ agentId: "alpha", agentName: "Alpha", sessionId: "s0" });
    const res = await api.post(`/api/sessions/${SID}/tasks`, {
      input: [
        { type: "text", text: block },
        { type: "file", fileName: "notes.txt", dataUrl: dataUrl("hi") },
      ],
    });
    expect(res.status).toBe(202);
    await waitFor(() => runs.length === 1);

    const texts = runs[0]!.map((m) => (m.payload as { text?: string }).text ?? "");
    expect(texts).toHaveLength(2);
    expect(texts[0]).toBe(block);
    expect(parseHandoffMessage(texts[0]!)?.agentId).toBe("alpha");
    expect(texts[1]).toBe(`[attached file: ${modelVisiblePath(path.join(dir, "notes.txt"))}]`);
  });

  it("more than the per-request file count is a 413 and writes nothing", async () => {
    const res = await api.post(`/api/sessions/${SID}/tasks`, {
      input: Array.from({ length: MAX_ATTACHMENT_COUNT + 1 }, (_, i) => ({
        type: "file",
        fileName: `f${i}.txt`,
        dataUrl: dataUrl("x"),
      })),
    });
    expect(res.status).toBe(413);
    expect(((await res.json()) as { error: { code: string } }).error.code).toBe("too_many_files");
    await expect(fs.access(dir)).rejects.toThrow();
    expect(runs).toHaveLength(0);
  });

  it("more than the per-request total size is a 413 and writes nothing", async () => {
    // Two files, each individually legal, that together cross the aggregate cap: the per-file
    // check alone would let this through and land both on disk.
    const half = Buffer.alloc(Math.floor(TEST_TOTAL_BYTES / 2) + 1).toString("base64");
    const res = await api.post(`/api/sessions/${SID}/tasks`, {
      input: [
        {
          type: "file",
          fileName: "a.bin",
          dataUrl: `data:application/octet-stream;base64,${half}`,
        },
        {
          type: "file",
          fileName: "b.bin",
          dataUrl: `data:application/octet-stream;base64,${half}`,
        },
      ],
    });
    expect(res.status).toBe(413);
    expect(((await res.json()) as { error: { code: string } }).error.code).toBe(
      "payload_too_large",
    );
    await expect(fs.access(dir)).rejects.toThrow();
    expect(runs).toHaveLength(0);
  });

  it("a busy session without queueIfBusy 409s before the upload is written", async () => {
    // Without the pre-check the files land first and the 409 comes after, so the user's retry
    // (the Web keeps the chips on failure) would deposit a second copy of every one of them.
    let release = () => {};
    const parked = new Promise<void>((resolve) => {
      release = resolve;
    });
    t.deps.manager.adopt(row, parkingFakeSession(SID, parked));
    await api.post(`/api/sessions/${SID}/tasks`, { input: [{ type: "text", text: "busy" }] });
    await waitFor(() => t.deps.manager.statusOf(SID) === "running");

    const res = await api.post(`/api/sessions/${SID}/tasks`, {
      input: [{ type: "file", fileName: "late.txt", dataUrl: dataUrl("bytes") }],
    });
    expect(res.status).toBe(409);
    expect(((await res.json()) as { error: { code: string } }).error.code).toBe("task_in_progress");
    await expect(fs.access(dir)).rejects.toThrow();
    release();
    await waitFor(() => t.deps.manager.statusOf(SID) === "idle");
  });

  // Symlink creation needs a privilege or developer mode on Windows; the containment rule
  // itself is platform-independent.
  it.skipIf(process.platform === "win32")(
    "a session directory symlinked out of the scratchpad root is refused, not written through",
    async () => {
      const outside = await fs.mkdtemp(path.join(os.tmpdir(), "penguin-outside-"));
      try {
        await fs.mkdir(path.dirname(dir), { recursive: true });
        // `fs.mkdir(dir, {recursive:true})` succeeds silently on an existing symlink-to-directory,
        // so without the realpath check the upload would land in `outside`.
        await fs.symlink(outside, dir, "dir");
        const res = await api.post(`/api/sessions/${SID}/tasks`, {
          input: [{ type: "file", fileName: "escape.txt", dataUrl: dataUrl("bytes") }],
        });
        expect(res.status).toBe(500);
        expect(await fs.readdir(outside)).toEqual([]);
      } finally {
        await fs.rm(outside, { recursive: true, force: true });
      }
    },
  );
});

describe("task attachments are removed when the Task never starts", () => {
  const FAIL_SID = "session-2026-07-29-11-00-00-aabb0002";
  const PID = "failer-default_project";
  let t: TestApp;
  let api: ReturnType<typeof apiClient>;
  let dir: string;

  beforeEach(async () => {
    // Never adopted into the active table, so startTask goes through the loader — which throws
    // here. That is the window the route's cleanup exists for: the pre-check cannot see a
    // session it hasn't loaded, so the files are already on disk when the failure happens.
    t = await createTestApp({
      loader: {
        load: async () => {
          throw new Error("loader unavailable");
        },
      },
    });
    const { cookie } = await provisionUser(t.app, "failer");
    api = apiClient(t.app, cookie);
    t.deps.sessionsRepo.insert(sessionRow(FAIL_SID, { projectId: PID }));
    dir = path.join(scratchpadDir(t.root, PID, "default_agent"), FAIL_SID);
  });
  afterEach(async () => {
    await t.cleanup();
  });

  it("a failure after the write leaves no orphaned bytes behind", async () => {
    const res = await api.post(`/api/sessions/${FAIL_SID}/tasks`, {
      input: [
        { type: "file", fileName: "a.txt", dataUrl: dataUrl("first") },
        { type: "file", fileName: "b.txt", dataUrl: dataUrl("second") },
      ],
    });
    expect(res.status).toBe(500);
    // The directory may remain (it is the Session's own and is deleted with it); the point is
    // that a retry cannot find a stale `a-<hex>.txt` next to its own upload.
    expect(await fs.readdir(dir).catch(() => [])).toEqual([]);
  });
});