A local-first multi-agent app development platform, built on PenguinHarness
/**
* A Session's source on the server: what kind of conversation each Session is, read from its
* session_meta (never the index row), and the sessions list's three categories built on it.
*
* One app and one Project serve the file; each case works in an Agent of its own, which it
* deletes on the way out.
*
* Scenarios:
* - Given Sessions of every source, some archived, the list files `user` rows under `active`,
* `api` / `schedule` / `subagent` / `cli` rows under `background`, and an archived row under
* `archived` whatever its source — but a `company` row, archived or not, under none of them;
* the plain list still serves it.
* - Given a category the list no longer has (`subagent`, `schedule`, `benchmark`) or junk,
* the list is a 400, never an unfiltered page.
* - Given the same rows, `counts=1` returns active / background / archived totals over the
* whole list whatever the page, counting no company row; the per-Workspace totals sum back
* to them, a Workspace holding only company rows has no totals and no stamp, and a request
* without `counts=1` carries none.
* - Given more background rows than a page, `category=background` pages by activity cursor,
* serving every background row exactly once and no other.
* - Given a create request, `source: "cli"` creates a `cli` Session and the retired
* `benchmark` is accepted as `cli`; a source the server writes itself is a 400 that creates
* nothing.
* - Given a Trace head from before the source was required, after a restart (a registry that
* has not seen it) one without a source lists as `active` and reads `user`, one with
* `benchmark` lists as `background` and reads `cli`; the startup sweep adopts them the same
* way.
* - Given a Session company mode opened before the source was required (a head without one, the
* row's client `org`), it reads as `company` and is in no category; so does an `org` row that
* has not run yet. An `api` row that has not run yet reads as `api`, in Background.
* - Given company mode opening a desk Session (`company`, client `org`), the Session is
* `company`, keeps its `org` client and is in no category; a child it spawns is `subagent`,
* in Background.
* - Given the scheduler opening a Session, it is `schedule`, in Background.
* (A fork is `user` whatever it was cut from: session-fork.test.ts.)
*/
import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest";
import { assistantText, sessionMeta, userText, withOrigin } from "@adelie/core";
import type {
ProjectCreateResponse,
SessionCreateResponse,
SessionResponse,
SessionsResponse,
} from "../src/api/types.js";
import { apiClient, createTestApp, provisionUser, waitFor, writeTraceFile } from "./helpers.js";
import type { TestApp } from "./helpers.js";
import { adoptSession, fakeSession } from "./fixtures/session.js";
describe("session source", () => {
let t: TestApp;
let api: ReturnType<typeof apiClient>;
let projectId: string;
let agentId: string;
let cases = 0;
const base = () => `/api/projects/${projectId}/agents/${agentId}/sessions`;
beforeAll(async () => {
t = await createTestApp();
const { cookie } = await provisionUser(t.app, "source_owner");
api = apiClient(t.app, cookie);
const created = (await (
await api.post("/api/projects", { projectId: "source_owner-src", name: "Source project" })
).json()) as ProjectCreateResponse;
projectId = created.project.projectId;
});
afterAll(async () => {
await t.cleanup();
});
beforeEach(async () => {
agentId = `case_${++cases}`;
expect((await api.post(`/api/projects/${projectId}/agents`, { agentId })).status).toBe(201);
});
afterEach(async () => {
await api.delete(`/api/projects/${projectId}/agents/${agentId}`);
});
async function configureModels(): Promise<void> {
const res = await api.put(`/api/projects/${projectId}/models`, {
defaultModel: { provider: "anthropic", modelId: "claude-sonnet-4-6" },
models: [{ provider: "anthropic", modelId: "claude-sonnet-4-6", contextWindow: 128000 }],
});
expect(res.status).toBe(200);
}
const list = async (qs: string) => {
const res = await api.get(`${base()}${qs}`);
expect(res.status, qs).toBe(200);
return (await res.json()) as SessionsResponse;
};
const ids = (body: SessionsResponse) => body.sessions.map((s) => s.sessionId);
const sourceIn = (body: SessionsResponse, sessionId: string) =>
body.sessions.find((s) => s.sessionId === sessionId)?.source;
/**
* A Session created by an earlier process: its index row, and a Trace whose head carries
* `source` exactly as given (undefined writes no key). Nothing in this process has seen the
* meta, so the list reads it from the head — the path every row takes after a restart.
*/
async function seed(
n: number,
source: unknown,
opts: { workspace?: string; archived?: boolean; indexed?: boolean; client?: "org" } = {},
): Promise<string> {
const day = String(n).padStart(2, "0");
// Unique per case as well: the in-process source registry outlives a deleted Agent (ids
// are never reused in production), so a repeated id would be answered from a stale entry.
const minute = String(cases).padStart(2, "0");
const sessionId = `session-2026-07-${day}-09-${minute}-00-5eed${minute}${day}`;
const stamp = `2026-07-${day}T09:00:00.000Z`;
const workspace = opts.workspace ?? `/tmp/ws-source-${day}`;
if (opts.indexed !== false) {
t.deps.sessionsRepo.insert({
sessionId,
projectId,
agentId,
provider: "custom",
modelId: "m-x",
workspace,
approvalMode: "allow-all",
title: null,
...(opts.client !== undefined ? { client: opts.client } : {}),
createdAt: stamp,
lastActiveAt: stamp,
});
if (opts.archived) t.deps.sessionsRepo.setArchived(sessionId, stamp);
}
const meta = {
session_id: sessionId,
model_id: "m-x",
provider: "custom",
model_context_window: 1000,
system_prompt: "",
agent_state: "/tmp/a",
workspace,
...(source !== undefined ? { source } : {}),
};
await writeTraceFile(t.root, projectId, agentId, `2026-07-${day}`, sessionId, 1, [
sessionMeta(meta as Parameters<typeof sessionMeta>[0]),
userText(`work ${n}`),
]);
return sessionId;
}
/**
* One row of every source, a pre-source `user` row, a retired `benchmark` row, two archived
* ones, and three company rows: one sharing a Workspace with background rows, one archived,
* one alone in its Workspace.
*/
async function seedEverySource() {
return {
user: await seed(1, "user"),
legacyUser: await seed(2, undefined),
api: await seed(3, "api"),
schedule: await seed(4, "schedule"),
subagent: await seed(5, "subagent", { workspace: "/tmp/ws-source-shared" }),
cli: await seed(6, "cli", { workspace: "/tmp/ws-source-shared" }),
legacyBenchmark: await seed(7, "benchmark"),
archivedUser: await seed(8, "user", { archived: true }),
archivedSchedule: await seed(9, "schedule", { archived: true }),
company: await seed(10, "company", { workspace: "/tmp/ws-source-shared", client: "org" }),
archivedCompany: await seed(11, "company", { archived: true, client: "org" }),
companyOnly: await seed(12, "company", { workspace: "/tmp/ws-source-desk", client: "org" }),
};
}
it("files user rows under active, other programs' under background, archived rows under archived, and company rows under none", async () => {
const rows = await seedEverySource();
expect(new Set(ids(await list("?category=active")))).toEqual(
new Set([rows.user, rows.legacyUser]),
);
expect(new Set(ids(await list("?category=background")))).toEqual(
new Set([rows.api, rows.schedule, rows.subagent, rows.cli, rows.legacyBenchmark]),
);
expect(new Set(ids(await list("?category=archived")))).toEqual(
new Set([rows.archivedUser, rows.archivedSchedule]),
);
// Nowhere in the categories, and still a Session: the plain list serves every row.
const all = await list("");
for (const id of [rows.company, rows.archivedCompany, rows.companyOnly]) {
expect(sourceIn(all, id)).toBe("company");
}
});
it("refuses a category the list no longer has, or junk, rather than serving an unfiltered page", async () => {
await seed(1, "subagent");
for (const category of ["subagent", "schedule", "benchmark", "weird"]) {
expect((await api.get(`${base()}?category=${category}`)).status, category).toBe(400);
}
});
it("counts=1 totals active, background and archived over the whole list, broken down by Workspace, counting no company row", async () => {
await seedEverySource();
const counted = await list("?category=active&counts=1&limit=1");
expect(counted.sessions).toHaveLength(1);
expect(counted.counts).toEqual({ active: 2, background: 5, archived: 2 });
// The two background rows sharing a Workspace are counted there together, and the company
// row beside them is not.
expect(counted.workspaceCounts?.["/tmp/ws-source-shared"]).toEqual({
active: 0,
background: 2,
archived: 0,
});
// A Workspace holding only a company row is no group of the list: no totals, no stamp.
expect(counted.workspaceCounts?.["/tmp/ws-source-desk"]).toBeUndefined();
expect(counted.workspaceLatest?.["/tmp/ws-source-desk"]).toBeUndefined();
const summed = { active: 0, background: 0, archived: 0 };
for (const ws of Object.values(counted.workspaceCounts ?? {})) {
for (const key of Object.keys(summed) as (keyof typeof summed)[]) summed[key] += ws[key];
}
expect(summed).toEqual(counted.counts);
expect((await list("?category=active")).counts).toBeUndefined();
});
it("pages category=background by activity cursor, serving every background row once and no other", async () => {
const background: string[] = [];
for (let n = 1; n <= 7; n++) {
// Every third row is a person's conversation, interleaved with the background ones.
if (n % 3 === 0) await seed(n, "user");
else background.push(await seed(n, n % 2 === 0 ? "schedule" : "cli"));
}
const served: string[] = [];
let below: { lastActiveAt: string; sessionId: string } | undefined;
for (;;) {
const cursor = below
? `&before=${encodeURIComponent(`${below.lastActiveAt},${below.sessionId}`)}`
: "";
const page = (await list(`?order=activity&category=background&limit=3${cursor}`)).sessions;
served.push(...page.slice(0, 2).map((s) => s.sessionId));
if (page.length <= 2) break;
below = page[1];
}
// Newest activity first: the seeded stamps rise with n.
expect(served).toEqual([...background].reverse());
});
it("creates a cli Session for source cli, and accepts the retired benchmark as cli", async () => {
await configureModels();
for (const source of ["cli", "benchmark"]) {
const res = await api.post(base(), { source });
expect(res.status, source).toBe(201);
const { session } = (await res.json()) as SessionCreateResponse;
expect(session.source, source).toBe("cli");
expect(sourceIn(await list("?category=background"), session.sessionId), source).toBe("cli");
}
});
it("refuses a source the server writes itself, creating nothing", async () => {
await configureModels();
for (const source of ["api", "schedule", "subagent", "company", "user"]) {
expect((await api.post(base(), { source })).status, source).toBe(400);
}
expect((await list("")).sessions).toEqual([]);
});
it("reads an old Trace head after a restart: no source lists as active user, benchmark as background cli", async () => {
const legacyUser = await seed(1, undefined);
const legacyBenchmark = await seed(2, "benchmark");
const all = await list("");
expect(sourceIn(all, legacyUser)).toBe("user");
expect(sourceIn(all, legacyBenchmark)).toBe("cli");
expect(ids(await list("?category=active"))).toEqual([legacyUser]);
expect(ids(await list("?category=background"))).toEqual([legacyBenchmark]);
// The single-session GET reads the same way.
const single = (await (
await api.get(`/api/sessions/${legacyBenchmark}`)
).json()) as SessionResponse;
expect(single.session.source).toBe("cli");
});
it("adopts an unindexed old Trace with the same reading", async () => {
const legacyUser = await seed(1, undefined, { indexed: false });
const legacyBenchmark = await seed(2, "benchmark", { indexed: false });
const junk = await seed(3, "weird-origin", { indexed: false });
await t.deps.sessionService.adoptUnmanagedTraceSessions();
const all = await list("");
expect(sourceIn(all, legacyUser)).toBe("user");
expect(sourceIn(all, legacyBenchmark)).toBe("cli");
expect(sourceIn(all, junk)).toBe("user");
});
it("reads a Session company mode opened before the source was required as company, in no category", async () => {
// Its head records no source; its row carries the organization runtime's `org` stamp.
const oldDesk = await seed(1, undefined, { client: "org" });
const single = (await (await api.get(`/api/sessions/${oldDesk}`)).json()) as SessionResponse;
expect(single.session.source).toBe("company");
expect(sourceIn(await list(""), oldDesk)).toBe("company");
const counted = await list("?category=active&counts=1");
expect(counted.sessions).toEqual([]);
expect(counted.counts).toEqual({ active: 0, background: 0, archived: 0 });
});
it.each([
// A desk opened at a hire and never run.
["an org row", "org", "company", { active: 0, background: 0, archived: 0 }],
// An API Session whose first run never got as far as its Trace.
["an api row", "api", "api", { active: 0, background: 1, archived: 0 }],
] as const)(
"reads %s that has not run yet as the source its client stands for",
async (_row, client, source, counts) => {
// After a restart: no Trace, nothing in the registry. (Its first run records that source
// too: session-loader.test.ts.)
const sessionId = `session-2026-07-21-09-${String(cases).padStart(2, "0")}-00-0de5c001`;
const stamp = "2026-07-21T09:00:00.000Z";
t.deps.sessionsRepo.insert({
sessionId,
projectId,
agentId,
provider: "anthropic",
modelId: "claude-sonnet-4-6",
workspace: t.root,
approvalMode: "allow-all",
title: null,
client,
createdAt: stamp,
lastActiveAt: stamp,
});
expect(sourceIn(await list(""), sessionId)).toBe(source);
expect((await list("?counts=1")).counts).toEqual(counts);
},
);
it("opens a company-mode desk Session as company, keeping its org client, in no category", async () => {
await configureModels();
// The organization runtime's call.
const desk = await t.deps.sessionService.createSession({
projectId,
agentId,
client: "org",
source: "company",
});
expect(desk.source).toBe("company");
const got = (await (
await api.get(`/api/sessions/${desk.sessionId}`)
).json()) as SessionResponse;
expect(got.session.source).toBe("company");
expect(got.session.client).toBe("org");
const counted = await list("?category=active&counts=1");
expect(counted.sessions).toEqual([]);
expect(counted.counts).toEqual({ active: 0, background: 0, archived: 0 });
});
it("files a child a desk Session spawns under Background as subagent", async () => {
const childId = "session-2026-07-20-09-00-00-c41d0001";
const deskId = "session-2026-07-20-08-00-00-de5c0001";
adoptSession(
t.deps,
fakeSession(deskId, {
async *run() {
// Core's spawn site writes the child's meta; it reaches the desk with its origin.
yield withOrigin(
sessionMeta({
session_id: childId,
model_id: "m-child",
provider: "custom",
model_context_window: 1000,
system_prompt: "",
agent_state: `${t.root}/${projectId}/agents/${agentId}/agent_state`,
workspace: "/tmp/ws-desk",
source: "subagent",
}),
childId,
);
yield withOrigin(assistantText("child done"), childId);
yield assistantText("done");
},
}),
{ projectId, agentId, client: "org", workspace: "/tmp/ws-desk" },
);
await t.deps.manager.startTask(deskId, [userText("go")]);
await waitFor(() => t.deps.manager.statusOf(deskId) === "idle");
const background = await list("?category=background");
expect(ids(background)).toEqual([childId]);
expect(sourceIn(background, childId)).toBe("subagent");
expect(background.sessions[0]!.client).toBe("org");
});
it("opens a scheduled task's Session as schedule, in Background", async () => {
await configureModels();
// The scheduler's call (new-session mode).
const info = await t.deps.sessionService.createSession({
projectId,
agentId,
source: "schedule",
});
expect(info.source).toBe("schedule");
expect(sourceIn(await list("?category=background"), info.sessionId)).toBe("schedule");
// Read from session_meta, never from the index row, which stores no source.
const row = t.deps.sessionsRepo.findById(info.sessionId);
expect(row !== null && "source" in row).toBe(false);
});
});