@adelie/server 0.0.0-stage → 0.4.2

package/dist/plugin/index.d.ts

@@ -0,0 +1,3002 @@
+import { SpawnConfiner, ThinkingLevelName, OmniMessage, ToolCallPayload, ProjectConfig, ModelRef, PluginTables, ListEndpointModelsOptions, ModelRequestContext, ProxyEnvPolicy, ControlEnvContext, AgentAssembly, ApproveFn, StopReason, CompactAvailability, SessionTitleResult, BackgroundCommandInfo, ToolDetachResult, BackgroundSubagentInfo, SubagentMessageOptions, SubagentMessageOutcome } from '@adelie/core';
+import { SandboxProviderSource, SandboxSettings, SandboxDimension, SandboxLimit } from '@adelie/core/plugin';
+import { Slot, Opaque } from '@adelie/core/kernel';
+import { ApprovalMode, ModelRefDto, ChatDefaultsDto, CommandPolicyDto, ModelVisionDetectRequest, ModelVisionDetectResponse, ModelTestRequest, ModelTestResponse, ModelProtocolDetectRequest, ModelProtocolDetectResponse, EndpointModelListRequest, EndpointModelListResponse, ModelsResponse, ModelsUpdateRequest, ServerEvent, MessagingChannel, UnavailableSandboxBackend, SessionSandboxPreset, SessionSandbox, SessionInfo, SessionCategory, SessionCategoryCounts, ModelScopeAuthFlowStatusResponse, SessionStatus, SessionBackgroundTasks, PendingSteeringInfo, PendingFollowUpInfo, AgentConfigDto, AgentConfigUpdateRequest, AgentKernelUpdateResponse, VaultResponse, VaultUpdateRequest, PluginUpdateRef, MessagingRuntimeStatus, PluginConfiguration, ContributionsResponse, RendererRef } from '../api/types.js';
+export { PluginConfigField } from '../api/types.js';
+import { ThinkingLevelName as ThinkingLevelName$1 } from '@adelie/core/interfaces';
+import { SessionSource } from '@adelie/core/omnimessage';
+import { Hono } from 'hono';
+import '@adelie/hmr';
+
+interface UserRow {
+    userId: string;
+    passwordHash: string;
+    isAdmin: boolean;
+    /** Still using the initial password (seeded / set by an admin); cleared to 0 once the user changes it. */
+    passwordIsInitial: boolean;
+    /** Nickname shown in place of the id; null = never set. */
+    displayName: string | null;
+    /** Avatar as a data URL; null = never set. */
+    avatar: string | null;
+    /** Most recent successful sign-in (ISO); null = never signed in — an account that exists but has not been used yet. */
+    lastLoginAt: string | null;
+    createdAt: string;
+}
+
+/**
+ * "desktop" and "setup" may set a password without the old one (theirs is random and was never
+ * shown); desktop-only routes open to "desktop" alone. "token" is the local API token's Bearer
+ * header — per request, never a stored row. Anything else reads as "password".
+ */
+type SessionVia = "password" | "desktop" | "setup" | "token";
+
+declare class SandboxService {
+    private mounted;
+    /**
+     * name → why it FAILED: it could not load, or failed its check on a host it is meant for —
+     * never silently absent. Surfaced in the fail-closed message and on the settings card.
+     */
+    private loadErrors;
+    /**
+     * The backends that declined: this host is not theirs (a Linux backend on Windows). Nothing
+     * is wrong with a deployment that installs one backend per platform, so a decline is not a
+     * failure — it is listed only when NO backend serves, where it is the explanation.
+     */
+    private declinedNames;
+    /** Every registration in routing order, with how its latest load settled. */
+    private readonly registrations;
+    /**
+     * Ships with confinement OFF (`danger-full-access`): the default flips to
+     * workspace-write together with the deployment-facing config surface, so a
+     * deployment gains the switch before the enforcement — otherwise every host without
+     * a usable backend would fail every command the moment this code arrives.
+     */
+    private settings;
+    private readonly ready;
+    /**
+     * @param registrations - the backends plugins registered (see the sandbox registry on
+     *   PenguinInterface). Loading is async, but create() and the confiner are sync: a
+     *   confining policy resolved before loading settles fails closed rather than
+     *   waiting. The default settings never consult a backend, so that window only
+     *   exists for deployments flipping the mode in the first milliseconds after boot.
+     */
+    constructor(registrations?: Iterable<[string, SandboxProviderSource]>);
+    /** Rebuilds the mounted / failed / declined views from the registrations, in routing order. */
+    private record;
+    /**
+     * Loads again every backend whose load failed and that registered a loader (a bare promise
+     * cannot be re-run). Called after the sandbox's settings are saved: a backend whose check
+     * failed on its own setting mounts once that setting is fixed. Resolves when those settle.
+     */
+    retryFailed(): Promise<void>;
+    /** Resolves when every registered backend has loaded (or failed to). */
+    whenReady(): Promise<void>;
+    /** Replaces the active settings (the config surface's write path). */
+    configure(settings: SandboxSettings): void;
+    /** The active settings as a plain copy (the config surface's read side). */
+    currentSettings(): SandboxSettings;
+    /**
+     * The active settings as parked state, or undefined for the pristine default. The
+     * omission is load-bearing compatibility: a default deployment keeps parking
+     * `{ motd }`, which any platform bundle's context schema accepts. Once confinement
+     * is configured the field enters the document, and from then on pushing a
+     * sandbox-ignorant bundle is BLOCKED by schema validation — the right failure:
+     * refusing the swap beats a swap that silently un-confines the deployment.
+     */
+    parkedSettings(): SandboxSettings | undefined;
+    /** The backends that failed to load, each with why (diagnostics / the config surface). */
+    failures(): Array<{
+        name: string;
+        reason: string;
+    }>;
+    /** The backends that declined because this host is not theirs (the config surface). */
+    declined(): string[];
+    /**
+     * The mounted backends and what each implements, in routing preference: the one a policy
+     * goes to first (diagnostics / the config surface).
+     */
+    backends(): Array<{
+        name: string;
+        dimensions: readonly SandboxDimension[];
+        mechanism?: string;
+        limits?: readonly SandboxLimit[];
+    }>;
+    /**
+     * The closure handed to the runtime: rewrites each spawn's argv under the active
+     * settings. Pure and self-contained, so the previous platform's confiner keeps
+     * serving during a hot-swap freeze window.
+     */
+    confiner(): SpawnConfiner;
+    /**
+     * The same closure under a policy the caller keeps — a Session's own snapshot. The
+     * backends are still this service's, so a backend change reaches every Session.
+     */
+    confinerFor(policyOf: () => SandboxSettings): SpawnConfiner;
+    /**
+     * The preferred mounted backend implementing every required dimension (byPreference), or a
+     * fail-closed throw.
+     */
+    private pick;
+    private failedSuffix;
+}
+declare const Sandbox_base: (abstract new () => Pick<SandboxService, "configure" | "currentSettings" | "parkedSettings" | "backends" | "failures" | "declined" | "retryFailed" | "confiner" | "confinerFor" | "whenReady">) & (<C>(target: C, context: ClassDecoratorContext) => C);
+/** Confinement: settings, the active confiner, and which backends are mounted. */
+declare abstract class Sandbox extends Sandbox_base {
+}
+interface SandboxSlots {
+    /**
+     * A backend: its static half here (name, the dimensions it implements), its code half
+     * bound by the contributor — a provider, or a promise of one for backends that probe.
+     */
+    providers: Slot<{
+        name: string;
+        dimensions: SandboxDimension[];
+    }, SandboxProviderSource>;
+}
+
+/**
+ * Screen snapshot -> ANSI restore stream, plus plain-text capture.
+ *
+ * This is what makes a browser refresh (or a reconnect from a second device) show the
+ * terminal exactly as it was: the daemon keeps an authoritative headless xterm per pty, and
+ * on attach it *re-renders* that grid as an escape-sequence stream the client's real xterm
+ * replays into an identical screen. That beats the two obvious alternatives:
+ *
+ * - Replaying the raw pty byte log: unbounded, and full-screen programs (vim, top) replay
+ *   as a flicker of stale frames.
+ * - Sending a JSON cell grid: a 200k-object payload per attach, parsed on the UI thread.
+ *
+ * Cursor alignment is the subtle part. The restore writes `scrollback + rows` lines, so the
+ * client's viewport ends up holding exactly the server's viewport, and only then is the
+ * cursor placed with a viewport-relative CUP. Trailing blank rows are therefore written on
+ * purpose — dropping them would shift every subsequent row and land the cursor in the wrong
+ * place.
+ */
+
+interface CaptureLinesOptions {
+    /** Line index into scrollback+viewport; negative counts from the end (-1 = last line). */
+    start?: number;
+    end?: number;
+}
+interface CaptureLinesResult {
+    lines: string[];
+    totalLines: number;
+}
+
+interface TerminalExitInfo {
+    exitCode: number;
+    signal: number | null;
+    lastOutputLines: string[];
+}
+interface CreateTerminalSessionOptions {
+    id?: string;
+    /** Absolute working directory (already resolved and validated by the manager). */
+    cwd: string;
+    /** Owning user id — a shell is the most privileged thing this server hands out. */
+    ownerUserId: string;
+    /**
+     * Stable per-user display number (tmux-style), assigned by the manager at creation. It
+     * travels with the terminal for its whole life — UI numbering must never depend on list
+     * position, which changes under user-reordered tabs.
+     */
+    seq?: number;
+    name?: string;
+    shell?: string;
+    cols?: number;
+    rows?: number;
+    env?: Record<string, string>;
+    /**
+     * Where a pushed bundle's node-pty assets live (the hmr capability's assetsDir);
+     * absent falls back to the packaged require (see pty-module.ts).
+     */
+    assets?: () => string | null;
+}
+interface TerminalSessionInfo {
+    id: string;
+    seq: number;
+    name: string;
+    cwd: string;
+    ownerUserId: string;
+    title: string | null;
+    cols: number;
+    rows: number;
+    pid: number;
+    createdAt: string;
+    alive: boolean;
+    exit: TerminalExitInfo | null;
+}
+type TerminalOutputListener = (data: string) => void;
+type TerminalExitListener = (info: TerminalExitInfo) => void;
+type TerminalTitleListener = (title: string | null) => void;
+declare class TerminalSession {
+    readonly id: string;
+    readonly seq: number;
+    readonly cwd: string;
+    readonly ownerUserId: string;
+    readonly createdAt: Date;
+    private name;
+    private readonly terminal;
+    private readonly ptyProcess;
+    private readonly inputMode;
+    private readonly outputListeners;
+    private readonly exitListeners;
+    private readonly titleListeners;
+    private title;
+    private pendingTitle;
+    private titleTimer;
+    private sizeState;
+    private exitInfo;
+    private disposed;
+    constructor(options: CreateTerminalSessionOptions);
+    /** DA1 / DSR / OSC colour queries — see OSC_COLOR_QUERY_RESPONSES. */
+    private registerCapabilityResponders;
+    get alive(): boolean;
+    get exit(): TerminalExitInfo | null;
+    info(): TerminalSessionInfo;
+    rename(name: string): void;
+    write(data: string): void;
+    /**
+     * Applies a size request under the claim/update ownership rule, resizing both the pty and
+     * the daemon's emulator so snapshots keep matching what the shell laid out.
+     */
+    resize(request: {
+        connectionId: string;
+        cols: number;
+        rows: number;
+        intent: "claim" | "update";
+    }): boolean;
+    releaseSize(connectionId: string): void;
+    get size(): {
+        cols: number;
+        rows: number;
+    };
+    /** The attach payload: the whole screen as an ANSI stream (see snapshot.ts). */
+    restoreStream(options?: {
+        scrollbackLines?: number;
+    }): string;
+    capture(options?: CaptureLinesOptions): CaptureLinesResult;
+    onOutput(listener: TerminalOutputListener): () => void;
+    onExit(listener: TerminalExitListener): () => void;
+    onTitleChange(listener: TerminalTitleListener): () => void;
+    kill(signal?: string): void;
+    dispose(): void;
+}
+
+interface CreateTerminalRequest {
+    cwd: string;
+    ownerUserId: string;
+    name?: string;
+    cols?: number;
+    rows?: number;
+    shell?: string;
+}
+/** A live pty: a host-like object (it owns a process), compared by name. */
+type Terminal = Opaque<"TerminalSession", TerminalSession>;
+/** Live ptys: the spawn primitive behind /api/terminals and the terminal WebSocket. */
+declare abstract class Terminals {
+    abstract create(request: CreateTerminalRequest): Promise<Terminal>;
+    abstract adopt(ids: readonly string[]): void;
+    abstract quiesce(): void;
+    abstract handleIds(): string[];
+    abstract require(id: string, userId: string): Terminal;
+    abstract get(id: string): Terminal | undefined;
+    abstract list(userId: string): Terminal[];
+    abstract listInfo(userId: string): TerminalSessionInfo[];
+    abstract kill(id: string, userId: string): void;
+    abstract disposeAll(): void;
+}
+
+/**
+ * The resolved, in-force limits for one request, in bytes. Read fresh per request from the
+ * settings repo rather than snapshotted at boot, so an admin's change applies to the very next
+ * upload without a restart.
+ */
+interface AttachmentLimits {
+    /** Per-file cap. */
+    maxBytes: number;
+    /** Per-request total of decoded attachment bytes. */
+    totalBytes: number;
+    /** Per-request file count. */
+    maxCount: number;
+}
+
+/**
+ * A queued message's file attachment as held for recall: the scratchpad path it was written
+ * to, plus what is needed to rebuild the composer-shaped part — the submitted name and media
+ * type (the bytes stay on disk; queued entries never hold file payloads in memory).
+ */
+interface RecallableFile {
+    fileName: string;
+    path: string;
+    mime: string;
+}
+
+/** SessionIndex: the mechanism SessionsRepo implements. */
+declare abstract class SessionIndex {
+    abstract insert(row: SessionRow): void;
+    abstract insertOrIgnore(row: SessionRow): void;
+    abstract insertFork(sourceSessionId: string, row: SessionRow): SessionRow;
+    abstract markOrgClient(sessionIds: readonly string[]): void;
+    abstract markHasTrace(sessionId: string): void;
+    abstract markDriven(sessionId: string, at: string): void;
+    abstract touchLastActive(sessionId: string, at: string): void;
+    abstract findById(sessionId: string): SessionRow | null;
+    abstract listByAgent(projectId: string, agentId: string): SessionRow[];
+    abstract listByProject(projectId: string): SessionRow[];
+    abstract latestByProjects(projectIds: readonly string[]): SessionRow | null;
+    abstract updateApprovalMode(sessionId: string, mode: ApprovalMode): void;
+    abstract updateSandbox(sessionId: string, sandbox: SandboxSettings): void;
+    abstract updateThinkingLevel(sessionId: string, level: ThinkingLevelName): void;
+    abstract updateTitle(sessionId: string, title: string): void;
+    abstract updateTitleIfNull(sessionId: string, title: string): void;
+    abstract updateModel(sessionId: string, provider: string, modelId: string): void;
+    abstract setArchived(sessionId: string, archivedAt: string | null): void;
+    abstract replaceId(oldSessionId: string, newSessionId: string): void;
+    abstract deleteByAgent(projectId: string, agentId: string): void;
+    abstract deleteByProject(projectId: string): void;
+    abstract deleteById(sessionId: string): void;
+}
+/** SessionOrigins: the mechanism SessionSources implements. */
+declare abstract class SessionOrigins {
+    /** `null`: the Session's Trace head records no source (written before it was required). */
+    abstract set(sessionId: string, source: SessionSource | null): void;
+    abstract get(sessionId: string): SessionSource | null | undefined;
+    abstract delete(sessionId: string): void;
+}
+
+/**
+ * sessions table repo:
+ * Session index, approval mode, and auto-generated title; Session-level routes use this to look up project ownership.
+ */
+
+interface SessionRow {
+    sessionId: string;
+    projectId: string;
+    agentId: string;
+    /**
+     * Provider group of the session's **current** model (pairs with `modelId` to form the model
+     * reference). Moves with each in-session switch (`updateModel`); the Trace's latest
+     * `session_meta` is the durable truth, and the runtime reconciles a row it disagrees with.
+     */
+    provider: string;
+    /** Upstream model_id of the session's current model (sent as-is to AgentHub; never concatenated). */
+    modelId: string;
+    workspace: string;
+    approvalMode: ApprovalMode;
+    /**
+     * Thinking level pinned for THIS session (PATCH /api/sessions/:id); NULL = not pinned,
+     * so runs that carry no level of their own follow the Agent config as before. Sessions
+     * are never inserted with one — pinning is an explicit act inside a live conversation.
+     */
+    thinkingLevel?: ThinkingLevelName$1 | null;
+    /** Auto-generated session title; NULL = not yet generated (frontend shows "New Conversation"). */
+    title: string | null;
+    /** Archive timestamp, ISO; NULL = not archived (omitting on insert defaults to NULL). */
+    archivedAt?: string | null;
+    /**
+     * Creating client: "web" (created via the Web App), "cli" (created through the API by
+     * the CLI, or adopted from a Trace a legacy CLI-direct run left behind), "org" (opened by
+     * the organization runtime — a desk or a ticket session — or spawned as a sub-session of
+     * one, which inherits the stamp at registration), "api" (created by an Agent API run — the
+     * only rows the API may continue); NULL = legacy row from before the column existed,
+     * treated as web. Free text in SQLite, so a new value needs no migration.
+     * Provenance that outlives its organization: development mode's list is the one reader
+     * that filters on it (through the list's `excludeOrg`), and it hides "org" rows whether or
+     * not the organization still exists. The schedule/subagent SOURCE is deliberately NOT a row field — core
+     * session_meta in the Trace stays the single source of truth for it
+     * (runtime/session-sources.ts); `client` is a separate, DB-only axis that meta never
+     * records.
+     */
+    client?: "web" | "cli" | "org" | "api" | null;
+    /** Cache: a Trace record exists (set at task start / adoption / subagent registration; backfilled by list hydration). */
+    hasTrace?: boolean;
+    /**
+     * Last activity this server drove for the session, ISO: stamped once when a run starts
+     * and once when it ends (see SessionManager.drive — a goal run is ONE drive over all its
+     * rounds, so it stamps twice, not per round). Set to createdAt at insert, and only ever
+     * moves forward (markDriven/touchLastActive clamp with MAX, so a backwards clock step
+     * cannot regress it). Rows this server never drives — CLI-adopted Sessions, subagent
+     * rows (their activity is driven through the parent's entry) — keep createdAt.
+     */
+    lastActiveAt: string;
+    createdAt: string;
+    /**
+     * The Session's own sandbox policy, snapshotted from the server's settings at creation.
+     * NULL = a row from before the column: it takes the settings at its next command.
+     */
+    sandbox?: SandboxSettings | null;
+}
+
+/**
+ * Tool call approval: ApproveFn factory + pending
+ * approval registry.
+ *
+ * Approval mode semantics match the CLI (packages/cli/src/approval.ts):
+ *   allow-all auto-approves; deny-all auto-denies; read-only allows read-only tools
+ *   (permission==="r") and routes the rest to manual approval; always-ask routes
+ *   everything to manual approval. Routing to manual approval registers a pending entry
+ *   and pushes an `approval_request` via SSE, suspending until the frontend decides via
+ *   `POST /approvals/:toolCallId`; no timeout — pending approvals are resolved to deny
+ *   when the Task is interrupted (then proceeds through the abort flow).
+ *
+ * An unattended Session takes that one route differently: there is no frontend to ask, so
+ * the call is denied on the spot instead of suspending forever (see `unattended` below).
+ *
+ * Every approval decision re-reads the current approval_mode (`getMode` reads the DB),
+ * so mode changes take effect immediately.
+ * Docs: /docs/tools § "Approval".
+ */
+
+interface PendingApproval {
+    toolCall: OmniMessage<ToolCallPayload>;
+    origin?: string[];
+}
+
+/** A numbered channel event; `id` is `<epoch>-<seq>`, `data` is serialized single-line JSON. */
+interface ChannelEvent {
+    id: string;
+    /** SSE event name; omitted (OmniMessage) means no `event:` line. */
+    event?: string;
+    data: string;
+}
+type ChannelListener = (evt: ChannelEvent) => void;
+interface ChannelOptions {
+    maxBufferCount?: number;
+    maxBufferBytes?: number;
+}
+declare class Channel {
+    /** Channel epoch: generated at instance creation, prefixed onto event ids (necessarily changes after recycle/recreate or restart). */
+    readonly epoch: string;
+    private nextSeq;
+    private buffer;
+    private bufferBytes;
+    /** Max seq among evicted events (0 means never evicted): lower bound for hit checks. */
+    private lastEvictedSeq;
+    private readonly listeners;
+    private readonly maxCount;
+    private readonly maxBytes;
+    /** Timestamp of last activity (publish/subscription change), used for idle-reclaim checks. */
+    lastActivityMs: number;
+    constructor(opts?: ChannelOptions);
+    get subscriberCount(): number;
+    /**
+     * Id of the most recently assigned event (`<epoch>-<seq>`; seq 0 when none was assigned
+     * yet). Unicast (sendTo) seqs count too — the value is a position marker, not a buffer
+     * lookup key. Used as the live-tail cursor on GET /messages: captured in the same
+     * synchronous tick as the fragment snapshot, it tells the client which buffered events
+     * the snapshot already covers.
+     */
+    get lastEventId(): string;
+    /** Broadcast an event: number it, buffer it (evicting the oldest), notify all subscribers. */
+    publish(data: unknown, event?: string): ChannelEvent;
+    /** Unicast an event to a single subscriber: consumes a seq but doesn't buffer or broadcast (used for replay at subscribe time). */
+    sendTo(listener: ChannelListener, data: unknown, event?: string): ChannelEvent;
+    subscribe(listener: ChannelListener): () => void;
+    /**
+     * Compute replay from a Last-Event-ID (`<epoch>-<seq>`): a mismatched epoch (channel
+     * recycled/recreated, process restarted, or malformed id) always misses; a matching
+     * epoch hits the buffer (if no events after that seq have been evicted and the seq was
+     * indeed assigned by this channel) and returns the buffered events after it; otherwise
+     * miss (the caller should send `resync_required` first).
+     */
+    replayAfter(lastEventId: string): {
+        hit: boolean;
+        events: ChannelEvent[];
+    };
+    private makeEvent;
+}
+interface ChannelHubOptions {
+    idleMs?: number;
+    /**
+     * Active check: keys for which this returns true are excluded from idle reclaim (app
+     * assembly injects `manager.statusOf(key) !== "idle"`, so a running/compacting
+     * Session channel is never reclaimed no matter how long since its last publish; a
+     * user channel key looks like `user:<id>` and is always considered active).
+     */
+    isActive?: (key: string) => boolean;
+}
+/**
+ * Channel collection: lazily created by key (Session id or `user:<user_id>`);
+ * a channel whose Session is idle and has had no subscribers for over 30 minutes is
+ * reclaimed, releasing its buffer as well.
+ */
+declare class ChannelHub {
+    private readonly channels;
+    private readonly timer;
+    private readonly idleMs;
+    private isActive;
+    constructor(opts?: ChannelHubOptions);
+    /**
+     * Replaces the activity probe. "Is this session busy" is a business question the hub
+     * (runtime mechanism) cannot answer itself; the App installs its answer at create over
+     * the claimed hub — ordinary capability use, not a registry entry. Overwrite-only, the
+     * cross-generation discipline: a successor installs its own probe and a dead
+     * generation's is simply left behind (its manager has drained, so it reports idle —
+     * never wrong, only replaced).
+     */
+    setActivityProbe(probe: (key: string) => boolean): void;
+    get(key: string): Channel;
+    peek(key: string): Channel | undefined;
+    /**
+     * Publishes to every live channel whose key starts with `prefix` — global
+     * notices (e.g. `user:` for "the web assets were hot-swapped, reload").
+     * Only reaches channels that exist (i.e. someone connected at least once);
+     * that is the right scope for a notice that only matters to live clients.
+     */
+    broadcast(prefix: string, data: unknown, event?: string): void;
+    /** Reclaim idle channels (skips active Sessions: no reclaim even without a publish while awaiting approval); `now` is injectable for tests. */
+    sweep(now?: number): void;
+    dispose(): void;
+}
+
+/** Attribution context for one record (top-level Session scope). */
+interface UsageContext {
+    projectId: string;
+    agentId: string;
+    /** Top-level Session id (the current actual id after self-heal). */
+    sessionId: string;
+    /** Vendor grouping for the top-level Session's model (paired with modelId; the fallback attribution when the origin mapping has no hit). */
+    provider: string;
+    /** Upstream model_id of the top-level Session (paired with provider). */
+    modelId: string;
+}
+
+/**
+ * Usage statistics query.
+ *
+ * Cost is **fixed when a Request completes**: every usage_records row carries the cost the
+ * recorder computed from the rates in force at that moment, and nothing here re-prices it — a
+ * price edited, synced or discounted later only changes what later Requests cost. The repo
+ * returns sums broken down by `(provider, model_id)` paired reference, and this service folds
+ * them into cost / hasUncosted (a row whose model had no price is excluded from cost and flags
+ * hasUncosted).
+ * Summary cards (today / last 7 days / cumulative), grouped aggregation (date /
+ * agent / model / session, with the session dimension supporting agentId drill-down
+ * filtering), and the zero-filled time series the cost center's charts draw.
+ * Server-side error statistics (error_records) ride along on the same response:
+ * the statistics center fetches everything in one request, and filters are
+ * naturally shared; unattributed errors (login failures, process crashes, and other
+ * errors with no Project context) are visible only to admins, see the ErrorsRepo
+ * file header.
+ */
+
+/** The three pricing buckets (usd_per_mtok convention), returned by the pricing lookup callback. */
+interface PricingRates {
+    cacheRead: number;
+    cacheWrite: number;
+    output: number;
+}
+
+/** Errors: the mechanism ErrorRecorder implements. */
+declare abstract class Errors {
+    abstract record(args: ErrorRecordArgs): void;
+}
+
+/** Capture-site source (maps one-to-one to error_records.source). */
+type ErrorSource = "http" | "organization" | "session" | "llm" | "environment" | "compaction" | "usage" | "title" | "subagent" | "process" | "schedule" | "messaging" | "id_suggest";
+/** Error classification: see file header — the criterion is "does a human need to step in". */
+type ErrorKind = "expected" | "unexpected";
+/** Attribution context (all optional: the login endpoint has no Project, and process-level fallback has no request at all). */
+interface ErrorContext {
+    projectId?: string;
+    agentId?: string;
+    sessionId?: string;
+}
+interface ErrorRecordArgs {
+    source: ErrorSource;
+    /** The caught error (unknown: the value caught may not be an Error; failures from the message stream pass the reason text directly). */
+    err: unknown;
+    ctx?: ErrorContext;
+    /** Semantic code (required for non-HTTP sources, e.g. session_run_failed); defaults to HttpError.code. */
+    code?: string;
+    /** HTTP status code; leave empty for non-HTTP sources. */
+    status?: number;
+    /** Explicit classification (see file header); defaults to inferring from `HttpError` — HTTP sources rely on this, other sources should pass it explicitly. */
+    kind?: ErrorKind;
+}
+declare class ErrorRecorder implements Errors {
+    /** Dedup table: `source \0 code \0 projectId` → timestamp of the last **persist** (see file header). */
+    private readonly lastSeen;
+    private readonly errors;
+    private readonly clock;
+    /** Record an error (synchronous, fails silently; same-window duplicates are dropped outright, see file header). */
+    record(args: ErrorRecordArgs): void;
+    /** true if a same-kind error was already recorded within the window (drop it); otherwise register this persist timestamp and keep the dedup table bounded. */
+    private deduped;
+    /** Keep the dedup table bounded (see file header): clear expired entries first; if still over the limit (hundreds/thousands of distinct error codes erupting at once), clear it entirely. */
+    private evict;
+}
+/** Minimal dependency a capture site needs on the recorder (tests inject a fake; structurally matches SessionManager's UsageRecorderLike). */
+type ErrorSink = Pick<ErrorRecorder, "record">;
+
+/** Host-side parameters for one title-generation request. */
+interface TitleRequest {
+    /** The user input this run started from: its first words become the immediate fallback title. */
+    fallbackText: string;
+    /** Material override (the main session passes its input text, a subagent the prompt that spawned it — assistant material stays empty either way, so the request never waits on model output); defaults to the material self-collected by the core Session. */
+    material?: {
+        userText: string;
+        assistantText: string;
+    };
+    /** The channel to push the `session_title` event to; defaults to `ctx.sessionId`. A
+     *  subagent has no SSE channel of its own, so its title must reach the frontend via
+     *  the **parent Session's** channel (the list updates in place by sessionId). */
+    notifyOn?: string;
+}
+/** session-manager's minimal dependency on the title generator (tests inject a fake implementation). */
+interface TitleNotifier {
+    maybeGenerate(ctx: UsageContext, session: Pick<RuntimeSession, "generateTitle">, req: TitleRequest): void;
+}
+
+/**
+ * In-process registry of Session sources, derived from core `session_meta` — the single
+ * source of truth for what kind of conversation a Session is (the DB stores no `source`
+ * column).
+ *
+ * Populated wherever the server actually has the meta in hand: Session creation
+ * (SessionService reads the just-created core Session's meta), subagent registration
+ * (SessionManager reads the forwarded child meta), forks (always `user`), and Trace adoption /
+ * lazy list resolution (the trace index's head read). A value read back from a Trace is
+ * narrowed through core's `normalizeSessionSource` (the retired `benchmark` reads as `cli`),
+ * except that a head recording no source is kept as `null`: what it reads as depends on the
+ * Session's index row (`readRecordedSource`), which a head read does not have. An absent entry
+ * means "unknown": the list path resolves it from the Trace once per process lifetime.
+ */
+
+/**
+ * What a Session's Trace head records as its source: one of the sources, or `null` for a head
+ * written before the source was required, which records none.
+ */
+type RecordedSource = SessionSource | null;
+
+/** One indexed Trace shard. */
+interface TraceFileRow {
+    projectId: string;
+    agentId: string;
+    sessionId: string;
+    fileIndex: number;
+    date: string;
+    sizeBytes: number;
+}
+/** One Session's registration-time facts (earliest shard's head). */
+interface TraceSessionRow {
+    sessionId: string;
+    projectId: string;
+    agentId: string;
+    /**
+     * The head's session_meta source, narrowed; `null` when the head records none (written before
+     * the source was required; read it with the row's client, `readRecordedSource`). Meaningful
+     * only once `metaRead`.
+     */
+    source: RecordedSource;
+    workspace: string;
+    title: string | null;
+    provider: string | null;
+    modelId: string | null;
+    firstTs: string | null;
+    metaRead: boolean;
+}
+
+/** TraceIndexStore: the mechanism TraceIndexRepo implements. */
+declare abstract class TraceIndexStore {
+    abstract upsertFile(row: TraceFileRow): void;
+    abstract updateFileSize(projectId: string, agentId: string, sessionId: string, fileIndex: number, sizeBytes: number): void;
+    abstract getPageStats(projectId: string, agentId: string, sessionId: string, fileIndex: number): string | null;
+    abstract setPageStats(projectId: string, agentId: string, sessionId: string, fileIndex: number, sizeBytes: number, pageStats: string): void;
+    abstract deleteFile(projectId: string, agentId: string, sessionId: string, fileIndex: number): void;
+    abstract listFilesByAgent(projectId: string, agentId: string): TraceFileRow[];
+    abstract listFilesBySession(projectId: string, agentId: string, sessionId: string): TraceFileRow[];
+    abstract findAgentBySession(projectId: string, sessionId: string): string | null;
+    abstract upsertSession(row: TraceSessionRow): void;
+    abstract getSession(sessionId: string): TraceSessionRow | null;
+    abstract listSessionsByAgent(projectId: string, agentId: string): TraceSessionRow[];
+    abstract deleteBySession(sessionId: string): void;
+    abstract deleteByAgent(projectId: string, agentId: string): void;
+    abstract deleteByProject(projectId: string): void;
+}
+/** TraceIndex: the mechanism TraceIndexService implements. */
+declare abstract class TraceIndex {
+    abstract readonly counters: {
+        gateStats: number;
+        dirScans: number;
+        headReads: number;
+    };
+    abstract reconcileAgent(projectId: string, agentId: string, opts?: {
+        force?: boolean;
+    }): Promise<void>;
+    abstract reconcileProject(projectId: string, opts?: {
+        force?: boolean;
+    }): Promise<void>;
+    abstract registerImportedFile(args: {
+        projectId: string;
+        agentId: string;
+        sessionId: string;
+        fileIndex: number;
+        date: string;
+        sizeBytes: number;
+        records: OmniMessage[];
+    }): void;
+    abstract removeSession(projectId: string, agentId: string, sessionId: string): void;
+    abstract removeAgent(projectId: string, agentId: string): void;
+    abstract removeProject(projectId: string): void;
+}
+
+interface PlatformCatalogPricing {
+    unit: "usd_per_mtok";
+    cacheRead: number;
+    cacheWrite: number;
+    output: number;
+}
+/** A platform model normalized into the fields Penguin persists for a newly discovered row. */
+interface PlatformCatalogModel {
+    modelId: string;
+    displayName: string;
+    contextWindow: number;
+    supportsVision: boolean;
+    /**
+     * List price, which is what a Project stores: the platform's `listPricing` when it runs a
+     * promotion on the model, its billed `pricing` otherwise.
+     */
+    pricing: PlatformCatalogPricing;
+    /** Fraction off `pricing` the platform is running (0.5 = half price); absent when none. */
+    discount?: number;
+    baseUrl: string;
+    clientType: "gemini-3.8" | "deepseek-v4";
+}
+/** Validated snapshot returned by Penguin Go's client-model catalog. */
+interface PlatformModelCatalog {
+    models: PlatformCatalogModel[];
+}
+/** Catalog merge result. `updated` counts existing rows whose list price, client type or promotion changed. */
+interface PlatformModelApplyResult {
+    added: number;
+    updated: number;
+    applied: number;
+}
+
+type RawTable = Record<string, unknown>;
+/**
+ * What one utility completion produced: the model's text, or why there is none. A bare null
+ * would say "no answer" and nothing else — and every one of these failures (no model
+ * configured, a missing credential, a provider rejection, a timeout, an answer that was all
+ * thinking) is one the user can act on, so the reason travels to the caller, which records it.
+ */
+type UtilityCompletion = {
+    ok: true;
+    text: string;
+} | {
+    ok: false;
+    /** `no_model`: the Project names no default model, or names one it has no entry for — nothing was asked. `failed`: the model was asked and produced no text. */
+    cause: "no_model" | "failed";
+    error: string;
+};
+
+/** ProjectConfigStore: the mechanism ProjectConfigService implements. */
+declare abstract class ProjectConfigStore {
+    abstract readRaw(projectId: string): Promise<RawTable>;
+    abstract loadConfig(projectId: string): Promise<ProjectConfig>;
+    abstract writeRaw(projectId: string, data: RawTable): Promise<void>;
+    abstract writeInitialConfig(projectId: string, name: string): Promise<void>;
+    abstract ensurePresetModels(projectId: string): Promise<boolean>;
+    /** Fills in a display name for an adopted Project that has none (see the implementation's own doc). */
+    abstract ensureDisplayName(projectId: string, name: string): Promise<void>;
+    abstract seedPresetPromotions(projectId: string): Promise<void>;
+    abstract getName(projectId: string): Promise<string | undefined>;
+    abstract setName(projectId: string, name: string): Promise<void>;
+    abstract getDefaultModelRef(projectId: string): Promise<ModelRef | undefined>;
+    abstract setDefaultModelRef(projectId: string, ref: ModelRefDto): Promise<ModelRefDto>;
+    abstract getChatDefaults(projectId: string): Promise<ChatDefaultsDto>;
+    abstract setChatDefaults(projectId: string, req: ChatDefaultsDto): Promise<ChatDefaultsDto>;
+    /** The `[plugins]` key: the shared table and each machine's own, package name → requirement, in the file's order. */
+    abstract getPluginTables(projectId: string): Promise<PluginTables>;
+    /** Replaces the tables (a declarative PUT); answers what was written. */
+    abstract setPluginTables(projectId: string, tables: PluginTables): Promise<PluginTables>;
+    abstract getCommandPolicy(projectId: string): Promise<CommandPolicyDto>;
+    abstract setCommandPolicy(projectId: string, req: {
+        enabled?: boolean;
+        rules: {
+            name: string;
+            pattern: string;
+            description?: string;
+            enabled?: boolean;
+        }[];
+    }): Promise<CommandPolicyDto>;
+    abstract getPricing(projectId: string, provider: string, modelId: string, at: Date): Promise<PricingRates | undefined>;
+    abstract detectVision(projectId: string, req: ModelVisionDetectRequest): Promise<ModelVisionDetectResponse>;
+    abstract testModel(projectId: string, req: ModelTestRequest): Promise<ModelTestResponse>;
+    abstract detectProtocol(projectId: string, req: ModelProtocolDetectRequest): Promise<ModelProtocolDetectResponse>;
+    abstract listEndpointModels(req: EndpointModelListRequest, listImpl?: (options: ListEndpointModelsOptions) => Promise<string[]>, timeoutMs?: number): Promise<EndpointModelListResponse>;
+    abstract getModels(projectId: string): Promise<ModelsResponse>;
+    abstract updateModels(projectId: string, req: ModelsUpdateRequest): Promise<ModelsResponse>;
+    abstract setGroupApiKey(projectId: string, provider: string, apiKey: string): Promise<number>;
+    abstract setGroupApiKeyWithProviderAuthToken(projectId: string, provider: string, apiKey: string, token: Omit<ModelProviderAuthToken, "provider" | "updatedAt">, options?: {
+        expectedRefreshToken?: string;
+    }): Promise<number>;
+    abstract getGroupApiKey(projectId: string, provider: string): Promise<string | undefined>;
+    /**
+     * The key a group's account balance is read with: the stored group key, or else the
+     * environment key a Session on one of the group's rows would use, when that variable's
+     * official endpoint is the balance endpoint's own host. Server-side only.
+     */
+    abstract getGroupBalanceKey(projectId: string, provider: string): Promise<string | undefined>;
+    abstract setModelApiKeyResolver(resolver: (context: ModelRequestContext) => Promise<string | undefined>): void;
+    abstract mergePlatformModels(projectId: string, provider: string, catalog: PlatformModelCatalog, apiKey: string, applyKeyToExisting: boolean): Promise<PlatformModelApplyResult>;
+    abstract completeOnce(projectId: string, prompt: string): Promise<UtilityCompletion>;
+}
+interface ModelProviderAuthToken {
+    provider: string;
+    refreshToken: string;
+    accessTokenExpiresAt?: string;
+    updatedAt: string;
+}
+
+/**
+ * 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.
+ */
+type SessionListOrder = "created" | "activity";
+/** A row's place in the activity order; as a `before` cursor, the last row the client holds. */
+interface ActivityCursor {
+    lastActiveAt: string;
+    sessionId: string;
+}
+/**
+ * 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.
+ */
+type SessionListPaging = {
+    offset: number;
+    limit: number;
+} | {
+    before: ActivityCursor;
+    limit: number;
+};
+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;
+}
+declare class SessionService {
+    private readonly deps;
+    constructor(deps: SessionServiceDeps);
+    /** The policy a new Session starts with: the server's Sandbox settings. */
+    defaultSandbox(): SandboxSettings;
+    /** Whether this server can enforce the `local` network level right now. */
+    localNetworkSupported(): boolean;
+    private sandboxDimensions;
+    /** A policy as the composer sees it, with which of its levels this server can enforce. */
+    sandboxView(policy: SandboxSettings): SessionSandbox;
+    /**
+     * 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;
+    /**
+     * 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;
+    /** A Session's policy: its snapshot, or — for a row from before snapshots — the settings. */
+    sandboxOf(row: SessionRow): SandboxSettings;
+    /**
+     * 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;
+    /** Stores one Session's policy (`pickSandbox`'s): its next command runs under it. */
+    updateSandbox(sessionId: string, policy: SandboxSettings): void;
+    /**
+     * 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.
+     */
+    toInfo(row: SessionRow, hasTrace: boolean, orgIds?: ReadonlyMap<string, string>): Promise<SessionInfo>;
+    /**
+     * 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 sourceOf;
+    /** Whether this Session already has a Trace record (a Task has been run): answered by the index (reconciled first). */
+    hasTrace(row: SessionRow): Promise<boolean>;
+    /**
+     * 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 categoryOf;
+    /**
+     * 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.
+     */
+    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>;
+    }>;
+    /**
+     * 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.
+     */
+    sessionStats(projectId: string, agentId: string, days: number): Promise<{
+        sessionCount: number;
+        activity: number[];
+    }>;
+    /**
+     * 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).
+     */
+    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>;
+    /** A new Session's snapshot: the settings, with the creator's picks (checked) on top. */
+    private snapshotSandbox;
+    /**
+     * 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.
+     */
+    latestTracePath(row: SessionRow): Promise<string | undefined>;
+    /**
+     * 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 discoverTraces;
+    /**
+     * 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.
+     */
+    adoptUnmanagedTraceSessions(): Promise<number>;
+    /**
+     * 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;
+}
+
+type ModelScopeAuthStatusResult = ModelScopeAuthFlowStatusResponse & {
+    changed?: true;
+};
+interface ModelScopeCredential {
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt?: string;
+}
+interface ModelScopeRefreshResult {
+    changed: boolean;
+}
+interface ModelScopeAuthDeps {
+    /** Base URL of the bridge, without a trailing slash (config.modelscopeBridgeUrl). */
+    bridgeUrl: string;
+    /** Writes the delivered credential; resolves to how many rows took the access token. */
+    applyCredential: (projectId: string, credential: ModelScopeCredential, options?: {
+        expectedRefreshToken?: string;
+    }) => Promise<number>;
+    /** Reads the server-side refresh metadata for the group. */
+    readStoredCredential?: (projectId: string) => ModelProviderAuthToken | undefined;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+}
+declare class ModelScopeAuthService {
+    private readonly deps;
+    private readonly flows;
+    private readonly refreshes;
+    private readonly refreshFailures;
+    private readonly fetchImpl;
+    private readonly now;
+    constructor(deps: ModelScopeAuthDeps);
+    private url;
+    private isPending;
+    private request;
+    ensureFresh(input: {
+        projectId: string;
+        provider: string;
+    }): Promise<ModelScopeRefreshResult>;
+    start(input: {
+        projectId: string;
+        userId: string;
+    }): Promise<{
+        flowId: string;
+        authorizeUrl: string;
+        expiresAt: string;
+    }>;
+    status(input: {
+        flowId: string;
+        projectId: string;
+        userId: string;
+    }): Promise<ModelScopeAuthStatusResult>;
+    retryApply(input: {
+        flowId: string;
+        projectId: string;
+        userId: string;
+    }): Promise<ModelScopeAuthStatusResult>;
+    cancel(input: {
+        flowId: string;
+        projectId: string;
+        userId: string;
+    }): void;
+    private refreshState;
+    private refreshNow;
+    private reauthorizationRequired;
+    private pollBridge;
+    private apply;
+    private publicFlow;
+    private requireFlow;
+    private sweep;
+    private evictOldest;
+}
+declare const ModelScopeAuth_base: (abstract new () => Pick<ModelScopeAuthService, "start" | "status" | "retryApply" | "cancel" | "ensureFresh">) & (<C>(target: C, context: ClassDecoratorContext) => C);
+/** The per-App ModelScope key authorization capability consumed by Project model routes. */
+declare abstract class ModelScopeAuth extends ModelScopeAuth_base {
+}
+
+/** Minimal interface for a runtime Session (satisfied by core Session; tests may inject a fake implementation). */
+interface RuntimeSession {
+    readonly sessionId: string;
+    run(newMessages: OmniMessage[], opts: {
+        approve: ApproveFn;
+        signal: AbortSignal;
+    }): AsyncGenerator<OmniMessage>;
+    compact(opts: {
+        signal: AbortSignal;
+    }): AsyncGenerator<OmniMessage>;
+    /**
+     * The running context's model (core `Session.provider` / `Session.modelId`, getters over
+     * the context's session_meta): the row's pair at creation, moved by each in-session switch
+     * — and, after a restart, whatever the Trace resumed on. Optional: test fakes may omit them,
+     * in which case the entry keeps the row's pair.
+     */
+    readonly provider?: string;
+    readonly modelId?: string;
+    /**
+     * Switches the Session's model in place (core `Session.switchModel`): closes the running
+     * context on the model it ran on, then opens the next one on the target. A completed switch
+     * streams the new context's main-session `session_meta` last, and the getters above answer
+     * the target by then; a refusal is thrown before the first event; a Session that never ran
+     * switches without streaming anything. Optional: test fakes may omit it, reading as
+     * "switching is not available".
+     */
+    switchModel?(opts: {
+        provider: string;
+        modelId: string;
+        signal: AbortSignal;
+    }): AsyncGenerator<OmniMessage, StopReason>;
+    /**
+     * The Session's thinking level (core `Session.thinkingLevel`, plain state): soft-limited —
+     * an assignment applies from the Session's very next LLM request. Optional: test fakes may
+     * omit it.
+     */
+    thinkingLevel?: ThinkingLevelName;
+    /** Whether compaction is possible and why; when not ok, compact() yields no messages (see core ContextEngine.compactability). */
+    compactability(): CompactAvailability;
+    /** Queues a mid-run steering input (core `Session.steer`); false when no Task is running. */
+    steer(input: OmniMessage[]): boolean;
+    /**
+     * Withdraws a steering input queued via `steer` before core delivers it (core
+     * `Session.unsteer`, matched by input-list identity); false when it is no longer queued —
+     * already delivered, or the run exited. Optional: test fakes may omit it, in which case
+     * every recall reports "already delivered".
+     */
+    unsteer?(input: OmniMessage[]): boolean;
+    /** Skips the in-progress reconnect backoff, firing the next retry immediately (core `Session.skipReconnectWait`); false when no wait is in progress. */
+    skipReconnectWait(): boolean;
+    /**
+     * Runs the named package's `user_prompt` hook (core `Session.runUserPromptHook` — hooks
+     * run in core and nowhere else); null = the package is not installed or names no such
+     * command. Optional: test fakes may omit it, reading as not installed.
+     */
+    runUserPromptHook?(name: string, prompt: string, extras?: Record<string, string | number | boolean>): Promise<{
+        context?: string;
+    } | null>;
+    /** A tool's permission level from the running context's toolset (core `Session.toolPermission`; strict-tier — rebuilt at rotation). */
+    toolPermission(name: string): "r" | "rw" | undefined;
+    /**
+     * Out-of-band one-shot request for title generation (core `Session.generateTitle`,
+     * writes no history/Trace). Material defaults to what the Session collects itself
+     * (the first Task's text gathered during run); `material` overrides this for
+     * subagents.
+     */
+    generateTitle(args?: {
+        material?: {
+            userText: string;
+            assistantText: string;
+        };
+        signal?: AbortSignal;
+    }): Promise<SessionTitleResult>;
+    /**
+     * Subscribes the idle-arrival signal for background-task completion notices (core
+     * `Session.onBackgroundNotice`): fired when a `run_in_background` launch settles while no
+     * Task is running — the manager then takes the queue and submits it as an ordinary task.
+     * Optional: test fakes may omit it.
+     */
+    onBackgroundNotice?(listener: () => void): void;
+    /** Takes the queued background completion notices as task input (core `Session.takeBackgroundNotices`). Optional, like onBackgroundNotice. */
+    takeBackgroundNotices?(): OmniMessage[];
+    /** Whether completion notices are still queued (core `Session.hasPendingBackgroundNotices`); pins the entry against idle eviction. Optional, like onBackgroundNotice. */
+    hasPendingBackgroundNotices?(): boolean;
+    /** Refreshes the listen-port probes behind the process list's `serviceUrl` (core `Session.probeBackgroundCommandServices`). Optional: test fakes may omit it. */
+    probeBackgroundCommandServices?(): Promise<void>;
+    /** Subscribes live-forwarded background-subagent messages (core `Session.onBackgroundMessage`); the manager publishes them to the session channel. Optional: test fakes may omit it. */
+    onBackgroundMessage?(listener: (msg: OmniMessage) => void): void;
+    /** Background command processes owned by the Session's environment (core `Session.listBackgroundCommands`). Optional: test fakes may omit it. */
+    listBackgroundCommands?(): BackgroundCommandInfo[];
+    /** Kills one background command process (core `Session.killBackgroundCommand`); false when the id is unknown. Optional, like listBackgroundCommands. */
+    killBackgroundCommand?(processId: string): boolean;
+    /** Hands one EXECUTING tool call back as a background task (core `Session.detachToolCall`). Optional: test fakes may omit it, reading as "not_running". */
+    detachToolCall?(toolCallId: string): ToolDetachResult;
+    /** Whether a background subagent is mid-round (core `Session.hasRunningBackgroundSubagents`); pins the entry against idle eviction. Optional, like listBackgroundCommands. */
+    hasRunningBackgroundSubagents?(): boolean;
+    /** All live subagent child sessions of the Session's environment (core `Session.listBackgroundSubagents`). Optional, like listBackgroundCommands. */
+    listBackgroundSubagents?(): BackgroundSubagentInfo[];
+    /** Host message to one child session — steering mid-run, a follow-up run when idle, a revival when released (core `Session.sendToBackgroundSubagent`). Optional. */
+    sendToBackgroundSubagent?(childSessionId: string, messages: OmniMessage[], opts?: SubagentMessageOptions): Promise<SubagentMessageOutcome>;
+    /** Subscribes the host's session-lifetime fallback approval sink for child sessions (core `Session.setSubagentApprovalFallback`). Optional. */
+    setSubagentApprovalFallback?(approve: ApproveFn): void;
+    /** Aborts one child session's current run, keeping the session (core `Session.abortBackgroundSubagentRun`); false when unknown or idle. Optional. */
+    abortBackgroundSubagentRun?(childSessionId: string): boolean;
+    /** Pins one live child session's thinking level (core `Session.setBackgroundSubagentThinkingLevel`); false when the child is not live. Optional. */
+    setBackgroundSubagentThinkingLevel?(childSessionId: string, level: ThinkingLevelName): boolean;
+    /** Subscribes subagent run-state changes (core `Session.onSubagentState`): the manager republishes `task_state` with the fresh live listing. Optional. */
+    onSubagentState?(listener: () => void): void;
+    /** Subscribes background-task state changes (core `Session.onBackgroundState`): the manager re-counts the live registries and publishes `session_background` when the counts moved. Optional. */
+    onBackgroundState?(listener: () => void): void;
+    /** Releases environment resources — kills the remaining background processes (core `Session.dispose`). Optional, idempotent. */
+    dispose?(): void;
+}
+/** The underlying loader behind get-or-resume-or-heal. */
+interface SessionLoader {
+    /**
+     * Load a runtime Session from an index row: recover (with a Trace) or self-heal
+     * rebuild (no Trace, session_id will change). Throws HttpError(409) for unrecoverable
+     * cases such as a missing Workspace.
+     */
+    load(row: SessionRow): Promise<RuntimeSession>;
+}
+interface UsageRecorderLike {
+    record(ctx: UsageContext, msg: OmniMessage): Promise<void>;
+}
+interface SessionManagerDeps {
+    sessions: SessionIndex;
+    channels: ChannelHub;
+    loader: SessionLoader;
+    /** Session-origin registry (session_meta is the single source of truth; subagent registration records the forwarded meta's source here). */
+    sources: SessionOrigins;
+    recorder: UsageRecorderLike;
+    /** Automatic Session title generation (optional: not injected in tests or when disabled). */
+    titles?: TitleNotifier;
+    /** Error persistence (optional: without it, only logs — same as before this was wired up). */
+    errors?: ErrorSink;
+    /** Provider auth refresh (optional for tests that do not exercise external model credentials). */
+    modelScopeAuth?: ModelScopeAuth;
+    log?: (line: string) => void;
+    /** Goal run-state persistence (optional like `titles`: without it, goals run but leave no restorable record). */
+    /**
+     * Publishes a Session-scoped event on the user-level channel of everyone who can see the
+     * Project. The audience lookup (owner + members) and the `user:<id>` channel binding stay in
+     * the app layer, the same split the scheduler's `notify` uses — this class holds no Project
+     * membership repos. Optional: without it only the per-Session channel is served, which is
+     * what unit tests that don't wire it get.
+     */
+    notifyProjectUsers?: (projectId: string, event: ServerEvent) => void;
+    /**
+     * Clock for persisted timestamps (last_active_at). Injected like the other services' so a
+     * stubbed clock moves this and `usage_records.ts` together — the pairing the legacy
+     * backfill assumes when it reads MAX(ts) as a session's last activity.
+     */
+    now?: () => Date;
+    /**
+     * Called when a Task starts (or is queued) from a PERSON's input — a message typed in the
+     * Web App, the CLI or a bound messaging bot, as opposed to one the harness injected
+     * (`sender: "server"` / `"harness"`). Company mode uses it to reset the desk's @-chain
+     * accounting: a person's message opens a fresh chain (hop 0), whatever mention last woke
+     * the desk. Optional; unit tests that do not wire it get nothing.
+     */
+    onHumanInput?: (sessionId: string) => void;
+}
+/**
+ * A queued message's original content, held while it waits in a queue so a recall (DELETE
+ * /steer/:id, DELETE /follow-ups/:id) can hand it back to the composer for editing (#287).
+ * `text` and `images` are the same strings the queued input already references (no extra
+ * copy); files stay on disk in the Session scratchpad and are read back only at recall.
+ */
+interface RecallStore {
+    text: string;
+    images: string[];
+    files: RecallableFile[];
+}
+declare class SessionManager {
+    private readonly deps;
+    private readonly entries;
+    /**
+     * Each registered subagent Session's ROOT Session: a subagent runs under its root's
+     * sandbox policy, as it runs under its root's approval mode, so a change the person makes
+     * in the composer reaches the children already running.
+     */
+    private readonly childRoots;
+    /** The Session whose policy governs `sessionId`: its root for a subagent, else itself. */
+    rootSessionOf(sessionId: string): string;
+    /** Per-Session mutex (serializes get-or-load and status flips); auto-cleaned once the chain drains. */
+    private readonly locks;
+    private readonly log;
+    /** Graceful-shutdown flag: once set, new Tasks/compactions are rejected (503). */
+    private closed;
+    /** Agents currently being deleted (key = agentKey): new Tasks/compactions are always rejected with 409 during this window. */
+    private readonly deletingAgents;
+    /** Sessions currently being deleted (guards against the entry/Trace file being rebuilt and reviving it inside the deletion race window). */
+    private readonly deletingSessions;
+    /** Per-Agent config generation (key = agentKey), bumped by invalidateAgentRuntimes when a Project's credentials change. */
+    private readonly agentGenerations;
+    /** Open streaming fragments of running sessions (fed by drive, served to GET /messages; see live-tail.ts). */
+    private readonly liveTail;
+    private readonly sweepTimer;
+    /** Clock for persisted timestamps (see SessionManagerDeps.now); wall clock unless injected. */
+    private readonly now;
+    constructor(deps: SessionManagerDeps);
+    statusOf(sessionId: string): SessionStatus;
+    pendingApprovalCount(sessionId: string): number;
+    pendingApprovals(sessionId: string): PendingApproval[];
+    /** Number of queued follow-up tasks (`queueIfBusy`) awaiting auto-start. */
+    pendingFollowUpCount(sessionId: string): number;
+    /**
+     * Background-task counts of a LOADED session, read live (see SessionInfo.backgroundTasks);
+     * undefined when the session is not in the active table or nothing is running — the list
+     * row and the single GET omit the field in both cases.
+     */
+    backgroundTasksOf(sessionId: string): SessionBackgroundTasks | undefined;
+    /** Steering messages queued but not yet delivered to the model (display mirror; see RuntimeEntry.pendingSteering). */
+    pendingSteeringOf(sessionId: string): PendingSteeringInfo[];
+    /** Steering a finished run never delivered, waiting for the composer to take it back (see RuntimeEntry.returnedSteering). */
+    returnedSteeringOf(sessionId: string): PendingSteeringInfo[];
+    /**
+     * Live subagent children of an ACTIVE runtime entry (empty when the session is not loaded
+     * — after a restart there is no in-process child left to report, so empty is the truth).
+     * Rides `task_state` events and the SSE subscribe snapshot; the panel renders child
+     * running marks from this instead of parsing tool-output text.
+     */
+    subagentsOf(sessionId: string): BackgroundSubagentInfo[];
+    /**
+     * Host message to one child session — a user input on the child, whatever its state:
+     * steering while it runs, a follow-up run while it is idle, a revival (resume-session
+     * semantics) when it is no longer live (core `Session.sendToBackgroundSubagent`). The
+     * parent runtime itself is loaded on demand (ensureEntry — the same get-or-resume path a
+     * task uses), so messaging a child of a long-idle conversation works after a restart too;
+     * the resume fallback names the child's owning Agent from its own session row, which must
+     * belong to the parent's project.
+     */
+    sendToSubagent(sessionId: string, childSessionId: string, messages: OmniMessage[]): Promise<SubagentMessageOutcome>;
+    /**
+     * Sets a Session's thinking level on its loaded runtime (core `Session.thinkingLevel`,
+     * plain state): the row's value is what the loader applies at load, so this only needs to
+     * reach a runtime that is already in the active table — or a live child session, which
+     * has an index row and a panel picker of its own but runs inside its parent's runtime.
+     * The level is soft-limited: it applies from the Session's very next LLM request
+     * (mid-context — the UI advises compacting first, since the change invalidates the
+     * provider's cached context). No-op when nothing is loaded.
+     */
+    setThinkingLevel(sessionId: string, level: ThinkingLevelName): void;
+    /** Host abort of one child session's current run (core `Session.abortBackgroundSubagentRun`); false when the parent runtime is not loaded, the child is unknown, or it is idle. */
+    abortSubagentRun(sessionId: string, childSessionId: string): boolean;
+    /** Queued follow-up tasks awaiting auto-start, as their display/recall info (id + content summary). */
+    pendingFollowUpsOf(sessionId: string): PendingFollowUpInfo[];
+    /**
+     * Live tail of a running session: one synthetic `partial_* start` OmniMessage per open
+     * streaming fragment, carrying the full accumulated content so far (see live-tail.ts).
+     * Empty when idle or when nothing is streaming. GET /messages attaches this (with a
+     * channel cursor) so a client joining mid-stream can render the in-progress message.
+     */
+    liveFragments(sessionId: string): OmniMessage[];
+    /**
+     * The running Task's input messages as published at launch; empty when idle. The engine
+     * writes these exact envelopes to the Trace only after the first run's bootstrap (MCP
+     * connect + discovery), so GET /messages appends whichever of them the Trace read has
+     * not caught up to yet — without this, a client rebuilding history during the connect
+     * (the draft flow subscribes only after the input publish) loses the user's own message.
+     */
+    pendingInputs(sessionId: string): OmniMessage[];
+    /** The running Task's streamed bootstrap records (see RuntimeEntry.pendingBootstrap); empty when idle. */
+    pendingBootstrap(sessionId: string): OmniMessage[];
+    /** Number of Sessions for this Agent that are currently running / compacting. */
+    activeCountForAgent(projectId: string, agentId: string): number;
+    /** Add a newly created Session to the active table (status idle), avoiding a redundant load on the next Task. */
+    adopt(row: SessionRow, session: RuntimeSession): void;
+    /**
+     * Subscribes the background hooks on a runtime Session entering the active table — every
+     * insertion path must call it (ensureEntry's loads, adopt's fresh creations):
+     * - the idle-arrival signal for completion notices (mid-run arrivals are delivered inside
+     *   the run by core; this signal is the only trigger left when the session sits idle);
+     * - live-forwarded background-subagent messages, published to the session channel (the
+     *   same feed SSE relays) and recorded for usage — a background child streams to the
+     *   frontend in real time past the launching turn's end, until its terminal state;
+     * - subagent run-state changes, republished as `task_state` so the panel's running
+     *   marks track child rounds structurally instead of parsing tool-output text;
+     * - background-task state changes (a command promoted or exited, a subagent promoted,
+     *   settling or released), re-counted and published as `session_background` on the user
+     *   channel so every Session list shows which rows still own background work.
+     */
+    private registerNoticeListener;
+    /**
+     * The entry-lifetime approval callback: the registry, the per-decision approval-mode
+     * re-read, and the SSE escalation are all entry-scoped, so one instance serves every run
+     * of the entry and the children's session-lifetime fallback sink alike.
+     *
+     * This is also where the one cross-cutting approval override lives — wrapping the callback
+     * handed to `Session.run` rather than teaching the engine anything: an organization's
+     * sessions run with nobody watching, so a call their approval mode would hand to a person
+     * is denied here instead of waiting for an answer that is never coming (see `unattended`
+     * in approvals.ts). The marker is the row's durable `client = "org"` stamp — desk, ticket
+     * and the sub-sessions that inherit it — read per decision, so a row the reconcile pass
+     * stamps later is covered from its next decision on.
+     */
+    private entryApprove;
+    /** Publishes one live background-subagent message and records its usage (fire-and-forget; the child's own Trace is the durable record). */
+    private forwardBackgroundMessage;
+    /**
+     * Bumps one Agent's config generation so every runtime built before it is discarded on
+     * its next idle access and re-resumed via the loader (history is preserved through the
+     * Trace). What warrants it is a Session-fixed fact changing under the runtime — the
+     * Project's credentials (see invalidateProjectRuntimes). Agent State changes never do:
+     * core reads them into the next model context itself. A Task already in flight is neither
+     * aborted nor hot-swapped: it keeps the values it started with, and its entry is rebuilt
+     * on the first access after it returns to idle (see ensureEntry).
+     */
+    invalidateAgentRuntimes(projectId: string, agentId: string): void;
+    /**
+     * After a Project's models/credentials change: invalidate every cached runtime in this
+     * Project, so the next Task re-resumes with the new api_key / base_url. Same
+     * effective-value semantics as invalidateAgentRuntimes — no hot swap into a Task already
+     * in flight. Iterating the active table is complete here, not a shortcut: the generation
+     * map only matters for runtimes that are already cached, and an Agent with no cached
+     * entry builds fresh through the loader anyway.
+     */
+    invalidateProjectRuntimes(projectId: string): void;
+    /**
+     * Cheap, lock-free rehearsal of the 409/503 conditions startTask checks, throwing exactly the
+     * same HttpErrors. **Advisory only**: it neither takes the Session lock nor loads an entry, so
+     * a session that isn't in the active table reads as acceptable and a status change racing this
+     * call is not caught — the authoritative check is still the one inside startTask.
+     *
+     * It exists so a caller that has irreversible work to do first (POST /tasks writes the
+     * message's file attachments to disk) can find out about the ordinary "a Task is already
+     * running" rejection before doing it, instead of undoing it afterwards.
+     */
+    assertCanAcceptTask(sessionId: string, opts?: {
+        queueIfBusy?: boolean;
+    }): void;
+    /**
+     * Run a metadata operation at an idle Session boundary under the same mutex as Task and
+     * compaction starts. Session fork uses this to snapshot an append-only Trace without a Task
+     * beginning between its status check and final read. An uncached Session is idle by definition;
+     * unlike startTask this path deliberately does not load a heavyweight runtime.
+     */
+    atIdleBoundary<T>(sessionId: string, operation: () => Promise<T>): Promise<T>;
+    /**
+     * Start a Task: get-or-load → 409
+     * mutual-exclusion check → publish the input messages first → drive run in the
+     * background. Returns the current actual session_id (the new id after self-heal).
+     * With `queueIfBusy`, a busy session (running/compacting) enqueues the input as a
+     * follow-up instead of 409: it auto-starts as an ordinary next task once the session
+     * returns to idle (`queued: true` in the result; see startQueuedFollowUp).
+     * `opts.recall` is that queued message's original
+     * content — optional, because only the HTTP route knows the parts of it the input does
+     * not carry (the pre-attachment text and where each file landed on disk); every other
+     * caller's store is read off the input, so a queued follow-up is recallable and shows
+     * its content whichever path queued it.
+     */
+    startTask(sessionId: string, input: OmniMessage[], opts?: {
+        queueIfBusy?: boolean;
+        recall?: RecallStore;
+    }): Promise<{
+        sessionId: string;
+        queued: boolean;
+    }>;
+    /**
+     * Start a goal run: like startTask, but the goal plugin composes the input and its stop
+     * hook drives every later round inside this one `session.run` call — so the Session
+     * stays `running` for the whole goal (every round), the existing abort endpoint
+     * interrupts the entire loop and schedules queue behind it as usual. The plugin's
+     * `user_prompt` hook (hooks run in core and nowhere else — `Session.runUserPromptHook`)
+     * writes the Session's goal file and answers the round-1 protocol message; it runs under
+     * the session lock AFTER the idle check, since it overwrites the goal file a running goal
+     * is reading. Not installed (null) is the route's 409; an empty answer a 500. Round inputs
+     * are yielded by core and published like any streamed message; progress additionally goes
+     * out as goal_* server events (the run state itself is the goal file the plugin maintains).
+     */
+    startGoal(sessionId: string, args: {
+        /** The user's own message(s) exactly as submitted — text and images, no wrapping. */
+        messages: OmniMessage[];
+        /** The user's own objective text (leading marker blocks stripped): what the plugin records, the goal_started event and the title material. */
+        objective: string;
+        budget: number;
+    }): Promise<{
+        sessionId: string;
+    }>;
+    /**
+     * Taps a goal run's stream for `drive`: round boundaries become goal_round events —
+     * round 1 from the seeded input (core never yields a run's initial input, so it is
+     * counted here, where startGoal published it), later rounds from the stop-hook continues
+     * core yields, each announced by the hook's `continue` event; a harness-stamped input
+     * nothing announced is another package's user_prompt context riding behind the
+     * objective, not a round — and the goal hook's `stop` event becomes the
+     * goal_finished server event. `used` is what the hook last recorded in its event's
+     * `output` — the same number its budget check used — so the UI never shows a different
+     * figure. A stream that ends without the hook's terminal event (a cut-off run, an
+     * infrastructure failure) closes as `aborted`.
+     */
+    private goalStream;
+    /** Closes a goal as aborted for the UI (stream cut off / infrastructure failure). */
+    private finishAborted;
+    /** Shared task launch (fresh tasks and auto-started follow-ups): flips to running, publishes the input, and drives the run. Caller holds the session lock and has verified idle. */
+    private launchTask;
+    /**
+     * Auto-start of queued follow-ups: called from drive's finally whenever a Task or
+     * compaction finishes (abort included — follow-ups are future tasks the user queued, so
+     * an abort of the current run does not discard them). Re-validates everything under the
+     * session lock (another task may have snuck in, the server may be shutting down, the
+     * session may be getting deleted) and launches exactly one queued input — the next
+     * finish picks up the one after, keeping order and one-at-a-time semantics.
+     */
+    private startQueuedFollowUp;
+    /** Manually compact the context: 409 if already running; compaction output also flows into the SSE channel. */
+    startCompact(sessionId: string): Promise<{
+        sessionId: string;
+    }>;
+    /**
+     * Switches the Session's model in place (`POST /switch-model`) — core `Session.switchModel`,
+     * gated like a compaction (open, not deleting, idle). Core decides everything before its
+     * first event, so the head of its stream is pulled here, under the lock, and tells the three
+     * outcomes apart:
+     *
+     * - it throws — a refusal, answered 409 with the code of its reason (see `switchRefusal`);
+     * - it is already done — a Session that never ran has no context to close: core re-assembled
+     *   its first context on the target, nothing streams, and the row carries the new pair by
+     *   the time this returns (`switched: true`; the route answers with the fresh DTO);
+     * - it yields — a driven run like a compaction (`switched: false`): status `compacting`,
+     *   idle when it ends. The head is a compaction's begin, the first record of a bootstrap (a
+     *   Session loaded from its Trace opens its context first), or — for a context with no
+     *   completed turn, which streams no pair — the opener's first record.
+     *
+     * The switch is the entry's run from that pull on — it can be stopped, and a deletion or a
+     * shutdown waits for it — while the entry only reads `compacting` once there is something
+     * to stream, so a refusal never flickers a state.
+     *
+     * The entry and the row follow the runtime as the new context's `session_meta` passes
+     * through the drive (see `drive`); a switch that does not complete streams no meta and
+     * leaves them where they were. Usage: a drive bills to the model it started on, so the
+     * switch's compaction request goes to the model that served it and the next run to the new
+     * one.
+     */
+    startSwitch(sessionId: string, ref: ModelRefDto): Promise<{
+        sessionId: string;
+        switched: boolean;
+    }>;
+    /** Who is told when a Session's model moves (see `onModelChanged`). */
+    private readonly modelListeners;
+    /**
+     * Subscribes to a Session's model moving: an in-session switch completing, or a row brought
+     * back in step with its Trace when the Session loads. The listener runs once the entry and
+     * the row carry the new pair. Returns the unsubscribe. Company mode listens: an employee's
+     * model is its desk Session's.
+     */
+    onModelChanged(listener: (sessionId: string, model: ModelRefDto) => void): () => void;
+    /**
+     * Moves the entry — and the row it caches into — to the model the runtime reports itself on,
+     * when that differs: the pair the next drive attributes usage to, and the one
+     * `GET /sessions/:id` describes. A runtime that reports none (test fakes) leaves the entry
+     * alone. The row write is guarded like the other bookkeeping writes (see `touchRow`): a
+     * switch must not be stranded mid-drive by a closed DB handle, and the entry is right either
+     * way. The same holds for whoever listens: a listener that throws is recorded, not rethrown.
+     */
+    private syncEntryModel;
+    /** Submit an approval decision; returns false if the pending approval doesn't exist (already decided/unknown). */
+    decideApproval(sessionId: string, toolCallId: string, decision: "allow" | "deny"): boolean;
+    /**
+     * Mid-run steering: forward the message to the running Session (core delivers it between
+     * turns as a standalone `[user_steering]` user message followed by its images — no SSE
+     * event of its own; the messages arrive through the stream the drive loop already
+     * publishes). 409 when the Session isn't running a Task (idle / compacting / not loaded)
+     * or the run finished in the race window — the caller falls back to submitting a normal
+     * task, which carries the same text and images.
+     *
+     * `recall` is the queued message's original content: its summary (with a fresh id) is
+     * mirrored on the entry and broadcast via `task_state` (and the SSE subscribe snapshot)
+     * until the delivered `[user_steering]` message is observed on the stream — that is what
+     * keeps the composer's "steering queued" hint, content included, alive across reloads —
+     * and the content itself is what a recall (recallSteering) hands back to the composer.
+     */
+    steer(sessionId: string, input: OmniMessage[], recall: RecallStore): void;
+    /**
+     * Recall an undelivered steering message (#287): withdraw it from core's queue and the
+     * display mirror, re-broadcast state, and hand back its original content for the composer
+     * to restore. 409 `not_pending` when the entry is no longer queued — already delivered to
+     * the model (core's `unsteer` says so authoritatively; the mirror can lag behind delivery
+     * until the `[user_steering]` message is observed on the stream), the run exited, or the
+     * id is unknown — all the same outcome for the caller: nothing left to take back.
+     */
+    recallSteering(sessionId: string, steerId: string): RecallStore;
+    /**
+     * Recall a queued follow-up task (#287): remove it from the queue before it auto-starts,
+     * re-broadcast state, and hand back its original content (plus the thinking level it was
+     * queued with). Being in the queue is the whole condition — every queued entry carries a
+     * recall store (see QueuedFollowUp.recall), so no queued message is ever refused. 409
+     * `follow_up_started` when the id is not in the queue: it already auto-started, or the
+     * runtime was released and took the queue with it. Its own code, distinct from steering's
+     * `not_pending`, because the two mean different things to the user — a follow-up became a
+     * task of its own, a steering message reached the model mid-run.
+     */
+    recallFollowUp(sessionId: string, followUpId: string): {
+        recall: RecallStore;
+    };
+    /**
+     * "Retry now" on the reconnect countdown: skip the in-progress backoff wait and fire
+     * the next retry immediately (the attempt counter is unchanged — the skipped wait does
+     * not consume an extra attempt). Returns false as a benign no-op when the session has
+     * no active runtime or no reconnect wait is in progress — timing races (the wait
+     * elapsed right before the click) must not surface as errors. Mirrors the steer seam:
+     * manager → RuntimeSession → core Session → engine.
+     */
+    retryNow(sessionId: string): boolean;
+    /**
+     * Interrupt the current Task/compaction: pending approvals converge to deny first,
+     * then the AbortSignal fires. Returns false if nothing is in progress (the route
+     * treats this as a 204 no-op).
+     */
+    abortTask(sessionId: string): boolean;
+    /**
+     * Background command processes of a LOADED session (empty when the entry is not in
+     * the active table — a resumed entry starts with a fresh environment and can only
+     * ever report an empty list, so nothing is resurrected just to answer a poll).
+     */
+    listProcesses(sessionId: string): BackgroundCommandInfo[];
+    /**
+     * Refreshes the listen-port probes behind the process list's `serviceUrl` (core
+     * `Session.probeBackgroundCommandServices`): called by the processes route before
+     * listing, so the first fetch already carries probed URLs. Bounded by core's own probe
+     * timeout and TTL; a session that isn't loaded has no processes to probe.
+     */
+    probeProcessServices(sessionId: string): Promise<void>;
+    /**
+     * Hands one EXECUTING tool call of a loaded session back as a background task (core
+     * `Session.detachToolCall`): the call closes with a registry handle, its work keeps
+     * running, and the turn carries on. An unloaded session has nothing executing, so it
+     * answers "not_running" like an unknown id.
+     */
+    detachToolCall(sessionId: string, toolCallId: string): ToolDetachResult;
+    /** Kills one background command process of a loaded session; false when the session isn't loaded or the id is unknown. */
+    killProcess(sessionId: string, processId: string): boolean;
+    /**
+     * Removes one EXITED background command entry from a loaded session's process list.
+     * A running process is refused ("running") — stopping is killProcess's job, and a
+     * bare removal must never surprise-signal a live process group. "not_found" covers
+     * an unloaded session and an unknown id alike: the entry is gone either way. The
+     * removal itself reuses the kill path — core's registry removal signals the (dead)
+     * group defensively and drops the row, exactly like input_command's post-exit reap.
+     * The only race, an entry observed running that exits before a retry, is benign:
+     * the caller gets "running", refreshes, and sees the row exited on the next look.
+     *
+     * Note what leaves with the row: the registry entry owns the ManagedSession holding
+     * that process's captured output, so after a removal input_command on the same
+     * process_id answers "unknown process_id". Removal is a deliberate discard, not just
+     * a list tidy-up — the Web App says so at the button and in the docs.
+     */
+    removeProcess(sessionId: string, processId: string): "removed" | "running" | "not_found";
+    /**
+     * Disposes a just-removed entry's runtime — after its in-flight drive (if any)
+     * settles, so interrupt cleanup never races a dying environment. Deleting a Session /
+     * Agent / Project is the one intent that must also end the background processes the
+     * conversation started (a dev server surviving its deleted conversation is
+     * unreachable from every UI, running forever).
+     */
+    private disposeRemoved;
+    /**
+     * Before deleting a Project, converge all its active runs and clear them out of the
+     * active table. Returns the in-flight drive Promises of the affected entries: the
+     * caller (deleteProject) should await them before removing the directory, so that
+     * interrupt-cleanup Trace writes don't recreate the directory after deletion.
+     */
+    abortProject(projectId: string): Promise<void>[];
+    /**
+     * Before deleting an Agent, converge all its active runs and clear them out of the
+     * active table (same semantics as abortProject). Also marks this Agent as "being
+     * deleted": new Tasks/compactions entering during the deletion process are always
+     * rejected with 409 (assertAgentNotDeleting), closing the race window where a new
+     * task recreates the directory and revives an already-deleted Agent between the
+     * abortAgent snapshot and the directory removal. The caller must call
+     * endAgentDeletion once deletion finishes (success or failure).
+     */
+    beginAgentDeletion(projectId: string, agentId: string): Promise<void>[];
+    endAgentDeletion(projectId: string, agentId: string): void;
+    /**
+     * Before deleting a single Session, converge its active run and clear it out of the
+     * active table (same semantics as beginAgentDeletion). Also marks this Session as
+     * "being deleted": new Tasks/compactions entering during the deletion process are
+     * always rejected with 409 (assertSessionNotDeleting), closing the race window where
+     * a new task recreates the entry and Trace file, reviving an already-deleted Session
+     * between the abort snapshot and the file removal. The caller must call
+     * endSessionDeletion once deletion finishes (success or failure). Returns the
+     * in-flight drive Promise: the caller should await it before deleting the Trace file,
+     * so cleanup writes don't recreate the file.
+     */
+    beginSessionDeletion(sessionId: string): Promise<void>[];
+    endSessionDeletion(sessionId: string): void;
+    /** Graceful shutdown: reject new tasks (503), interrupt all active runs, and wait for them to finish (default ≤5s). */
+    shutdown(timeoutMs?: number): Promise<void>;
+    /**
+     * Active-table idle eviction: removes entries that are idle (idle status, no pending
+     * approvals, no in-flight drive) and have been inactive past the timeout, releasing
+     * the core Session's full in-memory history. This is purely memory reclamation: the
+     * next access re-resumes via the loader, so correctness is unaffected. Lock-table
+     * entries are auto-cleaned by withLock once their chain drains (including leftover
+     * entries under the old id after self-heal). `now` / `idleMs` are injectable for
+     * tests and timers.
+     */
+    sweepIdle(now?: number, idleMs?: number): void;
+    private assertOpen;
+    /** The Agent owning this Session is being deleted → 409 (guards against directory recreation inside the deletion race window). */
+    private assertAgentNotDeleting;
+    /** This Session is being deleted → 409 (guards against the entry/Trace being rebuilt and reviving it inside the deletion race window). */
+    private assertSessionNotDeleting;
+    private assertIdle;
+    private generationOf;
+    private refreshProviderCredentialIfNeeded;
+    /** get-or-resume-or-heal: use directly on an active-table hit; otherwise load via the loader, updating the index's primary key on self-heal. */
+    private ensureEntry;
+    /**
+     * Auto-start of queued background completion notices: called when core signals an
+     * idle-session arrival, and from drive's finally for notices that raced a run's exit.
+     * Revalidates under the session lock; only an idle entry launches, and only when the
+     * queue is non-empty — a busy entry skips, because the running/queued task's engine
+     * drains the same queue at its own boundaries (each notice is delivered exactly once).
+     */
+    private startBackgroundNoticeTask;
+    /**
+     * Drive the output stream in the background: publish each message + persist usage +
+     * persist LLM/tool errors; on completion (including errors) resets to idle and pushes
+     * the status. `titleSource` is passed only for Task runs (compaction doesn't generate
+     * a title): its user text drives automatic title generation at run start.
+     */
+    private drive;
+    /**
+     * Register a subagent: persisted only when the origin message is session_meta
+     * (agentId is derived from the agent_state path: `<…>/<agentId>/agent_state`).
+     * **The title is left blank here** — the registration site in drive generates it
+     * right away from the spawning prompt (fallback first words + LLM replacement), so
+     * it never waits for the subagent's own output. Idempotent (children dedup +
+     * insertOrIgnore); a subagent has its own Trace, so it's visible in both the list
+     * and the trace view. On successful registration, the entry is put into `children`
+     * and returned; a duplicate session_meta returns null.
+     */
+    private registerChildSession;
+    /**
+     * Runs one `sessions` row write for a driven run's bookkeeping (has_trace /
+     * last_active_at), swallowing failures the same way the per-message `recorder.record`
+     * call does: bookkeeping must never take down a run's lifecycle. The two call sites both
+     * sit outside a covering try — the run-start write precedes drive's try block, the
+     * run-end one lives in its finally — and the realistic failure (the DatabaseSync handle
+     * closed by shutdown while a run outlived its drain window) throws ERR_INVALID_STATE.
+     */
+    private touchRow;
+    private publishState;
+    private publishEvent;
+    /**
+     * Re-counts a loaded session's background tasks and, when the counts moved, publishes
+     * `session_background` on the user channel (the list's mark is a user-channel affair like
+     * `session_state`; the open conversation reads the same row). A change is Session
+     * activity for the idle sweep: the entry stays loaded for the usual idle window after its
+     * last background task ends, so the finished process list can still be read. An entry
+     * that already left the table (a delete disposing its runtime) publishes nothing — its
+     * row is gone as well.
+     */
+    private publishBackgroundTasks;
+    /**
+     * Publishes `session_approvals` on the user channel: how many tool calls of this Session wait
+     * for a person now. The Session's own stream carries the calls; this is what lets a list, or
+     * a host watching every Session of a Project, see which one waits without subscribing to each.
+     * Sent for an entry that is being disposed too, so a mark it had is cleared.
+     */
+    private publishApprovals;
+    /** Serialize (mutually exclude) execution by sessionId; cleans up the lock-table entry once its chain drains (avoids unbounded growth). */
+    private withLock;
+}
+declare const Sessions_base: (abstract new () => Pick<SessionManager, "steer" | "statusOf" | "pendingApprovalCount" | "pendingApprovals" | "pendingFollowUpCount" | "pendingSteeringOf" | "subagentsOf" | "sendToSubagent" | "abortSubagentRun" | "pendingFollowUpsOf" | "liveFragments" | "pendingInputs" | "pendingBootstrap" | "activeCountForAgent" | "invalidateAgentRuntimes" | "invalidateProjectRuntimes" | "assertCanAcceptTask" | "startTask" | "startGoal" | "startCompact" | "startSwitch" | "onModelChanged" | "decideApproval" | "recallSteering" | "recallFollowUp" | "retryNow" | "abortTask" | "listProcesses" | "probeProcessServices" | "killProcess" | "removeProcess" | "abortProject" | "beginAgentDeletion" | "endAgentDeletion" | "beginSessionDeletion" | "endSessionDeletion" | "atIdleBoundary" | "shutdown" | "sweepIdle">) & (<C>(target: C, context: ClassDecoratorContext) => C);
+/** The session runtime: one entry per live Session, task mutex, approvals, streaming. */
+declare abstract class Sessions extends Sessions_base {
+}
+declare const SessionServiceIface_base: (abstract new () => Pick<SessionService, "toInfo" | "hasTrace" | "listSessions" | "sessionStats" | "createSession" | "defaultSandbox" | "pickSandbox" | "updateSandbox" | "latestTracePath" | "adoptUnmanagedTraceSessions">) & (<C>(target: C, context: ClassDecoratorContext) => C);
+declare abstract class SessionServiceIface extends SessionServiceIface_base {
+}
+
+interface AgentConfigView {
+    agentsMd: string;
+    systemConfigYaml: string;
+    config: AgentConfigDto;
+    stateDir: string;
+}
+declare class AgentConfigService implements AgentConfig {
+    private readonly paths;
+    private get root();
+    /** Whether the Agent exists (determined by the presence of system_config.yaml, matching the CLI's convention). */
+    exists(projectId: string, agentId: string): Promise<boolean>;
+    requireExists(projectId: string, agentId: string): Promise<void>;
+    /**
+     * Read list-card metadata: name / description + tool count (sum of tools.builtin
+     * and tools.mcpServers entries; MCP counted per server). Silently falls back to
+     * empty / 0 if the file is corrupt.
+     */
+    readCardMeta(projectId: string, agentId: string): Promise<{
+        name?: string;
+        description?: string;
+        toolCount: number;
+        version: number;
+        kernelOutdated: boolean;
+    }>;
+    /** Structured config view (matching the edit form's shape) + raw text + AGENTS.md + State path. */
+    getConfig(projectId: string, agentId: string): Promise<AgentConfigView>;
+    /**
+     * PUT accepts any subset: only the provided keys are updated (parseDocument
+     * preserves comments and untouched content); agentsMd is overwritten in full.
+     * Numeric validation: >0 or -1; thinkingLevel / mode are validated as enums.
+     */
+    updateConfig(projectId: string, agentId: string, req: AgentConfigUpdateRequest): Promise<void>;
+    /**
+     * Overwrites system_config.yaml with the current code defaults (core's
+     * resetSystemConfigToDefaults) — same semantics as updating an installed skill:
+     * only the identity fields (name / description / version) survive; the system
+     * prompt, max_turns, model/compaction settings and the tool list (incl. MCP
+     * servers) become the current defaults. AGENTS.md, skills and the vault are
+     * untouched.
+     */
+    resetConfig(projectId: string, agentId: string): Promise<void>;
+    /**
+     * Smart-merges the config up to the current defaults generation (core's applyKernelUpdate):
+     * a settings tab still carrying a recorded generation's default follows the new defaults,
+     * a tab the user changed is kept whole and reported; the config is stamped with the new
+     * kernel version.
+     * The destructive full-refresh alternative stays resetConfig.
+     */
+    kernelUpdate(projectId: string, agentId: string): Promise<AgentKernelUpdateResponse>;
+    private applyConfigUpdate;
+    /**
+     * Inserts a feature's section placeholder into the Agent's prompt template — the explicit
+     * adoption path mirroring the Memory tab's endpoint; nothing ever inserts automatically.
+     * For skills/vault the insert is migration-first (core's helpers): a stored template still
+     * carrying the legacy hardcoded section verbatim gets it replaced in place by the
+     * placeholder, otherwise the placeholder is inserted before `# Environment`. Idempotent;
+     * returns the refreshed config view (the route picks out the feature's DTO).
+     */
+    insertTemplatePlaceholder(projectId: string, agentId: string, feature: "vault" | "skills" | "schedules"): Promise<AgentConfigView>;
+    /** Read the Agent vault (agent_state/.vault.toml): values are always masked, plaintext is never sent to the client. */
+    getVault(projectId: string, agentId: string): Promise<VaultResponse>;
+    /**
+     * PUT replaces the whole vault table (same semantics as models): keys absent from
+     * the body are deleted; omitting value keeps the existing value (a new key must
+     * provide a value). Key names are validated against shell environment variable
+     * naming rules (same rule as core); deleting everything removes the whole
+     * .vault.toml file.
+     */
+    updateVault(projectId: string, agentId: string, req: VaultUpdateRequest): Promise<VaultResponse>;
+}
+
+/** AgentConfig: the mechanism AgentConfigService implements. */
+declare abstract class AgentConfig {
+    abstract exists(projectId: string, agentId: string): Promise<boolean>;
+    abstract requireExists(projectId: string, agentId: string): Promise<void>;
+    abstract readCardMeta(projectId: string, agentId: string): Promise<{
+        name?: string;
+        description?: string;
+        toolCount: number;
+        version: number;
+        kernelOutdated: boolean;
+    }>;
+    abstract getConfig(projectId: string, agentId: string): Promise<AgentConfigView>;
+    abstract updateConfig(projectId: string, agentId: string, req: AgentConfigUpdateRequest): Promise<void>;
+    abstract resetConfig(projectId: string, agentId: string): Promise<void>;
+    abstract kernelUpdate(projectId: string, agentId: string): Promise<AgentKernelUpdateResponse>;
+    abstract insertTemplatePlaceholder(projectId: string, agentId: string, feature: "vault" | "skills" | "schedules"): Promise<AgentConfigView>;
+    abstract getVault(projectId: string, agentId: string): Promise<VaultResponse>;
+    abstract updateVault(projectId: string, agentId: string, req: VaultUpdateRequest): Promise<VaultResponse>;
+}
+/** AgentLifecycle: the mechanism AgentService implements. */
+declare abstract class AgentLifecycle {
+    abstract listAgents(projectId: string): Promise<AgentListItem[]>;
+    /** Every id `createAgent` refuses as taken, as names only, including a folder that does not list. */
+    abstract takenAgentIds(projectId: string): Promise<string[]>;
+    abstract deleteAgent(projectId: string, agentId: string): Promise<void>;
+    abstract createAgent(projectId: string, agentId: string, name?: string, description?: string, skillNames?: readonly string[], directory?: {
+        path: string;
+        names: readonly string[];
+    }, archive?: Buffer<ArrayBufferLike>): Promise<AgentListItem>;
+    abstract pluginVersion(projectId: string, agentId: string, pluginName: string): Promise<{
+        installed: string | null;
+        library: string | null;
+    }>;
+    abstract updatePlugin(projectId: string, agentId: string, pluginName: string): Promise<void>;
+}
+
+interface AgentListItem {
+    agentId: string;
+    name?: string;
+    description?: string;
+    createdAt?: string;
+    /** Last config modification time: the later of system_config.yaml / AGENTS.md mtime. */
+    updatedAt?: string;
+    /** Tool count: number of tools.builtin + tools.mcpServers entries (MCP counted per server). */
+    toolCount: number;
+    /** Agent State version number (missing field treated as 1). */
+    version: number;
+    /** Whether the config's kernel stamp is behind the current defaults generation (missing stamp = outdated) — the list card's update hint. */
+    kernelOutdated: boolean;
+    /** Number of vault keys. */
+    vaultKeyCount: number;
+    /** Number of scheduled tasks (count of .toml files under schedule/, including invalid ones). */
+    scheduleCount: number;
+    /** Number of installed Skills (count of skills/<name>/ directories that contain a SKILL.md). */
+    skillCount: number;
+    /** Number of installed hook packages (hooks/<name>/ directories with a hooks.json). */
+    hookCount: number;
+    /** Installed skills and hook packages the library has a newer version of, by plugin, each carrying that library version. */
+    pluginUpdates: PluginUpdateRef[];
+    /** Number of memory topic files across every scope directory under memory/ (independent of the memory switch, like skillCount). */
+    memoryCount: number;
+}
+declare class AgentService implements AgentLifecycle {
+    private readonly paths;
+    private get root();
+    private readonly agents;
+    private readonly agentConfig;
+    private readonly snapshots;
+    /** Union of DB index ∪ directory scan; unmanaged directory Agents are backfilled into the DB. */
+    listAgents(projectId: string): Promise<AgentListItem[]>;
+    /**
+     * Every id `createAgent` refuses as taken, as names only: the index rows and every entry under
+     * `agents/`. Unlike `listAgents`, this includes a folder with no `system_config.yaml`, and it
+     * opens no Agent.
+     */
+    takenAgentIds(projectId: string): Promise<string[]>;
+    /** Number of vault keys (falls back to 0 on read failure). */
+    private vaultKeyCount;
+    /** Number of scheduled tasks: count of .toml files under schedule/ (0 if the directory doesn't exist). */
+    private scheduleCount;
+    /**
+     * One pass over `skills/` and one over `hooks/`, answering the card's questions: how many
+     * skills and hook packages are installed, and which of them the plugin library has moved
+     * past — by plugin, since a plugin is what gets reinstalled to catch up.
+     *
+     * Only the HEAD of each SKILL.md is read, and that bound is load-bearing rather than a
+     * micro-optimization: a preinstalled library is ~180 KB of SKILL.md across seventeen files
+     * per Agent, so a Project of ten Agents would move ~2 MB through every `GET /agents` — and
+     * the plugin page reloads that list after each update. The frontmatter block is at the head
+     * by definition (the parser's regex is anchored there) and the largest one in the library is
+     * under 1 KB, so {@link SKILL_HEAD_BYTES} covers it many times over; a block that somehow
+     * overran it would be truncated, fail to parse, and read as an empty version — the same
+     * fallback an unparseable file already takes, and one that sorts before every real version.
+     *
+     * The directory name is the identity (core's listings say so, and install/uninstall address
+     * by it), so that — not a frontmatter `name` — is what the library is looked up by: a skill
+     * by the plugin that ships it, a hook package by the plugin of the same name. A skill the
+     * library does not carry (installed from a zip or a picked directory) has no library version
+     * to be behind and is never an update. An unreadable skill degrades to "not installed" / "no
+     * update": a card hint must not be the thing that makes the Agent list fail. The library is
+     * the caller's, read once per listing rather than once per installed skill.
+     */
+    private installedPlugins;
+    /**
+     * Where one library plugin stands on one Agent: `installed` is the OLDEST version among the
+     * plugin's installed skills and its installed hook package — the same "any component behind
+     * the library is an update" rule {@link installedPlugins} draws the list cards' hints from —
+     * and null when the Agent carries none of them; `library` is the version the library offers
+     * now, null when the library has no such plugin. Only the head of each SKILL.md is read
+     * (see SKILL_HEAD_BYTES), so the answer costs one small read per skill the plugin ships.
+     *
+     * The organization runtime asks this per employee per pass to keep company plugins current.
+     * A skill the Agent does not carry — never installed, or removed by hand — counts for
+     * nothing: what is compared is the oldest version the Agent actually has, so a plugin whose
+     * skills are all current reads as current even where one of them is missing. Restoring a
+     * deleted skill is the Agents page's business, not a pass's.
+     */
+    pluginVersion(projectId: string, agentId: string, pluginName: string): Promise<{
+        installed: string | null;
+        library: string | null;
+    }>;
+    /**
+     * Reinstall one library plugin over an Agent's copy: the same whole-plugin update the
+     * Agents page performs, through the same `installPlugin` writer, which overwrites every
+     * skill the plugin ships and its hook package with library content. Throws 404
+     * `unknown_plugin` when the library does not carry the name. Callers that may hold a cached
+     * runtime for the Agent invalidate it afterwards — hook packages are bound when a core
+     * Session is built, unlike skills, which are read from disk on demand.
+     */
+    updatePlugin(projectId: string, agentId: string, pluginName: string): Promise<void>;
+    /** Number of memory topic files: regular `*.md` files (minus each scope's MEMORY.md index) summed over the scope directories under memory/ (0 if the directory doesn't exist). */
+    private memoryCount;
+    /** Last config modification time: the later of system_config.yaml and AGENTS.md mtime; omitted if neither is readable. */
+    private configUpdatedAt;
+    /**
+     * Delete an Agent: the sole built-in Agent
+     * default_agent (shared with the CLI, the default conversation Agent) cannot be
+     * deleted; callers must first drain any active run via manager.abortAgent.
+     * The directory is deleted recursively (including Trace), and the DB's
+     * agents/sessions index rows are removed along with it; usage records are kept
+     * (historical stats are unaffected).
+     */
+    deleteAgent(projectId: string, agentId: string): Promise<void>;
+    /**
+     * Create an Agent: the id is chosen by the creator (a semantic id, checked for
+     * duplicates against both the DB and the directory within the Project — a 409
+     * if taken, which naturally also blocks built-in Agent ids) → initialize State →
+     * write name/description (name defaults to the id) → install the seed plugins.
+     *
+     * `pluginNames` are library plugin names picked at creation; they go through the same
+     * `installPlugin` writer the plugin routes use, inside the same cleanup window as the rest
+     * of initialization, so an Agent never survives with only part of its picked set. They are
+     * resolved before anything is created, so an unknown name creates no directory at all.
+     *
+     * `archive` is an exported Agent State snapshot package: the fresh Agent is seeded from
+     * it instead of the default template (explicit name/description override the package's
+     * values, absent ones keep them — no id fallback). Mutually exclusive with seeding: the
+     * package carries its own skills and hooks. An invalid package fails the whole creation
+     * inside the same cleanup window, leaving no empty Agent behind.
+     */
+    createAgent(projectId: string, agentId: string, name?: string, description?: string, pluginNames?: readonly string[], directory?: {
+        path: string;
+        names: readonly string[];
+    }, archive?: Buffer): Promise<AgentListItem>;
+}
+
+/** MessagingBindings: the mechanism MessagingBindingsRepo implements. */
+declare abstract class MessagingBindings {
+    abstract find(sessionId: string, channel: string): MessagingBindingRow | null;
+    abstract findEnabled(sessionId: string): MessagingBindingRow | null;
+    abstract listForSession(sessionId: string): MessagingBindingRow[];
+    abstract findEnabledByAccount(channel: string, accountId: string): MessagingBindingRow | null;
+    abstract listAll(): MessagingBindingRow[];
+    abstract upsert(args: {
+        sessionId: string;
+        channel: string;
+        accountId: string;
+        config: Record<string, unknown>;
+        linePerMessage?: boolean;
+        finalReplyOnly?: boolean;
+        renderMarkdown?: boolean;
+    }): MessagingBindingRow;
+    abstract setEnabled(sessionId: string, channel: string, enabled: boolean): void;
+    abstract recordChat(sessionId: string, channel: string, chatId: string, isDirect: boolean): void;
+    abstract recordInboundWatermark(sessionId: string, channel: string, messageId: string | null): void;
+    abstract delete(sessionId: string, channel: string): void;
+    abstract deleteSession(sessionId: string): void;
+}
+
+interface MessagingBindingRow {
+    sessionId: string;
+    /** Messaging channel discriminator (`feishu` | `telegram` | `qq` | `wechat`). */
+    channel: string;
+    /** Channel-scoped bot/app identity (feishu: the app_id; telegram: the bot token's numeric id; qq: the App ID; wechat: the scanned bot id); never secret. */
+    accountId: string;
+    /** Channel-specific config document (feishu: appId/appSecret/baseDomain; telegram: botToken; qq: appId/appSecret; wechat: botId/botToken/baseUrl/userId). */
+    config: Record<string, unknown>;
+    /**
+     * INTENT state: whether the binding should hold a live connection (the connection's
+     * runtime status stays in memory). Saving credentials never flips it — only the
+     * explicit state toggle does — and new bindings start disabled. Flipping it on is what
+     * binds the account to this Session: at most one of a Session's rows is enabled, and at
+     * most one row per `(channel, accountId)` is enabled across all Sessions (both
+     * route-enforced).
+     */
+    enabled: boolean;
+    /**
+     * DELIVERY preference: send each non-blank line of a relayed assistant reply as its own
+     * message instead of one message per reply. Off by default, and off reproduces the
+     * original behaviour exactly. Ordinary saved state — the PUT owns it, like the config.
+     */
+    linePerMessage: boolean;
+    /**
+     * DELIVERY preference: relay only the LAST completed assistant message of a run, sent when
+     * the run ends, instead of mirroring each of them as it completes. Off by default, and off
+     * reproduces the original behaviour exactly. Independent of `linePerMessage`: with both set
+     * that one final message is what gets split per line. Ordinary saved state, like the field
+     * above.
+     */
+    finalReplyOnly: boolean;
+    /**
+     * DELIVERY preference: render a relayed assistant reply's Markdown in the channel's own
+     * markup rather than sending its characters as written. ON by default — the model writes
+     * Markdown, and relaying it raw is what this replaced. What survives differs per channel
+     * (Telegram has no headings, lists or tables; QQ has no code or tables; Feishu has all of
+     * them) and a rendering the channel refuses falls back to the plain source, so the setting
+     * can cost formatting and never a message.
+     */
+    renderMarkdown: boolean;
+    /**
+     * Most recent inbound chat (null until the bot is messaged once). The channel's connector
+     * mints this string and is the only thing that may read it: Telegram encodes the forum
+     * topic into it, so it is not always a bare chat id. Pass it to `MessagingClient.sendText`,
+     * never to a channel API directly.
+     */
+    lastChatId: string | null;
+    /** Whether that chat is a direct chat; group chats prefer reply-to-message. */
+    lastChatIsDirect: boolean;
+    /**
+     * Channel id of the most recently processed inbound message (null until one arrives).
+     * The bridge's redelivery guard is in memory and dies with the process; this is the one
+     * fact that survives it, so a channel replaying an already-processed event across a
+     * restart is recognized rather than run again (see MessagingBridge's recentInbound).
+     */
+    lastInboundMessageId: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+
+/**
+ * The messaging-channel connector seam: what the MessagingBridge needs from one chat
+ * platform (Feishu, Telegram, QQ and WeChat today; further channels implement the same interface
+ * and register in app assembly). A connector owns everything channel-specific — credential
+ * shape, wire protocol, event normalization — and hands the bridge a channel-neutral
+ * view: a client for outbound sends and credential checks, and a long-lived event
+ * connection delivering normalized inbound messages (text, images and files, each as far as
+ * the channel actually carries them).
+ *
+ * Config documents are the repo's stored per-channel JSON (`MessagingBindingRow.config`);
+ * every connector method validates its own shape and throws a readable error on a
+ * malformed one — the bridge treats that like any other channel failure.
+ */
+
+/** One inbound image's bytes, once fetched, with the MIME type the bridge needs for its data URL. */
+interface MessagingInboundImageData {
+    data: Buffer;
+    /** e.g. `image/png` — the connector's best answer, from the channel's own type or the bytes. */
+    mimeType: string;
+}
+/**
+ * An image attached to an inbound message: a handle, not the bytes.
+ *
+ * The bytes are deliberately NOT eagerly downloaded by the connector. Most of what makes
+ * an inbound message uninteresting is decided after the event is normalized — a
+ * redelivery is dropped before anything else happens — and a channel that downloaded
+ * first would pay a full image transfer for every replay. Fetching lazily also puts the
+ * cap where the transfer is: `fetch` refuses anything over `maxBytes` rather than handing
+ * the bridge something it would only discard, which is what keeps a 100MB attachment from
+ * ever being resident in this process.
+ */
+interface MessagingInboundImage {
+    /**
+     * Downloads the image. Two distinct failures, and the bridge answers them differently:
+     * `MessagingMediaTooLargeError` (see media.ts) for anything past `maxBytes`, which the
+     * user fixes by sending something smaller, and any other Error — carrying the channel's
+     * OWN reason, since a permission the bot lacks and a network blip are not the same
+     * problem — for a transfer that could not be made at all. That reason reaches the chat,
+     * so a connector must keep credentials out of it (see telegram-api's fetchErrorText).
+     */
+    fetch(maxBytes: number): Promise<MessagingInboundImageData>;
+}
+/**
+ * A non-image file attached to an inbound message: a handle, not the bytes, for exactly the
+ * reasons MessagingInboundImage is one — a redelivery is dropped before anything is
+ * transferred, and the cap rides into `fetch` so an oversized attachment is refused at the
+ * byte that crosses it rather than buffered whole and measured afterwards. A file's ceiling
+ * is the server's per-file attachment limit, which is far larger than an image's, so the
+ * difference between refusing during and after the transfer is correspondingly larger.
+ *
+ * There is no MIME type on this seam. An image needs one because its bytes become a `data:`
+ * URL inside the conversation; a file's bytes go to the Session scratchpad and reach the
+ * model as a PATH, so the name's extension is the whole of what says what it is — and a
+ * channel's declared media type is the sender's claim about a file nothing here parses.
+ */
+interface MessagingInboundFile {
+    /**
+     * The sender's own file name, extension included — what the model sees at the end of the
+     * `[attached file: …]` path, and what a refusal notice names. Channel text, so it is
+     * neither trusted nor pre-sanitized here: the attachment writer maps it onto a name that
+     * is safe on disk (see services/task-attachments.ts). A channel with no name for a file
+     * says so with a plain fallback rather than inventing one, since a made-up extension
+     * would tell the model the file is something it is not.
+     */
+    fileName: string;
+    /** Downloads the file; the same two failure shapes MessagingInboundImage.fetch documents. */
+    fetch(maxBytes: number): Promise<Buffer>;
+}
+/** One inbound chat message, normalized across channels. */
+interface MessagingInboundMessage {
+    /**
+     * Channel-scoped chat id, and the reply target for direct chats. Opaque to the bridge, for
+     * the same reason `messageId` is: the connector both mints it here and consumes it in
+     * `sendText`, so a channel whose replies need more routing context than a chat identity
+     * encodes it (Telegram appends the forum topic). It is stored verbatim as the binding's
+     * last known chat, so whatever is encoded here is what survives a restart.
+     */
+    chatId: string;
+    /** Direct chat with the bot, or a group chat (groups prefer reply-to-message). */
+    chatKind: "direct" | "group";
+    /**
+     * Channel-scoped id of the inbound message itself (the group reply target). Opaque to
+     * the bridge: the connector both mints it here and consumes it in `replyText`, so a
+     * channel whose native message ids are not globally unique encodes whatever context a
+     * reply needs (Telegram packs `chatId:messageId`). It is also the bridge's inbound
+     * dedupe key, so it must identify the MESSAGE and not the delivery: a channel that
+     * redelivers one message must mint the same id both times. `""` opts the channel out of
+     * deduplication entirely — the honest answer for a connector with no message identity,
+     * and better than every message after the first reading as a duplicate.
+     */
+    messageId: string;
+    /**
+     * The message's plain text; null for anything that carries none (stickers, voice, …) — a
+     * message with no text, no image and no file gets the not-supported notice. An image or a
+     * file sent with a caption puts the caption here: the caption IS that message's text, so
+     * a channel needs no second field for it and the bridge no second rule. A channel that
+     * carries a caption on media it does NOT deliver must still report null, or the model
+     * answers a question about an attachment it never received.
+     */
+    text: string | null;
+    /**
+     * Images attached to this message (absent or empty when there are none). Handles rather
+     * than bytes — see MessagingInboundImage. A channel that carries several images in one
+     * message lists them in the order the user sees them.
+     */
+    images?: readonly MessagingInboundImage[];
+    /**
+     * Non-image files attached to this message, in the order the user sees them (absent or
+     * empty when there are none) — see MessagingInboundFile.
+     *
+     * Optional, like `images`, so a channel that delivers no files simply never populates it
+     * rather than carrying an empty list through its whole normalizer. A message may carry
+     * text, images and files together; the bridge composes one composer input out of whatever
+     * is there.
+     */
+    files?: readonly MessagingInboundFile[];
+    /** Sender display name when the channel's event carries one. */
+    senderName?: string;
+}
+interface MessagingConnectorHandlers {
+    onMessage(msg: MessagingInboundMessage): void | Promise<void>;
+    /** The connection completed a handshake (may fire again after an automatic reconnect). */
+    onReady?(): void;
+    /**
+     * The connection failed and the channel gave up (or the initial connect failed). A
+     * {@link MessagingChannelError} says whether the outage clears without anyone acting.
+     */
+    onError?(err: unknown): void;
+}
+/** A live inbound event stream; `close` ends it (idempotent). */
+interface MessagingConnection {
+    close(): void;
+}
+/**
+ * A successful credential check's optional payload: whatever the probe learned that the test
+ * endpoint's feedback can act on. Every member is independently optional — a channel reports
+ * the ones its check happens to answer and omits the rest, so a check that learned nothing
+ * beyond "these credentials work" returns an empty object.
+ */
+interface MessagingAccountInfo {
+    /** A short human-readable label of the account the credentials sign in as (Telegram: the bot's `@username`). */
+    accountLabel?: string;
+    /**
+     * Whether this ACCOUNT is set up to receive ordinary messages in the groups it belongs to
+     * — as opposed to only the ones a platform hands a bot by default.
+     *
+     * Telegram's privacy mode is the case that needs saying: it is on for every bot whose
+     * owner has not turned it off in @BotFather, and under it `getUpdates` simply omits
+     * everything in a group that is not a command addressed to this bot or a reply to one of
+     * its messages. Nothing errors — the messages are never delivered, so a binding that works
+     * perfectly in a direct chat looks dead in a group. It is one account-wide setting and
+     * Telegram overrides it in any group the bot administers, so `false` says the account is
+     * muted where it is an ordinary member, never that some particular group is silent. Absent
+     * when the channel has no such notion, or reports nothing about it: unknown must never be
+     * reported as a problem.
+     */
+    readsGroupMessages?: boolean;
+}
+/**
+ * What a send had to give up in order to land, as a short readable phrase. The message DID
+ * arrive — a send that did not throws — so this is not a failure: it says the message is
+ * somewhere less right than it was addressed to, which is otherwise invisible from the
+ * outside. A channel that always delivers as addressed returns nothing at all; Telegram is
+ * the one that reports, a forum topic deleted under a live conversation sending the reply to
+ * General instead.
+ */
+type MessagingSendNote = string;
+/** One file on its way out to a chat: the bytes, plus the name the chat should show. */
+interface MessagingOutboundFile {
+    /** Display name — the base name of the Workspace-relative path the reply mentioned. */
+    fileName: string;
+    data: Buffer;
+}
+/** How one outbound text should be rendered. Absent throughout means plain text. */
+interface MessagingSendOptions {
+    /**
+     * Read the text as Markdown and render it in whatever this channel's markup is.
+     *
+     * A REQUEST, not an instruction: the connector owns both what its channel can show and
+     * what to do when the channel refuses the rendered form, and it must fall back to sending
+     * this same text plainly rather than let a formatting failure cost the message. What
+     * survives the conversion differs per channel and is documented at each renderer
+     * (telegram-html.ts, feishu-card.ts, qq-markdown.ts).
+     *
+     * Only a relayed assistant message ever sets it. The fixed notices and the test message
+     * carry no markup and are sent as they are written, so a bug in a renderer can never
+     * reach the one message a user sends to check whether the binding works at all.
+     */
+    markdown?: boolean;
+}
+/** Outbound half of one bound account. Every method throws on failure with a readable reason. */
+interface MessagingClient {
+    /** Credential check (used by the test endpoint); resolving means the config signs in. */
+    checkCredentials(): Promise<MessagingAccountInfo | null>;
+    /** Sends a text message into a chat by chat id; resolves a MessagingSendNote when it degraded. */
+    sendText(chatId: string, text: string, opts?: MessagingSendOptions): Promise<MessagingSendNote | void>;
+    /** Replies a text message to a specific inbound message (threads correctly in group chats). */
+    replyText(messageId: string, text: string, opts?: MessagingSendOptions): Promise<MessagingSendNote | void>;
+    /**
+     * Sends a picture into a chat, so a chart the Agent drew arrives as something the reader
+     * can see rather than as a download. Channels that need an upload step first do it here —
+     * the bridge holds bytes and a name, never a channel's file handle.
+     */
+    sendImage(chatId: string, file: MessagingOutboundFile): Promise<void>;
+    /** Sends any other file into a chat as an attachment. */
+    sendFile(chatId: string, file: MessagingOutboundFile): Promise<void>;
+}
+interface MessagingChannelConnector {
+    readonly channel: MessagingChannel;
+    /**
+     * How many outbound messages this channel will accept in answer to ONE inbound message,
+     * or undefined where no such limit exists (Feishu and Telegram both send freely).
+     *
+     * A channel that declares one enforces it itself — the connector is the only place that
+     * knows what the platform rejects and how to combine messages so nothing is lost. What
+     * the bridge does with the number is narrower: it caps the one-message-per-line split at
+     * it, because that option's own ceiling is sized for a channel with no such budget and
+     * would otherwise ask for more messages than the channel can ever deliver.
+     */
+    readonly replyBudget?: number;
+    /** Builds the outbound client for one stored config (throws on a malformed document). */
+    createClient(config: Record<string, unknown>): Promise<MessagingClient>;
+    /**
+     * Opens the inbound event stream for one stored config. Resolves as soon as the
+     * connection is constructed and connecting — lifecycle arrives via the handlers
+     * (`onReady` / `onError`), because channels reconnect on their own and a single promise
+     * cannot carry a lifecycle.
+     */
+    connect(config: Record<string, unknown>, handlers: MessagingConnectorHandlers): Promise<MessagingConnection>;
+}
+
+/**
+ * Auth middleware: `Authorization: Bearer <local API token>` -> the built-in admin, or
+ * session cookie -> auth_sessions row -> user; either way the user is injected into c.var.
+ *
+ * The Bearer path authenticates the boot's local API token (`<root>/api-token`, see
+ * auth/api-token.ts) as the admin — the CLI's and agents' machine-local credential; it
+ * applies to every route behind this middleware, SSE endpoints included (the CLI
+ * consumes SSE via fetch with headers). A Bearer header that does not match fails the
+ * request rather than falling back to the cookie: silently downgrading a wrong explicit
+ * credential would mask misconfiguration. A few writes refuse the token all the same and take a
+ * person's sign-in (requireHuman).
+ *
+ * Accessing a protected API while logged out -> 401 `{error:{code:"unauthorized"}}`.
+ * CSRF: SameSite=Lax plus a Content-Type an HTML form cannot forge (see jsonOnlyWrites).
+ * That guard stays for Bearer requests too — the CLI always sends application/json.
+ */
+
+/** Hono env: variables injected by the auth middleware. */
+type AppEnv = {
+    Variables: {
+        user: UserRow;
+        /** How the current session was established — see {@link SessionVia}. */
+        sessionVia: SessionVia;
+    };
+};
+
+/** Minimal dependency on SessionManager (eases test doubles; mirrors ScheduleTaskRunner). */
+interface MessagingTaskRunnerShape {
+    statusOf(sessionId: string): string;
+    startTask(sessionId: string, input: OmniMessage[], 
+    /**
+     * `recall` is what a queued follow-up hands back when the user withdraws it in the Web
+     * App. It is optional because the manager derives one from the input for every caller
+     * that has nothing to add; the inbound path supplies its own only when it wrote file
+     * attachments, whose on-disk paths the input does not carry (see inboundRecallStore).
+     */
+    opts: {
+        queueIfBusy: boolean;
+        recall?: RecallStore;
+    }): Promise<{
+        sessionId: string;
+        queued: boolean;
+    }>;
+}
+/**
+ * Minimal dependency on the sessions index: existence checks for reconcile/cascade, the
+ * Session's Project/Agent so a messaging failure can be filed under them (see recordError),
+ * and the one field an outbound file needs — the Workspace a mentioned path resolves against.
+ */
+interface MessagingSessionIndex {
+    findById(sessionId: string): {
+        projectId: string;
+        agentId: string;
+        workspace: string;
+    } | null;
+}
+/**
+ * Minimal dependency on the Workspace file service. Narrow, but deliberately NOT a
+ * reimplementation: both methods carry that service's containment rules (a path that leaves
+ * the Workspace — by `..`, by an absolute path, or through a symlink — is refused there,
+ * and reads happen on the canonical path). A second resolver living in the bridge is
+ * exactly the kind of thing that ends up one security fix behind.
+ */
+interface MessagingWorkspaceFiles {
+    /**
+     * The subset of `rels` that exist as regular files inside the Workspace, each with the
+     * time it was last written — which is what separates a file this run produced from one
+     * the reply merely named (see deliverFiles).
+     */
+    statExistingWithMtime(workspace: string, rels: string[]): Promise<{
+        rel: string;
+        mtimeMs: number;
+    }[]>;
+    /** Reads a file, at most `maxBytes` of it. */
+    read(workspace: string, rel: string, options?: {
+        maxBytes?: number;
+    }): Promise<{
+        data: Buffer;
+        fileName: string;
+    }>;
+}
+interface MessagingBridgeDeps {
+    repo: MessagingBindings;
+    sessions: MessagingSessionIndex;
+    files: MessagingWorkspaceFiles;
+    /**
+     * The data root, so an inbound file can be written into the Session scratchpad the web
+     * composer's uploads land in (`scratchpadDir(root, projectId, agentId)/<sessionId>`,
+     * deleted with the Session). The bridge holds the root rather than a pre-resolved
+     * directory because the Project and Agent are per Session, not per binding.
+     */
+    root: string;
+    /**
+     * The attachment limits in force right now. A function, not a snapshot: the per-file and
+     * per-message ceilings are admin-settable and read fresh per request everywhere else, so
+     * a change has to reach the next inbound message without a restart.
+     */
+    attachmentLimits: () => AttachmentLimits;
+    channels: ChannelHub;
+    runner: MessagingTaskRunner;
+    /** One connector per channel; a stored binding whose channel has no connector is skipped with an error record. */
+    connectors: readonly MessagingChannelConnector[];
+    errors: ErrorSink;
+    log?: (line: string) => void;
+    now?: () => number;
+    /** Test hook: the pace between a per-line reply's messages (default MESSAGING_LINE_DELAY_MS; tests collapse it to zero). */
+    lineDelayMs?: number;
+    /** Test hook: one binding's inbound image budget (default MESSAGING_INBOUND_IMAGE_BUDGET_BYTES). */
+    inboundImageBudgetBytes?: number;
+}
+declare class MessagingBridge {
+    private readonly deps;
+    private readonly entries;
+    /**
+     * Processed inbound ids per BINDING (`sessionId:channel`), deliberately not per
+     * connection: re-saving an enabled binding restarts its connector, and a message
+     * already turned into a Task must not run again because the connector is new.
+     *
+     * This map dies with the process; `messaging_bindings.last_inbound_message_id` is the
+     * half that does not, and `connect` folds it back in here so the two are one memory
+     * rather than two guards. The row holds ONE id — the last message the bridge finished
+     * with — which is what Feishu's WebSocket resume needs and all it needs: that stream
+     * replays events it never saw acknowledged, and the SDK acknowledges each one only
+     * after our handler returns, so at most the one in flight when the process ended is
+     * still owed. Telegram redelivers nothing across a restart — its poller advances
+     * `offset` past an update before handing it over, and a fresh connection drains with
+     * `getUpdates({offset: -1})`, discarding whatever was sent while nobody was connected —
+     * so on that channel the row is still written and still seeded, and simply never has a
+     * replay to catch.
+     */
+    private readonly recentInbound;
+    /** Inbound image budgets, keyed like recentInbound: per BINDING, surviving a reconnect. */
+    private readonly imageBudgets;
+    private readonly connectors;
+    private readonly now;
+    private readonly log;
+    private readonly lineDelayMs;
+    private readonly inboundImageBudgetBytes;
+    constructor(deps: MessagingBridgeDeps);
+    /**
+     * Server startup: connect every ENABLED binding (disabled ones keep their credentials
+     * and stay dark; at most one per Session is enabled). A binding whose Session no longer
+     * exists (deleted while this server was down, or by a bulk Agent/Project delete that
+     * bypassed the per-session cascade) is reconciled away instead of connected.
+     */
+    start(): Promise<void>;
+    /** App dispose: close every connection; bindings persist for the successor's start(). */
+    stop(): void;
+    /**
+     * Align the live connection with the stored intent: an enabled binding exists →
+     * (re)connect with its CURRENT config, none → disconnect. The state toggle calls this
+     * after flipping intent, and a credential save calls it only while the saved binding is
+     * enabled — the restart that keeps stored config and live connection from diverging.
+     */
+    sync(sessionId: string): Promise<void>;
+    /** Route DELETE: disconnect (when this channel holds the connection) and drop the row. No-op when unbound. */
+    unbind(sessionId: string, channel: string): void;
+    /** Session-delete cascade: disconnect and drop every channel's config. */
+    unbindSession(sessionId: string): void;
+    /**
+     * One channel's runtime status (only the connected channel is ever anything but
+     * disconnected), plus what this connection has actually seen: when a message last arrived,
+     * what last failed after one did, and the last connection failure even after it recovered.
+     * A binding can be `connected` with nothing wrong and still never receive anything, and
+     * that combination is invisible without them.
+     */
+    statusOf(sessionId: string, channel: string): MessagingRuntimeStatus;
+    /**
+     * Credential probe for the test endpoints: ok/error with latency, never a throw. A
+     * channel whose check identifies the account (Telegram: the bot's @username) passes
+     * that label through for the route's success feedback, along with anything else the
+     * probe learned that the user should act on (see MessagingAccountInfo).
+     */
+    testCredentials(channel: string, config: Record<string, unknown>): Promise<{
+        ok: boolean;
+        latencyMs?: number;
+        accountLabel?: string;
+        readsGroupMessages?: boolean;
+        error?: string;
+    }>;
+    /**
+     * Test-message endpoints: a short fixed text to the binding's last known chat. The
+     * route has already established that the binding and its chat exist; a race that
+     * removed either since surfaces as the send failing.
+     */
+    sendTestMessage(row: MessagingBindingRow): Promise<void>;
+    private connectorFor;
+    private connect;
+    private disconnect;
+    /** Every timestamp this bridge writes comes from the injected clock, never from `Date` directly. */
+    private nowIso;
+    /** Status write, guarded against a stale entry (replaced by a newer connect). */
+    private setStatus;
+    /**
+     * A connection failure, put in the three places one belongs: the live `error` state, the
+     * copy kept across recovery, and the error table.
+     *
+     * Behind the same stale-entry guard `setStatus` uses, applied to all three — a connector
+     * callback firing after a newer connect replaced this entry is reporting an attempt that was
+     * already abandoned, and neither its status writes (which nothing reads) nor its record
+     * (which would be filed against a binding since reconfigured) belong to the binding as it
+     * now stands.
+     */
+    private recordConnectionFailure;
+    /**
+     * One error record for a messaging failure, filed under the Session's Project and Agent.
+     *
+     * The attribution is load-bearing, not decoration: `GET /api/projects/:id/usage/errors`
+     * selects by project, and a record with none is "unattributed" — served only to admins
+     * (`includeGlobalErrors`), so an ordinary member could never see a failure of their own
+     * binding anywhere. The lookup uses the sessions index the bridge already holds; a row
+     * deleted since leaves the record unattributed rather than dropping it.
+     */
+    private recordError;
+    /**
+     * A failure AFTER an inbound message was accepted: recorded like any other, and also put
+     * on the binding's runtime status so the panel can say it. The error table is a Project-wide
+     * dashboard nobody visits to debug one bot; the binding's own panel is where the question
+     * is asked.
+     *
+     * A later success does not clear it. An intermittent failure — a group admin who revokes
+     * send rights for a minute, a rate limit — would otherwise be erased by the next ordinary
+     * message and never be seen at all, which is the same blind spot `lastConnectionError`
+     * exists to close. The panel states `at` so a stale one reads as stale.
+     */
+    private recordDeliveryFailure;
+    /**
+     * A send that landed somewhere less right than it was addressed to. Not a failure — the
+     * message arrived — so it stays out of `lastDeliveryError` and off the panel, and goes to
+     * the log, which is where "the replies moved to General a while ago" is answerable at all.
+     */
+    private noteSend;
+    private clientFor;
+    /**
+     * Has this binding already processed this message? A duplicate is a complete no-op —
+     * ahead of the chat record and the text-only reply, not just the Task start, because a
+     * replayed sticker would otherwise answer with the notice twice.
+     *
+     * Nothing downstream is idempotent: `startTask` with `queueIfBusy` appends to the
+     * follow-up queue unconditionally, and a queued input is published to the Session
+     * channel, so one redelivery becomes two runs in the chat AND two messages in the Web
+     * App. A connector that mints no id opts out rather than having every message after the
+     * first read as a duplicate.
+     */
+    private isRedelivery;
+    /** Get-or-create one binding's processed-id memory (see recentInbound). */
+    private inboundMemoryOf;
+    private onInbound;
+    /**
+     * Turns a message carrying attachments into one Task, or resolves the notice to answer
+     * the chat with when it could not be made whole.
+     *
+     * All-or-nothing across BOTH kinds, and in this order: the images are downloaded first,
+     * then the files, and only then is anything written to disk. A refusal on either side
+     * stops the message — a message is one thing the user sent, and half of it reaching the
+     * Agent is not a partial success but a misleading one — and refusing before the write
+     * means a rejected message leaves nothing behind in the scratchpad to clean up.
+     */
+    private startAttachedTask;
+    /**
+     * Lands this message's files in the Session scratchpad and folds their path lines into the
+     * input. Returns the input untouched when there are none, so a message with no files
+     * creates no directory.
+     *
+     * A failure here is NOT answered in the chat, unlike a refused download: a write that
+     * fails is a fault of this server (a full disk, a scratchpad that is not writable), the
+     * same class as a Session that cannot load, and it reaches the user through
+     * recordDeliveryFailure and the binding's status line. The chat is told about the things
+     * the person in it can act on.
+     */
+    private writeInboundFiles;
+    /**
+     * Downloads the message's files into composer attachments, or the notice to answer with
+     * when one of them could not be delivered.
+     *
+     * The caps are the server's attachment limits — the very numbers an authenticated
+     * composer upload answers to — because these files land in exactly the same place, the
+     * Session scratchpad, and are read back the same way, through the model's bounded file
+     * tools. Both byte budgets apply:
+     *
+     * - the per-file ceiling rides into each `fetch`, so an oversized attachment is refused at
+     *   the byte that crosses it and is never resident in this process;
+     * - the per-message total is spent as the batch is collected, each later file's cap
+     *   shrinking to what is left, so a message carrying several cannot add up past it either.
+     *
+     * The per-message file COUNT is deliberately not enforced: attachment-limits.ts calls it a
+     * composer-usability bound rather than a resource one, the byte budgets being what actually
+     * bound memory and disk — and a chat message carries one file today on both channels.
+     *
+     * There is no rolling per-binding budget like the image one, because the cost it exists to
+     * prevent is not paid here: an inline image is written into the Trace and re-read whole on
+     * every history page and every resume, while a file is bytes on disk that nothing re-reads
+     * and that are deleted with the Session.
+     *
+     * A refusal for size is the user's to fix and is not an error record — they sent something
+     * too big and the chat says so. A failure is somebody's fault (a scope the bot was never
+     * granted, most likely) and lands in the error log with the channel's reason, so it is
+     * diagnosable from the dashboard and not only from a chat bubble.
+     */
+    private inboundFileAttachments;
+    /**
+     * Downloads the message's images into `image_url` input parts, or the notice to answer
+     * with when one of them could not be delivered.
+     *
+     * The cap is the server's inline-image ceiling — the same number the web composer's
+     * uploads answer to, because these images land in exactly the same place (the
+     * conversation, and from there the Trace, which is read back whole on every resume). It
+     * happens to match Telegram's own 20MB download ceiling for bots.
+     *
+     * A refusal for size is the user's to fix and is not an error record — they sent
+     * something too big and the chat says so. A failure is somebody's fault (a scope the bot
+     * was never granted, most likely) and lands in the error log with the channel's reason,
+     * so it is diagnosable from the dashboard and not only from a chat bubble.
+     */
+    private inboundImageParts;
+    /** This binding's rolling image budget, created on first use (see InboundImageBudget). */
+    private imageBudgetFor;
+    /** Reply to the inbound message itself: threaded reply in groups, plain send in direct chats. */
+    private replyInbound;
+    /** Channel tap: each main-conversation completed assistant message + the run-state flips. */
+    private observe;
+    /**
+     * Queues one completed assistant message for the bound chat — or holds it back.
+     *
+     * Appended to the entry's send chain rather than started here: a run can complete several
+     * messages within milliseconds, and two sends racing would reach the chat in the wrong
+     * order. Returns immediately either way, so a slow channel never blocks the Session's
+     * stream handling.
+     *
+     * A binding with `finalReplyOnly` set sends nothing from here: the message replaces
+     * whatever this run was already holding, and the last one standing is delivered at the
+     * run's idle edge (see onTaskState). The preference is read per message off the stored row,
+     * as every delivery preference is, and no run ever sees it change: each of the three PUT
+     * handlers calls `sync` on an enabled binding, `sync` reconnects, and `connect` opens with a
+     * disconnect and a fresh entry — so a save made mid-run discards whatever was held at that
+     * moment along with the rest of this entry's memory (see heldReply).
+     */
+    private relay;
+    /**
+     * Whether this binding holds a run's intermediate messages back. A row that cannot be read
+     * at all is deliberately not decided here: relaying is the default, and the same read
+     * inside deliverReply then records the failure rather than letting it pass as a preference.
+     */
+    private finalReplyOnly;
+    /**
+     * Where this entry's traffic would go right now: null before any chat is known, and null
+     * when the row cannot be read at all — a caller holding null falls back to reading it again
+     * at delivery time, which is where a failure to read is recorded rather than swallowed.
+     */
+    private replyTargetOf;
+    private onTaskState;
+    /**
+     * Sends one relayed assistant message to the bound chat, in chunks under the channel's cap.
+     * Which messages arrive here is the caller's business — every completed message of the run,
+     * or its last one alone when the binding holds the rest (`finalReplyOnly`) — and nothing
+     * below is affected by the difference.
+     *
+     * `at` is where to put it. A message relayed as it completes passes none and goes to the
+     * chat the row names now, which is where the conversation is. A held reply passes the target
+     * captured when its run started (see onTaskState), because it leaves at the run's END: a
+     * second user writing in another forum topic meanwhile would otherwise take delivery of a
+     * whole answer to a question they never asked, quoted onto their own message.
+     *
+     * A send failure is recorded, never thrown, so the chain behind it keeps
+     * moving — and so do the messages behind it in THIS reply: one refused message (a 429 on
+     * the third line of twelve) must not abandon the rest, which would leave a reply stopping
+     * mid-sentence with nothing in the chat to say why. A binding with `linePerMessage` set
+     * sends one message per non-blank line instead of one per reply (see splitReplyLines,
+     * capped at the channel's own `replyBudget` where it declares one), paced
+     * MESSAGING_LINE_DELAY_MS apart so the burst stays inside the channel's per-chat
+     * allowance — chunking, threading and ordering are identical either way, and with the flag
+     * off the send sequence is unchanged. In a group the run's
+     * first outbound chunk threads onto the inbound message and
+     * everything after it is a plain send: the reply-to relation names which message is being
+     * answered, and one of them says it — repeating it per message and per chunk stacks quote
+     * headers over the whole conversation.
+     *
+     * A binding with `renderMarkdown` set relays the model's Markdown as formatting rather
+     * than as characters. The bridge only carries the REQUEST: the conversion is the
+     * connector's, because what a channel can show and what it does with a rendering the
+     * channel refuses are both channel-shaped (see MessagingSendOptions). What is not
+     * channel-shaped is where a reply too long for one message may be cut, and that is why the
+     * chunker changes with the flag — a cut through a code fence or an emphasis run costs the
+     * construct everywhere, and on a strict parser costs the whole message's formatting.
+     */
+    private deliverReply;
+    /**
+     * Sends the files THIS RUN produced and its reply mentioned, after its text.
+     *
+     * `replyText` is what the run actually SENT, not everything it said: a binding with
+     * `finalReplyOnly` set delivered one message, so that message is the whole of what this
+     * scans (see onTaskState). A file named only in a held-back working note has nothing in
+     * the chat to explain its arrival.
+     *
+     * `at` is where those words went, for the one caller whose text is not addressed to the live
+     * chat (again the held reply). Files follow their words: a picture landing in a forum topic
+     * where nothing named it is the same defect as one arriving unmentioned.
+     *
+     * Two filters, and both are load-bearing. The reply having said the name is what picks
+     * the one output that was the point out of the dozen a run writes. The file being newer
+     * than the run's start is what keeps that from becoming an exfiltration primitive: the
+     * reply is steerable by whoever is in the chat, and on a mention-only rule a group member
+     * who asks "what is in secrets.json?" gets the file uploaded by the very refusal that
+     * declined to paste it. Containment (the Workspace and nothing narrower) lives in the
+     * file service either way — see MessagingWorkspaceFiles.
+     *
+     * A file the run did not write is dropped SILENTLY, and so is a name matching no file at
+     * all: the rule reads prose, so a reply that mentions the config it read — or describes a
+     * `hello-world.md` it never wrote — is the ordinary case, and announcing those puts an
+     * error-shaped line under correct answers. Both are logged instead. What IS recorded is a
+     * file that exists and still did not go out — over a ceiling, past the count cap, or
+     * refused on the way: the reply promised something that then did not arrive, so it is filed
+     * under the Session's Project, once the batch is done, in one record per cause naming every
+     * file it held back (see messagingFilesNotSentRecords). None of it is posted into the chat,
+     * which carries the reply and its files and nothing about the ones that stayed behind.
+     *
+     * Always plain sends, never a threaded reply: a run that mentions a file has by
+     * definition already sent the text that mentions it, and that message took the group's
+     * one reply-to. Nothing here throws — a batch that fails is recorded, and a single file
+     * that fails does not stop the ones behind it.
+     */
+    private deliverFiles;
+    /**
+     * One mirrored file: read under the outer ceiling, then sent as a picture or an attachment.
+     * Resolves null once the file went out. A file over the ceiling for its kind is not sent and
+     * resolves to that ceiling instead; a read or a send the channel refused throws. The caller
+     * records both (see messagingFilesNotSentRecords).
+     */
+    private deliverOneFile;
+    /** One-line notice (approval waiting) to the last known chat; silent before one exists. */
+    private deliverNotice;
+    /**
+     * Where this entry's outbound traffic goes, with a client for it: null when no chat is
+     * known yet (nothing mirrors before the first inbound message) and null when the binding
+     * or its client could not be read at all, which is recorded like the send it stands in for.
+     */
+    private sendTarget;
+    /**
+     * Whether this entry still holds its Session's connection — asked at the head of every
+     * step of the send chain, the way `observe` asks it of every event.
+     *
+     * The chain outlives what fed it. A run's last messages and the files behind them are
+     * queued on it, and `stop()` — App dispose, a hot swap — drops the entry and takes the
+     * database with it while they are still waiting their turn. A step that ran anyway would
+     * read a closed database, and it would fail again inside its own error recording, leaving
+     * the chain rejected with nothing left to catch it.
+     */
+    private live;
+    /** The pace between a per-line reply's messages; zero (tests) waits for nothing. */
+    private pace;
+}
+declare const MessagingTaskRunner_base: (abstract new () => MessagingTaskRunnerShape) & (<C>(target: C, context: ClassDecoratorContext) => C);
+/** What the bridge needs of the session runtime — declared at the consumer. */
+declare abstract class MessagingTaskRunner extends MessagingTaskRunner_base {
+}
+declare const Messaging_base: (abstract new () => Pick<MessagingBridge, "sync" | "start" | "stop" | "statusOf" | "unbind" | "unbindSession" | "testCredentials" | "sendTestMessage">) & (<C>(target: C, context: ClassDecoratorContext) => C);
+/** The chat-channel bridge: bindings, delivery, status. */
+declare abstract class Messaging extends Messaging_base {
+}
+interface MessagingSlots {
+    /** A channel connector: which channel it speaks (static), and the connector (code). */
+    connectors: Slot<{
+        channel: "feishu" | "telegram" | "qq" | "wechat";
+    }, MessagingChannelConnector>;
+}
+
+/** A settings group as a module declares it: a configuration, and where the page draws it. */
+interface SettingsGroupDecl extends PluginConfiguration {
+    /** Another group's name (its contribution id): this one is drawn inside that card and saved with it. */
+    parent?: string;
+    /** Position among the groups: lower first (absent = 100), then declaration order. */
+    order?: number;
+}
+/** What a module reads: the group it declared, and a watch on it. */
+declare abstract class PluginConfig {
+    /** The stored values merged onto the declared defaults; `{}` for a name no group answers to. */
+    abstract get(name: string): Record<string, unknown>;
+    /** Fires with the new document after every save of `name`; returns the unsubscribe. */
+    abstract watch(name: string, cb: (values: Record<string, unknown>) => void): () => void;
+    /** Whether anything was ever saved under `name` — what tells a default from a choice. */
+    abstract saved(name: string): boolean;
+    /** The configuration `name` was declared with (what `resolveTable` reads a table by); undefined for none. */
+    abstract schema(name: string): PluginConfiguration | undefined;
+}
+interface PluginConfigSlots {
+    /** A settings group, as data: its id is its name, the data its configuration. */
+    groups: Slot<SettingsGroupDecl>;
+}
+
+/** The assembled business surface: one request in, one response (or a decline) out. */
+declare abstract class Http {
+    abstract fetch(request: Opaque<"Request", Request>): Promise<Opaque<"Response", Response>>;
+}
+interface HttpSlots {
+    /**
+     * A route group. `auth: "user"` mounts it behind the cookie gate, `"none"` in front of
+     * it; `order` is the mount position (a stable number, since Hono matches in order). The
+     * code half is the group's Hono app.
+     */
+    routes: Slot<{
+        prefix: string;
+        auth: "user" | "none";
+        order: number;
+    }, Opaque<"Hono", Hono<AppEnv>>>;
+}
+
+/**
+ * GET /api/contributions — the web slots' contributions, as data. What a pushed platform
+ * or an installed plugin adds to the web app arrives here; the app merges it with its
+ * own module.json and renders what it has a renderer for.
+ */
+
+/**
+ * The frontend's slots, declared on the SERVER so a server module (or a plugin) can
+ * contribute a page, an Agent settings tab or a Session tab as manifest data. The web
+ * app reads them back through GET /api/contributions and renders the ones whose
+ * renderer it knows: a `builtin` name from its own registry, or an `iframe`. No code
+ * crosses this boundary — only data.
+ */
+declare abstract class WebShell {
+    /** Every contribution to the web slots, by slot, in module order. */
+    abstract contributions(): ContributionsResponse;
+}
+interface WebShellSlots {
+    /** A page: its route, whether it sits in the main nav, whether it is admin-only. */
+    pages: {
+        key: string;
+        path: string;
+        nav: "main" | "none";
+        admin: boolean;
+        renderer: RendererRef;
+    };
+    /** A tab on the Agent settings page. */
+    agentTabs: {
+        key: string;
+        order: number;
+        renderer: RendererRef;
+    };
+    /**
+     * A tab beside a Session's chat. A workflow contributes here too, from its own tree, where
+     * the host publishes this slot under this module's name and scopes the tab to its Agent.
+     */
+    sessionTabs: {
+        key: string;
+        title: string;
+        titleZh?: string;
+        renderer: {
+            builtin: string;
+        } | {
+            iframe: {
+                src: string;
+            };
+        };
+    };
+}
+
+export { AgentConfigService, AgentService, Http, type HttpSlots, Messaging, type MessagingSlots, PluginConfig, type PluginConfigSlots, PluginConfiguration, Sandbox, type SandboxSlots, SessionServiceIface, Sessions, type SettingsGroupDecl, Terminals, WebShell, type WebShellSlots };