A local-first multi-agent app development platform, built on PenguinHarness
/**
* Session index service.
*
* Lists are served from the DB index alone — no Trace directory scanning in steady state
* (#139), and no client-side filtering: every row is listed whichever client created it.
* Sessions that exist only as Trace files (left behind by a pre-server CLI) are adopted
* into the index once per boot by the startup sweep (`adoptUnmanagedTraceSessions`):
* the trace index's registration-time facts supply (provider, model_id) / workspace,
* and the row is stamped `client: "cli"` (approval_mode defaults, createdAt taken from
* the timestamp embedded in session_id).
* Create: via core's `agent.createSession` (the model reference is always a complete
* (provider, modelId) pair — both or neither; omitting both falls back to the
* Project's default reference, 400 if there is none); the new Session is
* added to session-manager's active table (state idle).
*/
import fs from "node:fs/promises";
import { agentsDir, createAgent, isSessionMeta, normalizeSessionSource } from "@adelie/core";
import type { AgentAssembly, ControlEnvContext, ProxyEnvPolicy, SpawnConfiner } from "@adelie/core";
import type {
ApprovalMode,
MessagingChannel,
SessionCategory,
SessionCategoryCounts,
SessionInfo,
SessionSandbox,
SessionSandboxPreset,
SessionSource,
ServerEvent,
UnavailableSandboxBackend,
} from "../api/types.js";
import { HttpError, isMissingCredential, modelCredentialMissing } from "../http/errors.js";
import { badRequest } from "../http/validate.js";
import type { SessionRow } from "../db/repos/sessions.js";
import type { SessionManager } from "../runtime/session-manager.js";
import { listCategory, readRecordedSource, unrunSource } from "../runtime/session-sources.js";
import { TraceIndexService, traceFilePath } from "./trace-index.js";
import { matchesWorkspaceGroup } from "./workspace-group.js";
import type { TraceIndex, TraceIndexStore } from "../mechanisms/traces.js";
import type { SessionIndex, SessionOrigins } from "../mechanisms/sessions.js";
import type { ProjectConfigStore } from "../mechanisms/projects.js";
import type { SandboxDimension, SandboxSettings } from "@adelie/core/plugin";
import { aboveSandboxCeiling } from "./sandbox-ceiling.js";
/** A stored policy's network level as the composer names it. */
function networkOf(policy: SandboxSettings): SessionSandbox["network"] {
return policy.network ?? "open";
}
/**
* A stored policy as the composer sees it, with which of its levels this server can enforce:
* `dimensions` is what the mounted sandbox backends implement between them — none on a
* deployment that has not installed one. `unavailable` is each backend that is enabled but
* failed to load or failed its check, with why; one for another platform is not among them.
* `presets` is the Sandbox card's table the composer names levels by, when there is one; the
* policy is `advanced` when it holds what no preset shows (masked paths, a read-only temp).
* `switchOn` is the card's switch, when the server reports it. Given the server's settings
* (`ceiling`), each preset wider than them is marked `aboveCeiling`, by the comparison
* `applySandboxPick` refuses a non-admin's pick with.
*/
export function sessionSandboxOf(
policy: SandboxSettings,
dimensions: readonly SandboxDimension[] = [],
unavailable: readonly UnavailableSandboxBackend[] = [],
presets?: readonly SessionSandboxPreset[],
switchOn?: boolean,
ceiling?: SandboxSettings,
): SessionSandbox {
const masksPaths = (policy.maskPaths ?? []).length > 0;
const advanced = masksPaths || policy.writableTemp === false;
const above = (p: SessionSandboxPreset) =>
ceiling !== undefined &&
aboveSandboxCeiling(p, { mode: ceiling.mode, network: networkOf(ceiling) }) !== null;
return {
mode: policy.mode,
network: networkOf(policy),
confinementSupported: dimensions.includes("fs-write"),
noNetworkSupported: dimensions.includes("network"),
localNetworkSupported: dimensions.includes("network-local"),
maskPathsSupported: dimensions.includes("mask-paths"),
...(masksPaths ? { masksPaths: true } : {}),
unavailableBackends: unavailable.map(({ name, reason }) => ({ name, reason })),
...(presets !== undefined
? { presets: presets.map((p) => ({ ...p, ...(above(p) ? { aboveCeiling: true } : {}) })) }
: {}),
...(advanced ? { advanced: true } : {}),
...(switchOn !== undefined ? { switchOn } : {}),
};
}
/**
* `base` with the composer's picks laid over it — the mask paths and the temp directory stay
* what the snapshot holds. A non-admin may tighten but never loosen past the server's settings
* (`defaults`): the admin's sandbox is the ceiling for everyone else, per Session or not.
*/
export function applySandboxPick(
base: SandboxSettings,
pick: Partial<SessionSandbox>,
defaults: SandboxSettings,
isAdmin: boolean,
localNetworkSupported = false,
): SandboxSettings {
const mode = pick.mode ?? base.mode;
const network = pick.network ?? networkOf(base);
// Picking a level no backend here can enforce would make every command fail closed; say so
// now instead. A policy that already holds it (a backend went away) fails at the command.
if (pick.network === "local" && !localNetworkSupported) {
throw new HttpError(
400,
"sandbox_unsupported",
"No sandbox backend on this server can limit the network to localhost.",
);
}
if (!isAdmin) {
const above = aboveSandboxCeiling(
{ mode, network },
{ mode: defaults.mode, network: networkOf(defaults) },
);
if (above === "mode") {
throw new HttpError(
403,
"sandbox_forbidden",
`Only an administrator can give a Session more filesystem access than the server's sandbox settings (${defaults.mode}).`,
);
}
if (above === "network") {
throw new HttpError(
403,
"sandbox_forbidden",
`Only an administrator can give a Session more network access than the server's sandbox settings (${networkOf(defaults)}).`,
);
}
}
const { network: _dropped, ...rest } = base;
return { ...rest, mode, ...(network === "open" ? {} : { network }) };
}
const SESSION_ID_TS_RE = /^session-(\d{4})-(\d{2})-(\d{2})-(\d{2})-(\d{2})-(\d{2})-[0-9a-f]{8}$/;
/** Stands in for the organization map when company mode is not wired in (tests, older assemblies). */
const EMPTY_ORG_IDS: ReadonlyMap<string, string> = new Map();
/** Derives creation time from the local timestamp embedded in session_id; returns null if it doesn't match. */
export function sessionIdCreatedAt(sessionId: string): string | null {
const m = SESSION_ID_TS_RE.exec(sessionId);
if (!m) return null;
const [, y, mo, d, h, mi, s] = m;
const date = new Date(Number(y), Number(mo) - 1, Number(d), Number(h), Number(mi), Number(s));
return Number.isNaN(date.getTime()) ? null : date.toISOString();
}
/**
* The order a Session list is served in: `created` (the default) is newest creation first;
* `activity` is most recent `lastActiveAt` first — the order the sidebar displays, and the only
* one an {@link ActivityCursor} pages.
*/
export type SessionListOrder = "created" | "activity";
/** A row's place in the activity order; as a `before` cursor, the last row the client holds. */
export interface ActivityCursor {
lastActiveAt: string;
sessionId: string;
}
/**
* The activity order: `lastActiveAt` descending, ties broken by `sessionId` descending; negative
* when `a` is the more recent. Plain `<` / `>` on both fields, never `localeCompare`: the client
* derives the cursor from a row and the server slices on it, so both sides must agree on one
* total order, and ICU collation (case, punctuation) is not one they can share. Stamps are ISO
* 8601 and ids ASCII, so this is code-point order.
*/
export function compareActivityDesc(a: ActivityCursor, b: ActivityCursor): number {
if (a.lastActiveAt !== b.lastActiveAt) return a.lastActiveAt > b.lastActiveAt ? -1 : 1;
if (a.sessionId !== b.sessionId) return a.sessionId > b.sessionId ? -1 : 1;
return 0;
}
/** The `created` order, unchanged since before the activity order existed. */
function compareCreatedDesc(a: SessionRow, b: SessionRow): number {
return b.createdAt.localeCompare(a.createdAt) || b.sessionId.localeCompare(a.sessionId);
}
/**
* A slice of a Session list: `offset` rows skipped (the `created` contract, also accepted under
* `activity`), or every row strictly below `before` in the activity order.
*/
export type SessionListPaging =
{ offset: number; limit: number } | { before: ActivityCursor; limit: number };
export interface SessionServiceDeps {
root: string;
sessions: SessionIndex;
manager: SessionManager;
projectConfig: ProjectConfigStore;
/** In-process origin registry derived from session_meta (the DB stores no source column). */
sources: SessionOrigins;
/** Trace-file index: discovery / adoption / stats serve from it (mtime-gated reconciler; no per-request walks). */
traceIndex: TraceIndex;
/** The index rows themselves (files and sessions), for the reads the service does directly. */
traceStore: TraceIndexStore;
/**
* Admin proxy-settings threading (same getter the session loader passes, see
* createCoreSessionLoader): the runtime created here is adopted by the manager and
* runs the Session's first Task, so it needs the command-subprocess proxy policy too.
*/
proxyEnv?: () => ProxyEnvPolicy | null;
/**
* Harness-control env threading (same policy the session loader passes): the server's
* API URL/token plus the Session coordinates, injected into command subprocesses so
* agents can drive the harness back through the CLI/API.
*/
controlEnv?: (ctx: ControlEnvContext) => Record<string, string>;
/**
* PATH threading (same getter the session loader passes): the shim directory holding
* this harness's own `penguin`, put in front of every command an Agent runs.
*/
pathPrepend?: () => string[];
/**
* Tells every user of a Project that a Session now exists. The list only ever learns
* about rows it did not create itself from this: a Session started by the CLI, by
* another tab, by a schedule, or by an agent spawning a child sat invisible until the
* next full reload without it. Optional so the service keeps unit-testing without a
* channel registry; absent means nobody is told.
*/
notifyProjectUsers?: (projectId: string, event: ServerEvent) => void;
/**
* The channel of the Session's ENABLED messaging binding, or null when none is enabled
* (SessionInfo.messagingChannel, the sidebar row's per-channel indicator — saved-but-
* disabled configs stay off the row). A lookup lambda rather than the repo, so the
* service stays decoupled from the bindings table; absent (older assemblies/tests)
* means the field is never set.
*/
messagingChannel?: (sessionId: string) => MessagingChannel | null;
/**
* Company mode: the organization owning a Session (a desk session, or a session
* contributing to a ticket), for `SessionInfo.orgId` — development mode's list hides
* those rows, the company sidebar groups them. Two shapes because the two flows cost
* differently: the single-Session GET asks about one id, a list asks once for the whole
* Project and looks its rows up in the returned map, so a long list never costs a query
* per row. Lambdas rather than the repo, so the service stays decoupled from the
* company-mode caches; absent (older assemblies/tests) means the field is never set.
*/
orgIdOfSession?: (sessionId: string) => string | undefined;
orgIdsOfProject?: (projectId: string) => ReadonlyMap<string, string>;
/** Spawn-confinement getter (the sandbox module's), forwarded into core beside proxyEnv. */
confineSpawn?: (ctx: ControlEnvContext) => SpawnConfiner | null;
/** The server's Sandbox settings: what a new Session's policy is snapshotted from. */
sandboxDefaults?: () => SandboxSettings;
/** Host-owned model-request hooks, forwarded to core for every Session LLM. */
assembly?: AgentAssembly;
/** The dimensions the mounted sandbox backends implement between them (none when absent). */
sandboxDimensions?: () => readonly SandboxDimension[];
/** The enabled sandbox backends that failed to load or failed their check, with why. */
sandboxUnavailable?: () => readonly UnavailableSandboxBackend[];
/** The names of the sandbox backends in use, in routing preference (none when absent). */
sandboxBackends?: () => readonly string[];
/** The Sandbox card's presets table, in table order (absent: the view carries none). */
sandboxPresets?: () => readonly SessionSandboxPreset[];
/** The Sandbox card's switch: whether new Sessions start confined (absent: not reported). */
sandboxSwitchOn?: () => boolean;
/** The approval mode a new Session starts with when its request names none (the default preset's). */
sandboxDefaultApproval?: () => ApprovalMode | undefined;
}
export class SessionService {
constructor(private readonly deps: SessionServiceDeps) {}
/** The policy a new Session starts with: the server's Sandbox settings. */
defaultSandbox(): SandboxSettings {
return this.deps.sandboxDefaults?.() ?? { mode: "danger-full-access" };
}
/** Whether this server can enforce the `local` network level right now. */
localNetworkSupported(): boolean {
return this.sandboxDimensions().includes("network-local");
}
private sandboxDimensions(): readonly SandboxDimension[] {
return this.deps.sandboxDimensions?.() ?? [];
}
/** A policy as the composer sees it, with which of its levels this server can enforce. */
sandboxView(policy: SandboxSettings): SessionSandbox {
const backends = this.deps.sandboxBackends?.() ?? [];
return {
...sessionSandboxOf(
policy,
this.sandboxDimensions(),
this.deps.sandboxUnavailable?.() ?? [],
this.deps.sandboxPresets?.(),
this.deps.sandboxSwitchOn?.(),
this.defaultSandbox(),
),
...(backends.length > 0 ? { backendsInUse: [...backends] } : {}),
};
}
/**
* What a new Session starts from, as the composer's draft reads it (the chat defaults): the
* settings' policy, plus the approval mode the default preset gives a request naming none.
*/
defaultsView(): SessionSandbox {
const approval = this.deps.sandboxDefaultApproval?.();
return {
...this.sandboxView(this.defaultSandbox()),
...(approval !== undefined ? { defaultApprovalMode: approval } : {}),
};
}
/**
* The approval mode a Session created without one starts with. An organization's Session
* keeps `allow-all`: its runtime names the mode it wants, and nobody is there to answer an
* ask a preset might bring. The other unattended creators — a scheduled run, a workflow —
* pass `allow-all` themselves (scheduler.ts, workflows/service.ts).
*/
private startApproval(requested: ApprovalMode | undefined, client?: string): ApprovalMode {
if (requested !== undefined) return requested;
if (client === "org") return "allow-all";
return this.deps.sandboxDefaultApproval?.() ?? "allow-all";
}
/** A Session's policy: its snapshot, or — for a row from before snapshots — the settings. */
sandboxOf(row: SessionRow): SandboxSettings {
return row.sandbox ?? this.defaultSandbox();
}
/**
* The policy a pick would give one Session, checked — the non-admin ceiling and what this
* server can enforce — and not written: a PATCH checks every field before it writes any.
*/
pickSandbox(row: SessionRow, pick: Partial<SessionSandbox>, isAdmin: boolean): SandboxSettings {
return applySandboxPick(
this.sandboxOf(row),
pick,
this.defaultSandbox(),
isAdmin,
this.localNetworkSupported(),
);
}
/** Stores one Session's policy (`pickSandbox`'s): its next command runs under it. */
updateSandbox(sessionId: string, policy: SandboxSettings): void {
this.deps.sessions.updateSandbox(sessionId, policy);
}
/**
* DB row -> SessionInfo (run status and pending approval count come from session-manager).
* Async because `source` is derived from session_meta: a registry miss (Session predating
* this process) falls back to reading the Trace head once (see sourceOf). `traces` is the
* list flow's one-walk discovery result; without it a miss locates the shard itself.
*
* `orgIds` is the list flow's one-query organization map (see listSessions); without it the
* organization is a point lookup, which is what the single-Session paths want.
*/
async toInfo(
row: SessionRow,
hasTrace: boolean,
orgIds?: ReadonlyMap<string, string>,
): Promise<SessionInfo> {
const source = await this.sourceOf(row, hasTrace);
const messagingChannel = this.deps.messagingChannel?.(row.sessionId) ?? null;
const orgId = orgIds ? orgIds.get(row.sessionId) : this.deps.orgIdOfSession?.(row.sessionId);
const backgroundTasks = this.deps.manager.backgroundTasksOf(row.sessionId);
return {
sessionId: row.sessionId,
projectId: row.projectId,
agentId: row.agentId,
provider: row.provider,
modelId: row.modelId,
workspace: row.workspace,
approvalMode: row.approvalMode,
sandbox: this.sandboxView(this.sandboxOf(row)),
...(row.thinkingLevel ? { thinkingLevel: row.thinkingLevel } : {}),
...(row.title !== null ? { title: row.title } : {}),
...(source !== undefined ? { source } : {}),
createdAt: row.createdAt,
lastActiveAt: row.lastActiveAt,
status: this.deps.manager.statusOf(row.sessionId),
pendingApprovalCount: this.deps.manager.pendingApprovalCount(row.sessionId),
pendingFollowUpCount: this.deps.manager.pendingFollowUpCount(row.sessionId),
hasTrace,
archived: (row.archivedAt ?? null) !== null,
...(messagingChannel !== null ? { messagingChannel } : {}),
...(orgId !== undefined ? { orgId } : {}),
...(row.client !== null && row.client !== undefined ? { client: row.client } : {}),
...(backgroundTasks !== undefined ? { backgroundTasks } : {}),
};
}
/**
* A Session's source, with session_meta as the single source of truth: the in-process
* registry answers first (populated at creation / subagent registration / forks / adoption /
* index registration); on a miss (a Session created before this process started) the
* trace index's registration-time facts answer — the reconciler head-read the earliest
* shard once when the file first appeared, so no file is touched here. A head that records
* no source is read with the row's client (readRecordedSource). A Session with no Trace yet
* is NOT cached — its meta appears with the first run — and reads as its row says
* (unrunSource): the organization runtime's as `company`, the Agent API's as `api`, any other
* as unknown.
*/
private async sourceOf(row: SessionRow, hasTrace: boolean): Promise<SessionSource | undefined> {
const known = this.deps.sources.get(row.sessionId);
if (known !== undefined) return readRecordedSource(known, row.client);
if (!hasTrace) return unrunSource(row.client);
const facts = this.deps.traceStore.getSession(row.sessionId);
if (!facts?.metaRead) return undefined; // Unreadable/unregistered: stay unknown, retry on the next list.
this.deps.sources.set(row.sessionId, facts.source);
return readRecordedSource(facts.source, row.client);
}
/** Whether this Session already has a Trace record (a Task has been run): answered by the index (reconciled first). */
async hasTrace(row: SessionRow): Promise<boolean> {
return (await this.discoverTraces(row.projectId, row.agentId)).has(row.sessionId);
}
/**
* The list category of a row (see listCategory): none for a `company` Session, archived or
* not, which the list never serves; otherwise archived wins (an explicit user action), then
* its source's.
*/
private async categoryOf(row: SessionRow, hasTrace: boolean): Promise<SessionCategory | null> {
return listCategory(await this.sourceOf(row, hasTrace), (row.archivedAt ?? null) !== null);
}
/**
* List, sorted by createdAt descending — or, with `order: "activity"`, by lastActiveAt
* descending (ties by sessionId, see {@link compareActivityDesc}). Every row is served
* **straight from the DB**, whichever client created it, with no Trace directory scanning —
* the answer to many-session sidebar reloads re-walking the filesystem on every request (#139).
* Sessions living only in the Trace directory were adopted into the index by the
* boot-time sweep (`adoptUnmanagedTraceSessions`), so listing never discovers. One
* lazy discovery walk still runs for a list call that contains rows this process has
* not classified yet (no in-process source entry): it supplies the Trace locations for
* the one-time head reads and backfills the `has_trace` cache; once every row is
* classified, list calls touch only the DB.
*
* Optional `paging` returns just that slice (the sidebar pages with limit+1 to detect
* "has more"); slicing happens before toInfo, so per-request source derivation (lazy
* Trace-head reads) stays bounded by the page size.
*
* The `before` form pages the activity order by cursor: only rows strictly below it are
* walked and served. An offset cannot page that order, because a row below the offset that
* becomes active moves above it and the next page would skip a row; a cursor stays put — the
* moved row is simply not served again (the client learns of it from `session_state`). The
* offset form keeps serving the `created` order exactly as before.
*
* `category` filters to one sidebar bucket **before** paging, so offset/limit page
* within the category. Filtering needs each walked row's category (a possible
* Trace-head read per row, cached in the sources registry); without `withCounts`
* the walk stops as soon as the requested page is complete. `withCounts` classifies
* every row, a cursor or not, and returns per-category totals over the whole list — plus
* the same totals broken down by Workspace path, and each path's newest Session's
* `createdAt` — so the sidebar can label the collapsed folders, list every Workspace that holds
* Sessions (not only the ones its loaded pages happen to touch) and place the groups
* by recency, all without loading them.
*
* `workspaceGroup` filters the same way, to one Workspace group (see workspace-group.ts),
* so a sidebar grouped by Workspace pages each group down its OWN stream instead of
* sharing one per-Agent cursor — without it, one group's "load more" consumes the page
* its siblings were about to read, and their rows move on screen untouched. The two
* filters compose; the returned counts stay whole-Agent either way.
*
* A `company` Session — company mode's desk and ticket Sessions, which only company mode's
* own views list — belongs to no category (listCategory), archived or not: every classified
* form of the list (`category`, `workspaceGroup` or `withCounts`) leaves it out of the page,
* the totals, the Workspace breakdown and its stamps alike. The plain form, which classifies
* nothing, still serves every row.
*
* `excludeOrg` drops the rows an organization owns (its desk and ticket sessions, and the
* sub-sessions they spawned) from the stream BEFORE anything else looks at it — the page,
* `counts`, `workspaceCounts`, `workspaceLatest` and the limit+1 "has more" all describe the
* same own-rows stream. It is what development mode's list asks for: that list draws the
* user's own conversations, and a total or a stamp that still counted a desk or a ticket
* session would make its Workspace appear as a group the list can never fill. The `company`
* rule above does not replace it: the sub-sessions are `subagent` Sessions, a person's
* conversation attached to a ticket is stamped `org` but stays `user`, and a row the
* organization caches name before the reconcile pass stamps it reads as `user`. Without the
* flag every row is served, whichever client created it, but for that rule.
*/
async listSessions(
projectId: string,
agentId: string,
opts: {
paging?: SessionListPaging;
order?: SessionListOrder;
category?: SessionCategory;
workspaceGroup?: string;
withCounts?: boolean;
excludeOrg?: boolean;
} = {},
): Promise<{
sessions: SessionInfo[];
counts?: SessionCategoryCounts;
workspaceCounts?: Record<string, SessionCategoryCounts>;
workspaceLatest?: Record<string, string>;
}> {
const { paging, order = "created", category, workspaceGroup, withCounts, excludeOrg } = opts;
const rows = new Map(
this.deps.sessions.listByAgent(projectId, agentId).map((r) => [r.sessionId, r]),
);
// One query for the whole Project's organization-owned sessions, looked up per row
// below: the company caches are small, and a lookup per row would put a statement
// behind every entry of a long sidebar list.
const orgIds = this.deps.orgIdsOfProject?.(projectId) ?? EMPTY_ORG_IDS;
if (excludeOrg) {
// The durable `client` stamp answers first: it survives the organization and is
// inherited by sub-sessions, which no cache names. The caches catch a row the
// reconcile pass has not stamped yet.
for (const [id, row] of rows) if (row.client === "org" || orgIds.has(id)) rows.delete(id);
}
let traces: ReadonlySet<string> | undefined;
if ([...rows.values()].some((r) => this.deps.sources.get(r.sessionId) === undefined)) {
// Hydration pass: some rows predate this process and are unclassified — one
// reconciled index read supplies discovery so sourceOf's facts lookups and the
// has_trace cache need no per-row work. Steady state (everything classified)
// skips this.
traces = await this.discoverTraces(projectId, agentId);
for (const row of rows.values()) {
if (!row.hasTrace && traces.has(row.sessionId)) {
row.hasTrace = true;
this.deps.sessions.markHasTrace(row.sessionId);
}
}
}
const sorted = [...rows.values()].sort(
order === "activity" ? compareActivityDesc : compareCreatedDesc,
);
// The rows a cursor leaves to serve are a suffix of the activity order: those from `start` on.
const before = paging && "before" in paging ? paging.before : undefined;
let start = 0;
if (before) {
const below = sorted.findIndex((row) => compareActivityDesc(row, before) > 0);
start = below === -1 ? sorted.length : below;
}
const skip = paging && "offset" in paging ? paging.offset : 0;
const rowHasTrace = (row: SessionRow): boolean =>
traces ? traces.has(row.sessionId) : row.hasTrace === true;
const toPage = (page: SessionRow[]) =>
Promise.all(page.map((row) => this.toInfo(row, rowHasTrace(row), orgIds)));
// No classification asked for: slice straight away (the pre-category behavior).
if (category === undefined && workspaceGroup === undefined && !withCounts) {
const from = start + skip;
return {
sessions: await toPage(paging ? sorted.slice(from, from + paging.limit) : sorted),
};
}
const want = paging ? skip + paging.limit : Infinity;
const counts: SessionCategoryCounts = { active: 0, background: 0, archived: 0 };
const workspaceCounts: Record<string, SessionCategoryCounts> = {};
const workspaceLatest: Record<string, string> = {};
const matched: SessionRow[] = [];
for (const [i, row] of sorted.entries()) {
// Rows above a cursor are the client's already: never served, and classified only for
// the totals, which are whole-list.
const servable = i >= start;
if (!servable && !withCounts) continue;
if (!withCounts && matched.length >= want) break;
const cat = await this.categoryOf(row, rowHasTrace(row));
// A company Session is in no category: neither served nor counted, nor stamped on its
// Workspace, so no total describes a row the list cannot serve.
if (cat === null) continue;
counts[cat] += 1;
if (withCounts) {
const ws = (workspaceCounts[row.workspace] ??= { active: 0, background: 0, archived: 0 });
ws[cat] += 1;
// A path's newest Session by creation, whichever order the walk is in.
const latest = workspaceLatest[row.workspace];
if (latest === undefined || row.createdAt.localeCompare(latest) > 0) {
workspaceLatest[row.workspace] = row.createdAt;
}
}
const wanted =
servable &&
(category === undefined || cat === category) &&
(workspaceGroup === undefined || matchesWorkspaceGroup(row.workspace, workspaceGroup));
if (wanted && matched.length < want) matched.push(row);
}
const sessions = await toPage(paging ? matched.slice(skip, want) : matched);
return withCounts ? { sessions, counts, workspaceCounts, workspaceLatest } : { sessions };
}
/**
* Session stats (Agents list card): total count = size of the union of DB index
* ∪ Trace directory discovery; activity = number of active Sessions per day over
* the last `days` days (deduplicated count of Sessions created that day or with a
* Trace record that day; index 0 = earliest, last index = today). Counts only —
* does not backfill index rows.
*/
async sessionStats(
projectId: string,
agentId: string,
days: number,
): Promise<{ sessionCount: number; activity: number[] }> {
const all = new Set<string>();
const byDate = new Map<string, Set<string>>();
const mark = (date: string, sessionId: string): void => {
all.add(sessionId);
const set = byDate.get(date) ?? new Set<string>();
set.add(sessionId);
byDate.set(date, set);
};
// Trace activity from the index (one mtime-gated reconcile, then a pure DB read —
// this used to walk the Agent's ENTIRE trace history on every agents-list request):
// the date is the shard's date directory (local yyyy-mm-dd, core's writing convention).
await this.deps.traceIndex.reconcileAgent(projectId, agentId);
for (const f of this.deps.traceStore.listFilesByAgent(projectId, agentId)) {
mark(f.date, f.sessionId);
}
// DB index: the creation day also counts as active (a Session that hasn't run a Task yet produces no Trace).
for (const row of this.deps.sessions.listByAgent(projectId, agentId)) {
const created = new Date(row.createdAt);
if (Number.isNaN(created.getTime())) all.add(row.sessionId);
else mark(localDate(created), row.sessionId);
}
const activity: number[] = [];
const now = new Date();
for (let i = days - 1; i >= 0; i--) {
const d = new Date(now.getFullYear(), now.getMonth(), now.getDate() - i);
activity.push(byDate.get(localDate(d))?.size ?? 0);
}
return { sessionCount: all.size, activity };
}
/**
* Create a Session: the model reference is a complete `(provider, modelId)` pair.
* Half a reference is a client error, never something to resolve — the missing half
* is never guessed, since a guessed provider would send an entry's credential to a
* vendor nobody named. Omitting both falls back to the Project's default reference
* (400 prompting to configure a model first if there is none). `workspace` is already
* validated by the route guard. The new Session is added to the active table
* (idle).
*/
async createSession(args: {
projectId: string;
agentId: string;
/** Upstream id of the session's model; always paired with provider. Omit both for the Project's default reference. */
modelId?: string;
/** The provider group for `modelId`; always paired with modelId, never inferred. */
provider?: string;
workspace?: string;
approvalMode?: ApprovalMode;
/** The composer's sandbox picks; omitted halves take the server's settings. */
sandbox?: Partial<SessionSandbox>;
/** Whether the creator is an administrator (may loosen past the settings). Default false. */
isAdmin?: boolean;
/**
* What kind of conversation this is, recorded in the Session's session_meta: `schedule`
* from the scheduler, `company` from the organization runtime, `cli` from `penguin run`
* (the only source a request may name), `api` from an Agent API run; absent means `user`,
* a person's conversation.
*/
source?: SessionSource;
/**
* Creating-client hint stored on the index row (`POST .../sessions` body `client`):
* "cli" from the CLI, defaulting to "web". "org" and "api" are not accepted over HTTP —
* the organization runtime and the Agent API's run handler call this method directly and
* are the only callers that pass them, so no request can claim either provenance for
* itself ("api" is what lets the Agent API continue a Session).
*/
client?: "web" | "cli" | "org" | "api";
}): Promise<SessionInfo> {
if ((args.modelId === undefined) !== (args.provider === undefined)) {
throw badRequest(
"modelId and provider must be given together as a (provider, modelId) pair: specify both, or neither to use the Project's default model.",
);
}
// Checked before anything is created: a refused pick must not leave a Session behind.
const sandbox = this.snapshotSandbox(args);
let modelId: string;
let provider: string;
if (args.modelId !== undefined && args.provider !== undefined) {
modelId = args.modelId;
provider = args.provider;
} else {
// The guard above leaves only "both omitted" here: fall back to the Project default.
const def = await this.deps.projectConfig.getDefaultModelRef(args.projectId);
if (def === undefined) {
throw new HttpError(
400,
"no_default_model",
"This Project has no default model yet. Add a model on the Models page and set it as the default first.",
);
}
modelId = def.model_id;
provider = def.provider;
}
const agent = await createAgent({
root: this.deps.root,
projectId: args.projectId,
agentId: args.agentId,
...(this.deps.proxyEnv ? { proxyEnv: this.deps.proxyEnv } : {}),
...(this.deps.controlEnv ? { controlEnv: this.deps.controlEnv } : {}),
...(this.deps.pathPrepend ? { pathPrepend: this.deps.pathPrepend } : {}),
...(this.deps.confineSpawn ? { confineSpawn: this.deps.confineSpawn } : {}),
...(this.deps.assembly ? { assembly: this.deps.assembly } : {}),
});
let session;
try {
session = await agent.createSession({
modelId,
provider,
...(args.workspace !== undefined ? { workspaceDir: args.workspace } : {}),
// The source is recorded in core session_meta (Trace); the index row stores none.
...(args.source !== undefined ? { source: args.source } : {}),
});
} catch (err) {
// A missing credential is its own category (the frontend shows localized text
// by code); other core errors (the pair naming no configured entry, Workspace
// not existing, etc.) are collapsed to 400 — the guard already blocks most cases.
if (isMissingCredential(err)) throw modelCredentialMissing(modelId);
throw new HttpError(
400,
"session_create_failed",
err instanceof Error ? err.message : String(err),
);
}
// The source is read from the just-created core Session's session_meta (the single
// source of truth) rather than echoing args.source back: what the registry serves is
// exactly what the Trace will record.
const metaMsg = session.metaMessage;
const source = normalizeSessionSource(
isSessionMeta(metaMsg) ? metaMsg.payload.source : undefined,
);
this.deps.sources.set(session.sessionId, source);
const createdAt = new Date().toISOString();
const row: SessionRow = {
sessionId: session.sessionId,
projectId: args.projectId,
agentId: args.agentId,
provider: session.provider,
modelId: session.modelId,
workspace: session.workspaceDir,
approvalMode: this.startApproval(args.approvalMode, args.client),
sandbox,
title: null,
// The creator's hint: "cli" when the CLI created this Session through the API,
// "org" when the organization runtime opened a desk or a ticket session, "api" when an
// Agent API run did, otherwise "web" (schedule runs included). NULL means a legacy row,
// treated as web.
client: args.client ?? "web",
// Creation is the first activity; the first driven run advances it (see SessionManager.drive).
lastActiveAt: createdAt,
createdAt,
};
this.deps.sessions.insert(row);
this.deps.manager.adopt(row, session);
// After the insert: a reader who reacts by fetching the list must find the row there.
this.deps.notifyProjectUsers?.(args.projectId, {
type: "session_created",
projectId: args.projectId,
agentId: args.agentId,
sessionId: row.sessionId,
source,
});
return this.toInfo(row, false);
}
/** A new Session's snapshot: the settings, with the creator's picks (checked) on top. */
private snapshotSandbox(args: {
sandbox?: Partial<SessionSandbox>;
isAdmin?: boolean;
}): SandboxSettings {
const defaults = this.defaultSandbox();
return args.sandbox === undefined
? defaults
: applySandboxPick(
defaults,
args.sandbox,
defaults,
args.isAdmin ?? false,
this.localNetworkSupported(),
);
}
/**
* Absolute path of a Session's **latest** Trace file (the current context shard);
* undefined when no Trace exists. Costs a directory walk, so only the single-session
* GET includes it in the DTO (see SessionInfo.tracePath) — the web's `/model` switch
* hands it to the new session's `[model_switch_from]` block so the model can read the
* source history itself when it needs it.
*/
async latestTracePath(row: SessionRow): Promise<string | undefined> {
await this.deps.traceIndex.reconcileAgent(row.projectId, row.agentId);
let files = this.deps.traceStore.listFilesBySession(row.projectId, row.agentId, row.sessionId);
if (files.length === 0) {
// Index miss with disk possibly ahead: one forced diff, then retry (the consumers'
// rule — a stale index costs one extra scan, never a missing resume shard).
await this.deps.traceIndex.reconcileAgent(row.projectId, row.agentId, { force: true });
files = this.deps.traceStore.listFilesBySession(row.projectId, row.agentId, row.sessionId);
}
const latest = files.at(-1);
return latest === undefined ? undefined : traceFilePath(this.deps.root, latest);
}
/**
* One walk over the Trace directory: session_id → its **earliest** shard (the shard
* whose head carries the original session_meta). Discovery (which Sessions have
* records) and the meta-read location come out of a single pass, so classifying every
* row (`counts=1`) costs one directory walk total instead of one per Session.
*/
private async discoverTraces(projectId: string, agentId: string): Promise<Set<string>> {
await this.deps.traceIndex.reconcileAgent(projectId, agentId);
const out = new Set<string>();
for (const f of this.deps.traceStore.listFilesByAgent(projectId, agentId)) {
out.add(f.sessionId);
}
return out;
}
/**
* Startup adoption sweep: walks the whole trace tree once per boot and adopts every
* unmanaged Session (a Trace with no index row — legacy CLI-direct runs) as a
* `client: "cli"` row, so lists stay pure-SQLite afterwards. Enumerates
* `<root>/<project>/agents/<agent>/` directories directly — legacy Traces can live
* under Projects the DB has never seen — and reuses the existing discovery/adoption
* path per Agent (mtime-gated TraceIndexService reconcile, then registration-time
* facts; adoption reads no file itself). Idempotent (insertOrIgnore), so re-running —
* e.g. after a hot swap re-assembles the business surface — only costs the gated
* reconcile. Returns the number of rows adopted.
*/
async adoptUnmanagedTraceSessions(): Promise<number> {
let adopted = 0;
for (const projectId of await listChildDirs(this.deps.root)) {
const agentIds = await listChildDirs(agentsDir(this.deps.root, projectId));
for (const agentId of agentIds) {
// A dot-directory (`.deleting/`, where a deleted Agent's files wait) is never an Agent.
if (agentId.startsWith(".")) continue;
const known = new Set(
this.deps.sessions.listByAgent(projectId, agentId).map((r) => r.sessionId),
);
for (const sessionId of await this.discoverTraces(projectId, agentId)) {
if (known.has(sessionId)) continue;
if (this.adoptTraceSession(projectId, agentId, sessionId) !== null) adopted += 1;
}
}
}
return adopted;
}
/**
* Adopts a Session that exists only in the Trace directory, from the index's
* registration-time facts (the reconciler head-read the earliest shard's session_meta
* once when the file first appeared — adoption itself reads no file).
*/
private adoptTraceSession(
projectId: string,
agentId: string,
sessionId: string,
): SessionRow | null {
const facts = this.deps.traceStore.getSession(sessionId);
if (!facts?.metaRead) return null; // Corrupt/unreadable head: skip (does not block the list; retried by a later reconcile)
// An older Trace version's session_meta lacks provider (the model reference
// wasn't split into separate fields yet): no backward compat, skip adoption
// (core will give a clear error on resume; the product hasn't launched yet, so
// old data can simply be deleted and recreated).
if (facts.provider === null || facts.modelId === null) return null;
// Registration already narrowed the source (a head without one stays `null`, read with the
// row's client); record it in the registry (single source of truth).
this.deps.sources.set(sessionId, facts.source);
const createdAt = sessionIdCreatedAt(sessionId) ?? facts.firstTs ?? new Date().toISOString();
const row: SessionRow = {
sessionId,
projectId,
agentId,
provider: facts.provider,
modelId: facts.modelId,
workspace: facts.workspace,
// The approval mode for an unmanaged Session (started via the CLI) isn't in the Trace, so it's backfilled with the default value.
approvalMode: "allow-all",
title: null,
// Adopted = a Trace this server never created, i.e. a legacy CLI-direct run: the
// row keeps that provenance, and lists serve it like any other.
client: "cli",
hasTrace: true,
createdAt,
// The CLI's own activity leaves no mark on this row (this server drives none of its
// runs), so an adopted Session reads as last-active at its creation time until it is
// resumed here; the Trace tail is not consulted (see SessionRow.lastActiveAt).
lastActiveAt: createdAt,
};
// Idempotent backfill: concurrent list calls may discover the same Session for the first time simultaneously (consistent with AgentsRepo's convention).
this.deps.sessions.insertOrIgnore(row);
return row;
}
}
/** Child directory names of `dir` (empty on a missing/unreadable directory — a fresh root has no Projects yet). */
async function listChildDirs(dir: string): Promise<string[]> {
try {
const entries = await fs.readdir(dir, { withFileTypes: true });
return entries.filter((e) => e.isDirectory()).map((e) => e.name);
} catch {
return [];
}
}
/** Local date as yyyy-mm-dd (matches the Trace date directory convention: core's internal formatLocalDate, not publicly exported). */
function localDate(d: Date): string {
const pad = (n: number) => (n < 10 ? `0${n}` : `${n}`);
return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
}