Skip to content

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

43.4 KB
Raw Blame
/**
 * 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())}`;
}