A local-first multi-agent app development platform, built on PenguinHarness
/**
* Active Session runtime.
*
* Responsibilities:
* - get-or-resume-or-heal: use it directly on an active-table hit; with a Trace,
* recover via `agent.resumeSession`; a stale Session that was created but never run
* and survived a process restart (no Trace) **self-heals** — recreated via
* createSession using the index row's workspace/modelId, yielding a new session_id
* and updating the index's primary key; the Task response body always returns the
* current actual id;
* - Credential effectiveness: a Project's models/credentials change bumps every affected
* Agent's config generation (invalidateProjectRuntimes); runtimes built earlier are
* discarded on their next idle access and re-resumed, so the next Task runs with the
* new api_key / base_url. Agent State changes (vault, AGENTS.md, tools, …) take no
* such shortcut: core assembles them into the next model context — at the Session's
* next compaction — exactly as the CLI does, so a running context never changes;
* - Per-Session mutual exclusion: only one Task/compaction/model switch may be in
* progress at a time;
* - run/compact/switch drive: consumes the output stream in the background, publishing
* each message to the SSE channel and handing it to usage-recorder for persistence;
* on completion (including errors) resets to idle and pushes a `task_state` server
* event. A model switch (startSwitch) is a compaction whose next context opens on
* another model: the entry's (provider, modelId) — the pair usage is attributed to —
* and the index row follow the runtime, moving as the new context's session_meta passes
* through the drive;
* - Approval registration and interrupt convergence: each approval decision re-reads
* approval_mode from the DB (takes effect immediately); an interrupt first
* converges pending approvals to deny, then aborts. An organization's sessions have
* nobody to ask, so a call their mode would hand to a person is denied at once
* (see entryApprove).
*
* The underlying implementation of get-or-resume-or-heal is injected via
* `SessionLoader`: production uses the core SDK (createCoreSessionLoader), tests inject
* a fake Session (issuing no real LLM requests).
*/
import { randomUUID } from "node:crypto";
import fs from "node:fs/promises";
import path from "node:path";
import {
createAgent,
findLatestTraceFile,
isHookContinue,
isHookInput,
isSessionMeta,
ModelSwitchRefusedError,
normalizeSessionSource,
parseUserSteeringText,
tracesDir,
userText,
} from "@adelie/core";
import type {
ApproveFn,
BackgroundCommandInfo,
BackgroundSubagentInfo,
CompactAvailability,
ControlEnvContext,
AgentAssembly,
OmniMessage,
ProxyEnvPolicy,
SpawnConfiner,
SessionMetaPayload,
SessionTitleResult,
StopReason,
SubagentMessageOptions,
SubagentMessageOutcome,
SwitchFailurePolicy,
TextPayload,
ThinkingLevelName,
ToolDetachResult,
} from "@adelie/core";
import type {
ModelRefDto,
PendingFollowUpInfo,
PendingSteeringInfo,
ServerEvent,
SessionBackgroundTasks,
SessionStatus,
} from "../api/types.js";
import type { RecallableFile } from "../services/task-attachments.js";
import { cliShimDir } from "../services/cli-shim.js";
import { HttpError, isMissingCredential, modelCredentialMissing } from "../http/errors.js";
import type { SessionRow } from "../db/repos/sessions.js";
import { ApprovalRegistry, makeApprove } from "./approvals.js";
import { goalOutcomeOf, goalProgressOf } from "./goal-events.js";
import type { PendingApproval } from "./approvals.js";
import type { ChannelHub } from "./channel.js";
import type { ErrorSink } from "./error-recorder.js";
import { LiveTailTracker } from "./live-tail.js";
import { unrunSource } from "./session-sources.js";
import { StreamErrorWatcher } from "./stream-error-watcher.js";
import type { TitleNotifier } from "./title-generator.js";
import type { UsageContext } from "./usage-recorder.js";
import { Component, Interface, Module, Provide, Use } from "@adelie/core/kernel";
import type { SessionService as SessionServiceImpl } from "../services/session-service.js";
import type { ClassCtx, Opaque } from "@adelie/core/kernel";
import { Sandbox, SandboxModule } from "../sandbox/service.js";
import { SANDBOX_GROUP } from "../sandbox/settings-store.js";
import { sandboxEnabledOf, sandboxPresetsOf, sandboxStartOf } from "../sandbox/settings-policy.js";
import { PluginConfig } from "../plugin/config.js";
import { SessionService } from "../services/session-service.js";
import { ModelScopeAuth } from "../services/modelscope-auth-service.js";
import { TitleGenerator } from "./title-generator.js";
import { loopbackHostRoles } from "../services/preview-token.js";
import { mergedNoProxy } from "../net/proxy.js";
import type { SandboxService } from "../sandbox/service.js";
import type { AuthState, Channels, Clock, Config, Log } from "../hmr/capabilities.js";
import type { ProjectConfigStore, ProjectEvents } from "../mechanisms/projects.js";
import type { SessionIndex, SessionOrigins } from "../mechanisms/sessions.js";
import type { Errors, UsageRecording } from "../mechanisms/observability.js";
import type { TraceIndex, TraceIndexStore } from "../mechanisms/traces.js";
import type { Settings } from "../mechanisms/settings.js";
import type { MessagingBindings } from "../mechanisms/messaging.js";
import type { OrgCache } from "../mechanisms/organization.js";
import { enabledMessagingChannel } from "./messaging/enabled-channel.js";
import { MODELSCOPE_PROVIDER_ID } from "@adelie/core/model-catalog";
/**
* 409 for when there's nothing to compact: give the specific reason rather than a
* one-size-fits-none message.
*
* Each reason carries its **own code**, not just its own message. Clients localize by code
* (the Web's `apiErrorText` looks the code up in a table and falls back to the raw English
* message), so one shared code leaves exactly two bad options: flatten three unrelated
* explanations into one vague sentence, or let English prose reach a non-English UI. One code
* per sub-reason is how the rest of this API splits a refusal — `dir_not_absolute` /
* `dir_not_found` / `not_a_dir` are three codes for three ways of rejecting one directory.
*/
function compactUnavailable(why: Exclude<CompactAvailability, "ok">): HttpError {
const reasons: Record<typeof why, { code: string; message: string }> = {
unsupported: {
code: "compaction_not_configured",
message: "This Agent does not have context compaction configured.",
},
empty: {
code: "nothing_to_compact",
message: "The current context has nothing to compact (no completed conversation turns yet).",
},
just_compacted: {
code: "already_compacted",
message:
"The context was just compacted and there is no new conversation since; no need to compact again.",
},
};
const { code, message } = reasons[why];
return new HttpError(409, code, message);
}
/**
* Core's refusal of a model switch — a typed `ModelSwitchRefusedError`, thrown before its
* first event (see `Session.switchModel`) — as the 409 the HTTP contract names for it: each
* reason is its own code (see `SessionSwitchModelRequest`). A missing credential reads as the
* remedy the Web App can act on rather than the loader's own wording. Anything else core
* throws is not a refusal but a failure — an Agent State that no longer parses, a bootstrap
* that broke — and is rethrown, so it reaches the 500 path and its logging instead of being
* dressed up as a target problem.
*/
function switchRefusal(err: unknown, ref: ModelRefDto): HttpError {
if (!(err instanceof ModelSwitchRefusedError)) throw err;
const message =
err.reason === "model_unavailable" && isMissingCredential(err)
? `Model ${ref.modelId} has no API key yet. Configure it on the Models page first.`
: err.message;
return new HttpError(409, err.reason, message);
}
/** A stream whose head was already pulled, whole again: `head`, then the rest of `rest`. */
async function* resumeFrom<T>(head: T, rest: AsyncGenerator<T, unknown>): AsyncGenerator<T> {
yield head;
yield* rest;
}
/** The model a runtime Session reports itself on, or null for one that reports none (test fakes). */
function runtimeModelOf(session: RuntimeSession): ModelRefDto | null {
const { provider, modelId } = session;
if (provider === undefined || modelId === undefined) return null;
return { provider, modelId };
}
/** Minimal interface for a runtime Session (satisfied by core Session; tests may inject a fake implementation). */
export 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".
*
* `onCompactionFailure` is core's own field of the same name (`"discard"` drops the context
* and switches anyway); the manager passes it straight through and never reads it.
*/
switchModel?(opts: {
provider: string;
modelId: string;
signal: AbortSignal;
onCompactionFailure?: SwitchFailurePolicy;
}): 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. */
export 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>;
}
/**
* Production loader: the core SDK's resumeSession / createSession. `sources` (when given)
* lets the no-Trace self-heal rebuild re-record a known origin into the fresh session_meta;
* with no registry entry (e.g. the process restarted and no Trace was ever written) the
* rebuilt Session is unsourced — session_meta is the single source of truth, and none survived.
* `opts.proxyEnv` threads the admin proxy settings into core (a live getter returning the
* agent-command-subprocess policy: strip the proxy variables, inject the explicit proxy
* address, or null = pass the environment through). `opts.controlEnv` threads the
* harness-control injection the same way (the server's API URL/token plus the Session's
* coordinates; core evaluates it per Session — see CreateAgentOptions.controlEnv), and
* `opts.pathPrepend` the directories every command of a resumed Session finds at the front
* of its PATH (the harness's own CLI shim — see CreateAgentOptions.pathPrepend).
*/
export function createCoreSessionLoader(
root: string,
sources?: SessionOrigins,
opts: {
proxyEnv?: () => ProxyEnvPolicy | null;
controlEnv?: (ctx: ControlEnvContext) => Record<string, string>;
pathPrepend?: () => string[];
confineSpawn?: (ctx: ControlEnvContext) => SpawnConfiner | null;
assembly?: AgentAssembly;
} = {},
): SessionLoader {
return {
async load(row: SessionRow): Promise<RuntimeSession> {
const agent = await createAgent({
root,
projectId: row.projectId,
agentId: row.agentId,
...(opts.proxyEnv ? { proxyEnv: opts.proxyEnv } : {}),
...(opts.controlEnv ? { controlEnv: opts.controlEnv } : {}),
...(opts.pathPrepend ? { pathPrepend: opts.pathPrepend } : {}),
...(opts.confineSpawn ? { confineSpawn: opts.confineSpawn } : {}),
...(opts.assembly ? { assembly: opts.assembly } : {}),
});
const located = await findLatestTraceFile(
tracesDir(root, row.projectId, row.agentId),
row.sessionId,
);
if (located) {
// With a Trace: rebuild via "Session Recovery" (history injected via setHistory,
// carrying over any residual state).
// core's recognizable recovery failures (Workspace deleted / Model removed from
// config / Trace missing session_meta, etc.) are converged to 409, preserving
// the original message rather than bubbling up as 500.
try {
const session = await agent.resumeSession({ sessionId: row.sessionId });
// The row's stored level — the knob position the user last chose — restored onto
// the runtime as a plain assignment: it rides the resumed Session's requests.
if (row.thinkingLevel) session.thinkingLevel = row.thinkingLevel;
return session;
} catch (err) {
// The credential key was deleted after the Session was created: only caught
// here at recovery time; give the same actionable message.
if (isMissingCredential(err)) throw modelCredentialMissing(row.modelId);
throw toUnrecoverableError(err);
}
}
// No Trace (created but never run, and the process has restarted since): self-heal
// rebuild. A missing Workspace → 409.
try {
const stat = await fs.stat(row.workspace);
if (!stat.isDirectory()) throw new Error("not a directory");
} catch {
throw new HttpError(
409,
"workspace_missing",
`This Session's Workspace no longer exists: ${row.workspace}, so it cannot continue. Create a new Session.`,
);
}
// The source this process recorded at creation, else the one the row stands for: the
// organization runtime's are `company`, the Agent API's `api` (unrunSource), the list's
// reading of the same row.
const knownSource = sources?.get(row.sessionId) ?? unrunSource(row.client);
try {
return await agent.createSession({
workspaceDir: row.workspace,
modelId: row.modelId,
provider: row.provider,
// The rebuilt Session records that source in its fresh session_meta (an unknown one
// is core's default, `user`), and starts its first context at the row's pinned level.
...(knownSource !== undefined ? { source: knownSource } : {}),
...(row.thinkingLevel ? { thinkingLevel: row.thinkingLevel } : {}),
});
} catch (err) {
if (isMissingCredential(err)) throw modelCredentialMissing(row.modelId);
throw toUnrecoverableError(err);
}
},
};
}
/** A plain Error thrown by core recovery/self-heal rebuild → 409 (preserving the original, actionable message). */
function toUnrecoverableError(err: unknown): HttpError {
if (err instanceof HttpError) return err;
return new HttpError(
409,
"session_unrecoverable",
err instanceof Error ? err.message : String(err),
);
}
export interface UsageRecorderLike {
record(ctx: UsageContext, msg: OmniMessage): Promise<void>;
}
export 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;
}
/**
* Whether a Task's input came from a person: every text payload either carries no sender or
* `sender: "user"`. A harness-injected turn (`"server"`, `"harness"`, `"parent_agent"`) on any
* message makes the whole input non-human — the org scheduler's trigger and a subagent's
* prompt both arrive that way.
*/
export function isHumanInput(input: readonly OmniMessage[]): boolean {
return input.every((m) => {
const p = m.payload as { sender?: string };
return p.sender === undefined || p.sender === "user";
});
}
/**
* 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`, `images` and `videos` 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.
* `videos` holds the inline ones only — a video the Session's model cannot take was turned
* into a file before it ever got here (see the task route).
*/
export interface RecallStore {
text: string;
images: string[];
videos: string[];
files: RecallableFile[];
}
/** One queued follow-up task (`queueIfBusy`): the task input, held until the session is idle. */
interface QueuedFollowUp {
/** Recall handle (PendingFollowUpInfo.id), assigned at queue time. */
id: string;
input: OmniMessage[];
/**
* Original content for recall, and the content `task_state` shows on the queued line.
* Always present: a caller that knows more than the input carries (the HTTP route, which
* also knows where the file attachments landed on disk) supplies it, and every other
* queueing path gets it derived from the input — what can be recalled must not depend on
* which door the message came through.
*/
recall: RecallStore;
}
/** One undelivered steering entry: the display info broadcast on task_state, plus what a recall needs — the exact input list core queued (its unsteer handle) and the original content. */
interface PendingSteeringEntry {
info: PendingSteeringInfo;
input: OmniMessage[];
recall: RecallStore;
}
/** Active-table entry: a loaded runtime Session plus its running state. */
interface RuntimeEntry {
sessionId: string;
projectId: string;
agentId: string;
/**
* The Session's current model (provider group paired with modelId): what the next drive
* attributes usage to. The row's pair, kept in step with the runtime's own answer (see
* `syncEntryModel`) — at load, and whenever a model switch moves it.
*/
provider: string;
modelId: string;
session: RuntimeSession;
status: SessionStatus;
approvals: ApprovalRegistry;
abort: AbortController | null;
/** The in-flight drive Promise (awaited during graceful shutdown). */
running: Promise<void> | null;
/**
* Agent config generation this runtime was built under (see
* invalidateAgentRuntimes): once it falls behind the Agent's current generation,
* the entry is discarded on its next idle access and re-resumed via the loader.
*/
generation: number;
/**
* Queued follow-up tasks (`queueIfBusy`): task inputs accepted while a Task/compaction was
* in progress, auto-started one at a time (in order) once the session returns to idle —
* ordinary tasks with normal semantics, unlike the mid-run steering queue.
* Deliberately NOT discarded on abort: they are future tasks the user explicitly queued.
*/
followUps: QueuedFollowUp[];
/**
* The running Task's input messages, held from launch until the run ends. The engine
* writes these exact envelopes to the Trace only after the session bootstrap (MCP
* connect + discovery on the first run), so a history read during that window would
* miss the user's own message — and the draft flow subscribes to the stream only after
* the input publish, so the live channel cannot backfill it either. GET /messages
* appends the ones the Trace has not caught up to yet (exact-envelope dedup).
*/
pendingInputs: OmniMessage[];
/**
* The running Task's streamed bootstrap records (mcp_connect begin/end,
* tool_list_ready), held until the run ends. Their Trace writes are deferred by the
* engine until after the input lands (turn attribution), and the draft flow subscribes
* only after they were published — so a history rebuild during the MCP connect would
* otherwise show nothing at all (a silent blank while a slow server times out).
* GET /messages appends whichever of them the Trace has not caught up to.
*/
pendingBootstrap: OmniMessage[];
/**
* Steering messages queued on core but not yet delivered to the model — a display mirror
* of core's steering queue (same FIFO order), so the composer's "steering queued" hint and
* its content survive reloads: pushed on `steer`, shifted as each `[user_steering]`
* message appears on the drive stream, dropped wholesale when the run exits (core
* discards undelivered steering on abort/completion). The `info` halves are broadcast on
* every `task_state`; the rest is the recall handle (see recallSteering).
*/
pendingSteering: PendingSteeringEntry[];
/**
* Steering the run ended without ever delivering — handed back to the user instead of
* discarded (#287 follow-up). An interrupt mid-tool-call is the ordinary way to get here:
* core drops its queue when the run exits, so the message would otherwise vanish with the
* text the user had already typed.
*
* Entries move here from `pendingSteering` when the run exits and stay recallable by the
* same handle, so the composer pulls them back into its draft (auto-recall on observing
* them, a reload included). They are deliberately NOT cleared when the next run starts:
* the message was never delivered whatever happens later, and dropping it there would
* reintroduce exactly the loss this list exists to prevent. Only a recall — or the entry's
* idle eviction — removes one.
*/
returnedSteering: PendingSteeringEntry[];
/** Timestamp of last activity (refreshed on load / status flip / drive completion / background-task change), used for idle-eviction checks. */
lastActivityMs: number;
/**
* Background-task counts as last read from the runtime — at entry creation, then on every
* background-state ping. The baseline `session_background` is published against: a ping
* that leaves the counts where they were (a foreground-window child settling, an exited
* process being removed from the list) publishes nothing.
*/
backgroundTasks: SessionBackgroundTasks;
}
/** Active-table idle eviction: same convention as the SSE channel (an idle entry with no activity for 30 minutes releases its memory). */
const ENTRY_IDLE_MS = 30 * 60 * 1000;
const ENTRY_SWEEP_INTERVAL_MS = 60 * 1000;
/**
* Queue depth cap per session. Every queued follow-up is a full model run waiting to
* happen, and the queue has no other brake: org triggers always ask to queue
* (queueIfBusy), so a mention storm or an @all fan-out against a busy desk would grow it
* without bound and then replay every entry as a model call. The cap refuses the overflow
* loudly instead (429 queue_full): the org trigger path records org_dispatch_failed, and
* the HTTP caller sees the refusal directly.
*/
export const FOLLOW_UP_QUEUE_LIMIT = 16;
/** Composite Agent key (used as a Set key, avoiding projectId/agentId concatenation ambiguity). */
function agentKey(projectId: string, agentId: string): string {
return `${projectId}\0${agentId}`;
}
/**
* The runtime's background-task counts, read live from its registries: command sessions
* whose process is still running (exited rows stay listed until removed and do not count),
* and subagent sessions that hold a `subagent_id` — promoted to the background by a yield
* window expiring or a `run_in_background` launch — and are mid-round. A child still inside
* a foreground collect window has no id yet and is the running Task's own work, not
* background work.
*/
function backgroundTaskCounts(session: RuntimeSession): SessionBackgroundTasks {
const processes = session.listBackgroundCommands?.().filter((p) => p.running).length ?? 0;
const subagents =
session.listBackgroundSubagents?.().filter((s) => s.running && s.subagentId !== null).length ??
0;
return { processes, subagents };
}
/** The `task_state` display info of one queued follow-up (see PendingFollowUpInfo). */
function followUpInfo(f: QueuedFollowUp): PendingFollowUpInfo {
return {
id: f.id,
text: f.recall.text,
images: f.recall.images.length,
videos: f.recall.videos.length,
files: f.recall.files.length,
};
}
/**
* The recall store of a queued input whose caller supplied none: everything recallable is
* already in the input itself — the user's text and the inline image / video URLs, the only
* shapes a task input is ever built from.
*
* `files` is empty because the path a written attachment landed on is known only to
* whoever wrote it. A caller that wrote some therefore builds its store on top of this one
* instead of leaving it to be derived, and passes the input as it stood BEFORE the
* `[attached file: …]` lines were folded in — derived from the folded input, `text` would
* hand a recall back a raw scratchpad path in place of the chip it was meant to restore.
*/
export function recallStoreOf(input: OmniMessage[]): RecallStore {
const text = input
.filter(isPlainText("user"))
.map((m) => m.payload.text)
.join("\n");
const images: string[] = [];
const videos: string[] = [];
for (const msg of input) {
const payload = msg.payload as { type?: string; image_url?: unknown; video_url?: unknown };
if (msg.type !== "model_msg") continue;
if (payload.type === "image_url" && typeof payload.image_url === "string") {
images.push(payload.image_url);
} else if (payload.type === "video_url" && typeof payload.video_url === "string") {
videos.push(payload.video_url);
}
}
return { text, images, videos, files: [] };
}
/** If msg is a run_subagent tool call carrying a `prompt`, return its id and prompt (for use as the subagent's title); otherwise null. */
/** Whether this main-stream message is a delivered `[user_steering]` user text (one per queued steering entry, see core's steeringMessages). */
function isDeliveredSteering(msg: OmniMessage): boolean {
const p = msg.payload as { type?: string; role?: string; text?: string };
if (msg.type !== "model_msg" || p.type !== "text" || p.role !== "user") return false;
return typeof p.text === "string" && parseUserSteeringText(p.text) !== null;
}
function runSubagentCall(msg: OmniMessage): { toolCallId: string; prompt: string } | null {
const p = msg.payload as {
type?: string;
name?: string;
arguments?: string;
tool_call_id?: string;
};
if (msg.type !== "model_msg" || p.type !== "tool_call" || p.name !== "run_subagent") return null;
if (typeof p.arguments !== "string" || typeof p.tool_call_id !== "string") return null;
try {
const args = JSON.parse(p.arguments) as { prompt?: unknown };
if (typeof args.prompt !== "string" || !args.prompt.trim()) return null;
return { toolCallId: p.tool_call_id, prompt: args.prompt };
} catch {
return null; // Arguments were truncated/malformed: this call is doomed, no subagent will result
}
}
/** The denied tool_call_id (approval_decision with decision ≠ allow); otherwise null. */
function deniedToolCallId(msg: OmniMessage): string | null {
const p = msg.payload as { type?: string; decision?: string; tool_call_id?: string };
if (msg.type !== "event_msg" || p.type !== "approval_decision") return null;
if (p.decision === "allow" || typeof p.tool_call_id !== "string") return null;
return p.tool_call_id;
}
/** The tool_call_id of a parent-level tool call that has settled (a complete tool_call_output); otherwise null. */
function settledToolCallId(msg: OmniMessage): string | null {
const p = msg.payload as { type?: string; tool_call_id?: string };
if (msg.type !== "model_msg" || p.type !== "tool_call_output") return null;
return typeof p.tool_call_id === "string" ? p.tool_call_id : null;
}
/** A subagent registered during this run, plus its title material. */
interface ChildSession {
sessionId: string;
agentId: string;
/** The prompt of the run_subagent call that spawned it (user material for title generation, and the fallback title). */
prompt: string;
}
/** Predicate for a plain-text message on the main session (no origin): title material is drawn only from user/model text. */
function isPlainText(role: "user" | "assistant") {
return (msg: OmniMessage): msg is OmniMessage<TextPayload> => {
const payload = msg.payload as { type?: string; role?: string };
return (
msg.type === "model_msg" &&
payload.type === "text" &&
payload.role === role &&
(!msg.origin || msg.origin.length === 0)
);
};
}
export class SessionManager {
private readonly entries = new Map<string, RuntimeEntry>();
/**
* 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 = new Map<string, string>();
/** The Session whose policy governs `sessionId`: its root for a subagent, else itself. */
rootSessionOf(sessionId: string): string {
return this.childRoots.get(sessionId) ?? sessionId;
}
/** Per-Session mutex (serializes get-or-load and status flips); auto-cleaned once the chain drains. */
private readonly locks = new Map<string, Promise<unknown>>();
private readonly log: (line: string) => void;
/** Graceful-shutdown flag: once set, new Tasks/compactions are rejected (503). */
private closed = false;
/** Agents currently being deleted (key = agentKey): new Tasks/compactions are always rejected with 409 during this window. */
private readonly deletingAgents = new Set<string>();
/** Sessions currently being deleted (guards against the entry/Trace file being rebuilt and reviving it inside the deletion race window). */
private readonly deletingSessions = new Set<string>();
/** Per-Agent config generation (key = agentKey), bumped by invalidateAgentRuntimes when a Project's credentials change. */
private readonly agentGenerations = new Map<string, number>();
/** Open streaming fragments of running sessions (fed by drive, served to GET /messages; see live-tail.ts). */
private readonly liveTail = new LiveTailTracker();
private readonly sweepTimer: NodeJS.Timeout;
/** Clock for persisted timestamps (see SessionManagerDeps.now); wall clock unless injected. */
private readonly now: () => Date;
constructor(private readonly deps: SessionManagerDeps) {
this.log = deps.log ?? ((line) => console.error(line));
this.now = deps.now ?? (() => new Date());
this.sweepTimer = setInterval(() => this.sweepIdle(), ENTRY_SWEEP_INTERVAL_MS);
this.sweepTimer.unref?.();
}
// —— Query surface (used by Session listing / Agent active-count / SSE subscription replay) ——
statusOf(sessionId: string): SessionStatus {
return this.entries.get(sessionId)?.status ?? "idle";
}
/**
* Every Session this process holds in a live state — running or compacting — across all
* Projects and Agents. `statusOf` answers one id at a time, and a Session nobody is looking
* at has no row in any client's list; the account menu's "what is running right now" asks
* the whole table instead, which is a walk over the entries this process already keeps.
*/
liveSessions(): Array<{
sessionId: string;
projectId: string;
agentId: string;
status: SessionStatus;
}> {
const out: Array<{
sessionId: string;
projectId: string;
agentId: string;
status: SessionStatus;
}> = [];
for (const e of this.entries.values()) {
if (e.status === "idle") continue;
out.push({
sessionId: e.sessionId,
projectId: e.projectId,
agentId: e.agentId,
status: e.status,
});
}
return out;
}
pendingApprovalCount(sessionId: string): number {
return this.entries.get(sessionId)?.approvals.size ?? 0;
}
pendingApprovals(sessionId: string): PendingApproval[] {
return this.entries.get(sessionId)?.approvals.list() ?? [];
}
/** Number of queued follow-up tasks (`queueIfBusy`) awaiting auto-start. */
pendingFollowUpCount(sessionId: string): number {
return this.entries.get(sessionId)?.followUps.length ?? 0;
}
/**
* 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 {
const entry = this.entries.get(sessionId);
if (!entry) return undefined;
const counts = backgroundTaskCounts(entry.session);
return counts.processes > 0 || counts.subagents > 0 ? counts : undefined;
}
/** Steering messages queued but not yet delivered to the model (display mirror; see RuntimeEntry.pendingSteering). */
pendingSteeringOf(sessionId: string): PendingSteeringInfo[] {
return (this.entries.get(sessionId)?.pendingSteering ?? []).map((p) => p.info);
}
/** Steering a finished run never delivered, waiting for the composer to take it back (see RuntimeEntry.returnedSteering). */
returnedSteeringOf(sessionId: string): PendingSteeringInfo[] {
return (this.entries.get(sessionId)?.returnedSteering ?? []).map((p) => p.info);
}
/**
* 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[] {
return this.entries.get(sessionId)?.session.listBackgroundSubagents?.() ?? [];
}
/**
* 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.
*/
async sendToSubagent(
sessionId: string,
childSessionId: string,
messages: OmniMessage[],
): Promise<SubagentMessageOutcome> {
const entry = await this.ensureEntry(sessionId);
entry.lastActivityMs = Date.now();
const childRow = this.deps.sessions.findById(childSessionId);
const resume =
childRow && childRow.projectId === entry.projectId
? { agentId: childRow.agentId }
: undefined;
return (
(await entry.session.sendToBackgroundSubagent?.(childSessionId, messages, {
...(resume ? { resume } : {}),
})) ?? "gone"
);
}
/**
* 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 {
const session = this.entries.get(sessionId)?.session;
if (session) {
session.thinkingLevel = level;
return;
}
for (const entry of this.entries.values()) {
if (entry.session.setBackgroundSubagentThinkingLevel?.(sessionId, level)) return;
}
}
/** 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 {
const entry = this.entries.get(sessionId);
if (!entry) return false;
entry.lastActivityMs = Date.now();
return entry.session.abortBackgroundSubagentRun?.(childSessionId) ?? false;
}
/** Queued follow-up tasks awaiting auto-start, as their display/recall info (id + content summary). */
pendingFollowUpsOf(sessionId: string): PendingFollowUpInfo[] {
return (this.entries.get(sessionId)?.followUps ?? []).map(followUpInfo);
}
/**
* 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[] {
return this.liveTail.fragments(sessionId);
}
/**
* 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[] {
return this.entries.get(sessionId)?.pendingInputs ?? [];
}
/** The running Task's streamed bootstrap records (see RuntimeEntry.pendingBootstrap); empty when idle. */
pendingBootstrap(sessionId: string): OmniMessage[] {
return this.entries.get(sessionId)?.pendingBootstrap ?? [];
}
/** Number of Sessions for this Agent that are currently running / compacting. */
activeCountForAgent(projectId: string, agentId: string): number {
let n = 0;
for (const e of this.entries.values()) {
if (e.projectId === projectId && e.agentId === agentId && e.status !== "idle") n++;
}
return n;
}
/** 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 {
const entry: RuntimeEntry = {
sessionId: row.sessionId,
projectId: row.projectId,
agentId: row.agentId,
provider: row.provider,
modelId: row.modelId,
session,
status: "idle",
approvals: new ApprovalRegistry(() => this.publishApprovals(entry)),
abort: null,
running: null,
generation: this.generationOf(row.projectId, row.agentId),
followUps: [],
pendingInputs: [],
pendingBootstrap: [],
pendingSteering: [],
returnedSteering: [],
lastActivityMs: Date.now(),
backgroundTasks: backgroundTaskCounts(session),
};
this.entries.set(row.sessionId, entry);
// Same wiring as ensureEntry: adopt IS the entry path for a session created in this
// process (POST /sessions), and a listener registered only on the loader path left
// freshly created sessions unable to deliver idle-arrival completion reports.
this.registerNoticeListener(row.sessionId, session);
}
/**
* 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(sessionId: string, session: RuntimeSession): void {
session.onBackgroundNotice?.(() => void this.startBackgroundNoticeTask(sessionId));
session.onBackgroundMessage?.((msg) => this.forwardBackgroundMessage(sessionId, msg));
session.onSubagentState?.(() => {
const entry = this.entries.get(sessionId);
if (entry) this.publishState(entry, entry.status);
});
session.onBackgroundState?.(() => this.publishBackgroundTasks(sessionId));
// The entry-lifetime approve doubles as the children's fallback approval sink: a child
// approval with no window and no background-launch standing sink escalates to the user
// (SSE approval_request) instead of parking until the model's next poll — the parent
// session idle included.
const entry = this.entries.get(sessionId);
if (entry) session.setSubagentApprovalFallback?.(this.entryApprove(entry));
}
/**
* 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(entry: RuntimeEntry): ApproveFn {
return makeApprove({
// Re-reads approval_mode from the DB on every decision (a PATCH takes effect immediately).
getMode: () => this.deps.sessions.findById(entry.sessionId)?.approvalMode ?? "always-ask",
toolPermission: (name) => entry.session.toolPermission(name),
registry: entry.approvals,
unattended: () => this.deps.sessions.findById(entry.sessionId)?.client === "org",
publishRequest: (pending) =>
this.publishEvent(entry, {
type: "approval_request",
toolCall: pending.toolCall,
...(pending.origin !== undefined ? { origin: pending.origin } : {}),
}),
});
}
/** Publishes one live background-subagent message and records its usage (fire-and-forget; the child's own Trace is the durable record). */
private forwardBackgroundMessage(sessionId: string, msg: OmniMessage): void {
const entry = this.entries.get(sessionId);
if (!entry) return;
// A child producing messages IS session activity: without this stamp the idle sweep
// measures only the launching task, and a long background run ages into eviction.
entry.lastActivityMs = Date.now();
this.deps.channels.get(entry.sessionId).publish(msg);
const ctx: UsageContext = {
projectId: entry.projectId,
agentId: entry.agentId,
sessionId: entry.sessionId,
provider: entry.provider,
modelId: entry.modelId,
};
void this.deps.recorder.record(ctx, msg).catch((err: unknown) => {
this.log(`[usage] Insert failed: ${err instanceof Error ? err.message : String(err)}`);
this.deps.errors?.record({ source: "usage", err, ctx, code: "usage_insert_failed" });
});
}
/**
* 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 {
const key = agentKey(projectId, agentId);
this.agentGenerations.set(key, this.generationOf(projectId, agentId) + 1);
}
/**
* 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 {
const agentIds = new Set<string>();
for (const e of this.entries.values()) {
if (e.projectId === projectId) agentIds.add(e.agentId);
}
for (const agentId of agentIds) this.invalidateAgentRuntimes(projectId, agentId);
}
// —— Task / compaction drive ——
/**
* 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 {
this.assertOpen();
this.assertAgentNotDeleting(sessionId);
this.assertSessionNotDeleting(sessionId);
const entry = this.entries.get(sessionId);
if (entry && !opts?.queueIfBusy) this.assertIdle(entry);
}
/**
* 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.
*/
async atIdleBoundary<T>(sessionId: string, operation: () => Promise<T>): Promise<T> {
return this.withLock(sessionId, async () => {
this.assertOpen();
this.assertAgentNotDeleting(sessionId);
this.assertSessionNotDeleting(sessionId);
const entry = this.entries.get(sessionId);
if (entry) this.assertIdle(entry);
return operation();
});
}
/**
* 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.
*/
async startTask(
sessionId: string,
input: OmniMessage[],
opts?: { queueIfBusy?: boolean; recall?: RecallStore },
): Promise<{ sessionId: string; queued: boolean }> {
return this.withLock(sessionId, async () => {
this.assertOpen();
this.assertAgentNotDeleting(sessionId);
this.assertSessionNotDeleting(sessionId);
const entry = await this.ensureEntry(sessionId);
// A person's message opens a fresh chain for company mode's hop accounting, whether the
// Task starts now or waits in the queue (see SessionManagerDeps.onHumanInput).
if (isHumanInput(input)) this.deps.onHumanInput?.(sessionId);
if (entry.status !== "idle" && opts?.queueIfBusy) {
// The cap refuses the overflow rather than enqueuing it: see FOLLOW_UP_QUEUE_LIMIT.
if (entry.followUps.length >= FOLLOW_UP_QUEUE_LIMIT) {
throw new HttpError(
429,
"queue_full",
`Session ${entry.sessionId} already has ${entry.followUps.length} queued follow-ups (cap ${FOLLOW_UP_QUEUE_LIMIT}); wait for the session to drain.`,
);
}
entry.followUps.push({
id: randomUUID(),
input,
// The original content rides the queue so a recall can hand it back, and so the
// queued line shows what is waiting (see recallFollowUp). Callers that know more
// than the input carries pass their own; the rest get it read off the input.
recall: opts.recall ?? recallStoreOf(input),
});
entry.lastActivityMs = Date.now();
// Re-publish the current state so subscribers pick up the new queued count (the
// input itself is published when the follow-up actually starts).
this.publishState(entry, entry.status);
return { sessionId: entry.sessionId, queued: true };
}
this.assertIdle(entry);
this.launchTask(entry, input);
return { sessionId: entry.sessionId, queued: false };
});
}
/**
* 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).
*/
async 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 }> {
return this.withLock(sessionId, async () => {
this.assertOpen();
this.assertAgentNotDeleting(sessionId);
this.assertSessionNotDeleting(sessionId);
const entry = await this.ensureEntry(sessionId);
this.assertIdle(entry);
const objective = args.objective;
const started = await entry.session.runUserPromptHook?.("goal", objective, {
budget: args.budget,
});
if (!started) {
throw new HttpError(
409,
"goal_plugin_not_installed",
"Goal mode needs the goal plugin installed on this agent.",
);
}
if (!started.context) {
throw new HttpError(
500,
"goal_start_failed",
"The goal plugin's user_prompt hook gave no round-1 context.",
);
}
// Round 1 is the user's own message(s) followed by the hook's expansion context stamped
// as harness-injected (the protocol text points back at the user message as the
// objective). Later rounds are the stop hook's continues, which core stamps the same way.
const input = [...args.messages, userText(started.context, "harness")];
const ac = new AbortController();
entry.status = "running";
entry.abort = ac;
entry.lastActivityMs = Date.now();
// Round-1 input: same publish + pendingInputs hold as launchTask. Core never yields
// a run's own initial input (only the stop hook's later injections), so without this
// publish the round-1 messages reach only the Trace — a page already subscribed (a
// second goal on the session) would not see the user's message or the protocol
// message until a reload. Append + bootstrap reset for the same abort-mid-bootstrap
// reasons as launchTask.
entry.pendingInputs = [...entry.pendingInputs, ...input];
entry.pendingBootstrap = [];
const channel = this.deps.channels.get(entry.sessionId);
for (const msg of input) channel.publish(msg);
this.publishState(entry, "running");
const approve = this.entryApprove(entry);
this.publishEvent(entry, {
type: "goal_started",
sessionId: entry.sessionId,
objective,
budget: args.budget,
});
const gen = this.goalStream(entry, {
input,
budget: args.budget,
approve,
signal: ac.signal,
});
// The objective doubles as the title material (same role as a task's input text).
entry.running = this.drive(entry, gen, { userExcerpt: objective });
return { sessionId: entry.sessionId };
});
}
/**
* 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 async *goalStream(
entry: RuntimeEntry,
args: {
input: OmniMessage[];
budget: number;
approve: ApproveFn;
signal: AbortSignal;
},
): AsyncGenerator<OmniMessage> {
const gen = entry.session.run(args.input, {
approve: args.approve,
signal: args.signal,
});
let round = 0;
let used = 0;
let finished = false;
// Round 1's boundary is the seeded input itself: it never comes back out of `gen`.
for (const msg of args.input) {
if (isHookInput(msg)) {
round++;
this.publishEvent(entry, {
type: "goal_round",
sessionId: entry.sessionId,
round,
used,
budget: args.budget,
});
}
}
// Set by a stop hook's `continue` event, spent by the input that follows it.
let continued = false;
try {
for await (const msg of gen) {
if (isHookContinue(msg)) continued = true;
if (continued && isHookInput(msg)) {
continued = false;
round++;
this.publishEvent(entry, {
type: "goal_round",
sessionId: entry.sessionId,
round,
used,
budget: args.budget,
});
}
const progress = goalProgressOf(msg);
if (progress) used = progress.tokensUsed;
const outcome = goalOutcomeOf(msg);
if (outcome) {
finished = true;
this.publishEvent(entry, {
type: "goal_finished",
sessionId: entry.sessionId,
outcome: outcome.outcome,
rounds: outcome.rounds,
used: outcome.tokensUsed,
});
}
yield msg;
}
if (!finished) this.finishAborted(entry, round, used);
} catch (err) {
// Core throws only on infrastructure failures: close the goal
// as aborted, then let drive's defensive catch record the error. Guarded on
// `finished`: a throw after the terminal event must not publish a contradicting event.
if (!finished) this.finishAborted(entry, round, used);
throw err;
}
}
/** Closes a goal as aborted for the UI (stream cut off / infrastructure failure). */
private finishAborted(entry: RuntimeEntry, round: number, used: number): void {
this.publishEvent(entry, {
type: "goal_finished",
sessionId: entry.sessionId,
outcome: "aborted",
rounds: round,
used,
});
}
/** 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(entry: RuntimeEntry, input: OmniMessage[]): void {
const channel = this.deps.channels.get(entry.sessionId);
const ac = new AbortController();
entry.status = "running";
entry.abort = ac;
entry.lastActivityMs = Date.now();
// Publish the input messages first (visible to other subscribers; the Trace is
// persisted by the SDK), then flip the running status. The same envelopes are held as
// pendingInputs so GET /messages can serve them before the engine's Trace write
// catches up (delayed by the first run's MCP connect). APPEND, don't replace: inputs
// of a run aborted mid-bootstrap are still held (nothing reached the Trace; core
// carries them into this run) and must stay served until this run persists them.
// The previous attempt's bootstrap records are dropped instead — this run streams
// its own connect phase, and a stale aborted pair would render as an extra row.
entry.pendingInputs = [...entry.pendingInputs, ...input];
entry.pendingBootstrap = [];
for (const msg of input) channel.publish(msg);
this.publishState(entry, "running");
const approve = this.entryApprove(entry);
const gen = entry.session.run(input, {
approve,
signal: ac.signal,
});
// This call's input user text is the whole title source: drive persists its first
// words as the immediate fallback and hands it to the LLM as the generation material
// (user input only — generation never waits for model output).
const userExcerpt = input
.filter(isPlainText("user"))
.map((m) => m.payload.text)
.join("\n");
entry.running = this.drive(entry, gen, { userExcerpt });
}
/**
* 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 async startQueuedFollowUp(sessionId: string): Promise<void> {
try {
await this.withLock(sessionId, async () => {
if (this.closed || this.deletingSessions.has(sessionId)) return;
const row = this.deps.sessions.findById(sessionId);
if (row && this.deletingAgents.has(agentKey(row.projectId, row.agentId))) return;
const entry = this.entries.get(sessionId);
if (!entry || entry.status !== "idle" || entry.followUps.length === 0) return;
const next = entry.followUps.shift()!;
this.launchTask(entry, next.input);
});
} catch (err) {
this.log(`[followup] auto-start failed: ${err instanceof Error ? err.message : String(err)}`);
}
}
/** Manually compact the context: 409 if already running; compaction output also flows into the SSE channel. */
async startCompact(sessionId: string): Promise<{ sessionId: string }> {
return this.withLock(sessionId, async () => {
this.assertOpen();
this.assertAgentNotDeleting(sessionId);
this.assertSessionNotDeleting(sessionId);
const entry = await this.ensureEntry(sessionId);
this.assertIdle(entry);
// When there's nothing to compact, core's compact() yields no messages at all: we
// can't just return 202 and walk away, or the frontend would wait forever for a
// compaction banner that never comes (this is exactly the "/compact does nothing
// after an interrupt" complaint). Reject explicitly, and **say why** clearly —
// "just compacted" and "haven't talked yet" share the same internal state
// (sessionTurns === 0), but are two completely different messages to the user:
// telling someone who just compacted that there's "no completed conversation turn
// yet" tells them nothing.
const why = entry.session.compactability();
if (why !== "ok") throw compactUnavailable(why);
const ac = new AbortController();
entry.status = "compacting";
entry.abort = ac;
entry.lastActivityMs = Date.now();
this.publishState(entry, "compacting");
const gen = entry.session.compact({ signal: ac.signal });
entry.running = this.drive(entry, gen);
return { sessionId: entry.sessionId };
});
}
/**
* 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.
*
* `opts.onCompactionFailure` is passed straight to core (`"discard"` drops the context and
* switches anyway): it is the route's answer to a model whose requests all fail, where the
* closing summarize could never succeed. Nothing here reads it — the events the drive streams
* say which of the two happened.
*/
async startSwitch(
sessionId: string,
ref: ModelRefDto,
opts?: { onCompactionFailure?: SwitchFailurePolicy },
): Promise<{ sessionId: string; switched: boolean }> {
return this.withLock(sessionId, async () => {
this.assertOpen();
this.assertAgentNotDeleting(sessionId);
this.assertSessionNotDeleting(sessionId);
const entry = await this.ensureEntry(sessionId);
this.assertIdle(entry);
if (entry.provider === ref.provider && entry.modelId === ref.modelId) {
throw new HttpError(
409,
"same_model",
`This Session already runs on ${ref.provider} / ${ref.modelId}.`,
);
}
if (!entry.session.switchModel) {
throw new HttpError(
409,
"model_unavailable",
"Switching the model is not available for this Session.",
);
}
const ac = new AbortController();
const gen = entry.session.switchModel({
...ref,
signal: ac.signal,
...(opts?.onCompactionFailure !== undefined
? { onCompactionFailure: opts.onCompactionFailure }
: {}),
});
const head = gen.next();
const settled = (): void => {
entry.abort = null;
entry.running = null;
};
// One promise for the whole switch — the pull, then the drive behind it — so whoever
// waits for this entry's run to end waits for both.
entry.abort = ac;
entry.running = head.then((first) => {
if (first.done) return settled();
entry.status = "compacting";
this.publishState(entry, "compacting");
return this.drive(entry, resumeFrom(first.value, gen));
}, settled);
let first: IteratorResult<OmniMessage, StopReason>;
try {
first = await head;
} catch (err) {
throw switchRefusal(err, ref);
}
entry.lastActivityMs = Date.now();
if (!first.done) return { sessionId: entry.sessionId, switched: false };
this.syncEntryModel(entry);
return { sessionId: entry.sessionId, switched: true };
});
}
/** Who is told when a Session's model moves (see `onModelChanged`). */
private readonly modelListeners = new Set<(sessionId: string, model: ModelRefDto) => void>();
/**
* 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 {
this.modelListeners.add(listener);
return () => void this.modelListeners.delete(listener);
}
/**
* 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(entry: RuntimeEntry): void {
const model = runtimeModelOf(entry.session);
if (!model) return;
if (entry.provider === model.provider && entry.modelId === model.modelId) return;
entry.provider = model.provider;
entry.modelId = model.modelId;
const ctx = { projectId: entry.projectId, agentId: entry.agentId, sessionId: entry.sessionId };
try {
this.deps.sessions.updateModel(entry.sessionId, model.provider, model.modelId);
} catch (err) {
this.log(
`[session] model bookkeeping failed: ${err instanceof Error ? err.message : String(err)}`,
);
this.deps.errors?.record({
source: "session",
err,
ctx,
code: "session_model_update_failed",
});
}
for (const listener of this.modelListeners) {
try {
listener(entry.sessionId, model);
} catch (err) {
this.deps.errors?.record({
source: "session",
err,
ctx,
code: "session_model_listener_failed",
});
}
}
}
/** 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 {
const entry = this.entries.get(sessionId);
if (!entry) return false;
return entry.approvals.decide(toolCallId, decision);
}
/**
* 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 {
const entry = this.entries.get(sessionId);
if (!entry || entry.status !== "running" || !entry.session.steer(input)) {
throw new HttpError(
409,
"not_running",
"This Session has no Task in progress; send the message as a new task instead.",
);
}
entry.pendingSteering.push({
info: {
id: randomUUID(),
text: recall.text,
images: recall.images.length,
videos: recall.videos.length,
files: recall.files.length,
},
input,
recall,
});
entry.lastActivityMs = Date.now();
this.publishState(entry, entry.status);
}
/**
* 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 {
const entry = this.entries.get(sessionId);
if (entry) {
const queued = entry.pendingSteering.findIndex((p) => p.info.id === steerId);
if (queued >= 0) {
const pending = entry.pendingSteering[queued]!;
// Still queued on a live run: core decides, since the mirror can lag a delivery that
// has not reached the stream yet.
if (entry.session.unsteer?.(pending.input) ?? false) {
entry.pendingSteering.splice(queued, 1);
entry.lastActivityMs = Date.now();
this.publishState(entry, entry.status);
return pending.recall;
}
}
// Handed back when the run exited without delivering it: core's queue is gone, so there
// is nothing to unsteer and the mirror is the only authority left — it holds exactly
// what the drained stream never showed as delivered (see RuntimeEntry.returnedSteering).
const returned = entry.returnedSteering.findIndex((p) => p.info.id === steerId);
if (returned >= 0) {
const [taken] = entry.returnedSteering.splice(returned, 1);
entry.lastActivityMs = Date.now();
this.publishState(entry, entry.status);
return taken!.recall;
}
}
throw new HttpError(
409,
"not_pending",
"This steering message was already delivered to the model and can no longer be recalled.",
);
}
/**
* 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 } {
const entry = this.entries.get(sessionId);
const i = entry?.followUps.findIndex((f) => f.id === followUpId) ?? -1;
const queued = i >= 0 ? entry!.followUps[i]! : undefined;
if (!entry || !queued) {
throw new HttpError(
409,
"follow_up_started",
"This follow-up message already started and can no longer be recalled.",
);
}
entry.followUps.splice(i, 1);
entry.lastActivityMs = Date.now();
this.publishState(entry, entry.status);
return { recall: queued.recall };
}
/**
* "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 {
const entry = this.entries.get(sessionId);
// Both running Tasks and compactions can be parked in a reconnect backoff.
if (!entry || entry.status === "idle") return false;
const skipped = entry.session.skipReconnectWait();
if (skipped) entry.lastActivityMs = Date.now();
return skipped;
}
/**
* 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 {
const entry = this.entries.get(sessionId);
if (!entry || !entry.abort) return false;
// Deny only the MAIN session's pending approvals: an approval blocks the run the user is
// stopping. A subagent child survives the parent's stop, and so does its question.
entry.approvals.denyMain();
entry.abort.abort();
return true;
}
/**
* 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[] {
return this.entries.get(sessionId)?.session.listBackgroundCommands?.() ?? [];
}
/**
* 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.
*/
async probeProcessServices(sessionId: string): Promise<void> {
await this.entries.get(sessionId)?.session.probeBackgroundCommandServices?.();
}
/**
* 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 {
const entry = this.entries.get(sessionId);
if (!entry) return "not_running";
const result = entry.session.detachToolCall?.(toolCallId) ?? "not_running";
if (result === "detached") entry.lastActivityMs = Date.now();
return result;
}
/** 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 {
const entry = this.entries.get(sessionId);
if (!entry) return false;
const killed = entry.session.killBackgroundCommand?.(processId) ?? false;
if (killed) entry.lastActivityMs = Date.now();
return killed;
}
/**
* 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" {
const entry = this.entries.get(sessionId);
if (!entry) return "not_found";
const info = entry.session.listBackgroundCommands?.().find((p) => p.processId === processId);
if (!info) return "not_found";
if (info.running) return "running";
const removed = entry.session.killBackgroundCommand?.(processId) ?? false;
if (!removed) return "not_found";
entry.lastActivityMs = Date.now();
return "removed";
}
/**
* 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(entry: RuntimeEntry): void {
const dispose = (): void => entry.session.dispose?.();
if (entry.running) void entry.running.then(dispose, dispose);
else dispose();
}
/**
* 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>[] {
const runnings: Promise<void>[] = [];
for (const [key, entry] of [...this.entries]) {
if (entry.projectId !== projectId) continue;
entry.approvals.denyAll();
entry.abort?.abort();
if (entry.running) runnings.push(entry.running);
this.entries.delete(key);
this.disposeRemoved(entry);
}
return runnings;
}
/**
* 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>[] {
this.deletingAgents.add(agentKey(projectId, agentId));
const runnings: Promise<void>[] = [];
for (const [key, entry] of [...this.entries]) {
if (entry.projectId !== projectId || entry.agentId !== agentId) continue;
entry.approvals.denyAll();
entry.abort?.abort();
if (entry.running) runnings.push(entry.running);
this.entries.delete(key);
this.disposeRemoved(entry);
}
return runnings;
}
endAgentDeletion(projectId: string, agentId: string): void {
this.deletingAgents.delete(agentKey(projectId, agentId));
}
/**
* 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>[] {
this.deletingSessions.add(sessionId);
const entry = this.entries.get(sessionId);
if (!entry) return [];
entry.approvals.denyAll();
entry.abort?.abort();
this.entries.delete(sessionId);
this.disposeRemoved(entry);
return entry.running ? [entry.running] : [];
}
endSessionDeletion(sessionId: string): void {
this.deletingSessions.delete(sessionId);
}
/** Graceful shutdown: reject new tasks (503), interrupt all active runs, and wait for them to finish (default ≤5s). */
async shutdown(timeoutMs = 5000): Promise<void> {
this.closed = true;
clearInterval(this.sweepTimer);
const pending: Promise<void>[] = [];
for (const entry of this.entries.values()) {
entry.approvals.denyAll();
entry.abort?.abort();
if (entry.running) pending.push(entry.running);
// Suspend means the environment too: dispose kills the Session's remaining
// background processes (a dev server the conversation started, etc.). Without
// this, a hot swap orphans them — the OS process keeps running while the next
// App's freshly resumed Session starts with an empty process list, so the stop
// control has gone blind. Sequenced after the in-flight drive settles, the same
// ordering disposeRemoved uses.
const dispose = (): void => entry.session.dispose?.();
if (entry.running) void entry.running.then(dispose, dispose);
else dispose();
}
this.entries.clear();
if (pending.length === 0) return;
await Promise.race([
Promise.allSettled(pending).then(() => undefined),
new Promise<void>((resolve) => setTimeout(resolve, timeoutMs).unref?.()),
]);
}
/**
* 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 = Date.now(), idleMs: number = ENTRY_IDLE_MS): void {
for (const [key, entry] of this.entries) {
if (entry.status !== "idle" || entry.approvals.size !== 0 || entry.running !== null) continue;
if (entry.followUps.length > 0) continue; // queued follow-ups must not be evicted with the entry
// A live background process (e.g. a dev server the conversation started) pins the
// entry: eviction would strand the process — a resumed entry starts with a fresh
// environment, so the process list and its stop control would go blind while the
// OS process kept running. Exited-but-listed processes don't pin anything.
if (entry.session.listBackgroundCommands?.().some((p) => p.running)) continue;
// A background subagent still working pins it for the same reason: a run_in_background
// child outlives the call that launched it, and its completion report and live messages
// are delivered through the very Session object eviction would drop.
if (entry.session.hasRunningBackgroundSubagents?.()) continue;
// Undelivered background completion notices pin the entry too: they live in the core
// Session object, so evicting it would silently drop them.
if (entry.session.hasPendingBackgroundNotices?.()) continue;
if (now - entry.lastActivityMs <= idleMs) continue;
this.entries.delete(key);
}
}
// —— Internal ——
private assertOpen(): void {
if (this.closed) {
throw new HttpError(
503,
"shutting_down",
"Server is shutting down; not accepting new Tasks.",
);
}
}
/** The Agent owning this Session is being deleted → 409 (guards against directory recreation inside the deletion race window). */
private assertAgentNotDeleting(sessionId: string): void {
const row = this.deps.sessions.findById(sessionId);
if (row && this.deletingAgents.has(agentKey(row.projectId, row.agentId))) {
throw new HttpError(
409,
"agent_deleting",
"This Agent is being deleted; not accepting new Tasks.",
);
}
}
/** This Session is being deleted → 409 (guards against the entry/Trace being rebuilt and reviving it inside the deletion race window). */
private assertSessionNotDeleting(sessionId: string): void {
if (this.deletingSessions.has(sessionId)) {
throw new HttpError(
409,
"session_deleting",
"This Session is being deleted; not accepting new Tasks.",
);
}
}
private assertIdle(entry: RuntimeEntry): void {
if (entry.status === "running") {
throw new HttpError(409, "task_in_progress", "This Session already has a Task in progress.");
}
if (entry.status === "compacting") {
throw new HttpError(
409,
"compacting",
"This Session is compacting its context; not accepting new input.",
);
}
}
private generationOf(projectId: string, agentId: string): number {
return this.agentGenerations.get(agentKey(projectId, agentId)) ?? 0;
}
private async refreshProviderCredentialIfNeeded(row: {
projectId: string;
agentId: string;
provider: string;
}): Promise<void> {
const refreshed = await this.deps.modelScopeAuth?.ensureFresh({
projectId: row.projectId,
provider: row.provider,
});
if (refreshed?.changed) this.invalidateProjectRuntimes(row.projectId);
}
/** 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 async ensureEntry(sessionId: string): Promise<RuntimeEntry> {
const existing = this.entries.get(sessionId);
/** Background-task counts the discarded runtime last reported (see the publish below). */
let discardedBackgroundTasks: SessionBackgroundTasks | undefined;
if (existing) {
await this.refreshProviderCredentialIfNeeded(existing);
if (existing.generation === this.generationOf(existing.projectId, existing.agentId)) {
return existing;
}
// Built before the last credential change: discard once idle and fall through to a
// fresh load (resume re-reads the Project config). A busy entry is returned as-is — the
// in-flight run keeps its values and assertIdle rejects the new Task anyway;
// it is rebuilt on the first access after it finishes.
if (
existing.status !== "idle" ||
existing.running !== null ||
existing.approvals.size !== 0
) {
return existing;
}
this.entries.delete(sessionId);
discardedBackgroundTasks = existing.backgroundTasks;
}
const row = this.deps.sessions.findById(sessionId);
if (!row) {
throw new HttpError(
404,
"session_not_found",
"Session does not exist or you do not have access.",
);
}
await this.refreshProviderCredentialIfNeeded(row);
// Captured before the (awaited) load: an invalidation racing with the load leaves
// this entry stale, so the access after next rebuilds it with the new values.
const generation = this.generationOf(row.projectId, row.agentId);
const session = await this.deps.loader.load(row);
// The Session/Agent was marked for deletion while loading: discard the load result,
// don't rebuild the entry (avoids reviving an orphaned Trace).
this.assertSessionNotDeleting(row.sessionId);
this.assertAgentNotDeleting(row.sessionId);
// A thinking-level PATCH that landed during the (awaited) load updated the row but found
// no entry to assign, and the loader applied the snapshot's level: re-read the pin.
const pin = this.deps.sessions.findById(row.sessionId)?.thinkingLevel;
if (pin && pin !== row.thinkingLevel) session.thinkingLevel = pin;
let currentId = row.sessionId;
if (session.sessionId !== row.sessionId) {
// Self-heal produced a new session_id: update the index's primary key; the SSE
// channel and pending state are naturally empty for it.
this.deps.sessions.replaceId(row.sessionId, session.sessionId);
currentId = session.sessionId;
}
const entry: RuntimeEntry = {
sessionId: currentId,
projectId: row.projectId,
agentId: row.agentId,
provider: row.provider,
modelId: row.modelId,
session,
status: "idle",
approvals: new ApprovalRegistry(() => this.publishApprovals(entry)),
abort: null,
running: null,
generation,
followUps: [],
pendingInputs: [],
pendingBootstrap: [],
pendingSteering: [],
returnedSteering: [],
lastActivityMs: Date.now(),
// Baselined on the DISCARDED runtime's counts when there was one: the replacement
// resumes with empty registries, so a client that saw the old counts would keep its
// background-task mark with no ping left to clear it. Publishing against that baseline
// below reports whatever the fresh runtime actually owns — nothing, in every case the
// discard path produces today.
backgroundTasks: discardedBackgroundTasks ?? backgroundTaskCounts(session),
};
// The runtime's model is the truth the row caches: a Session that switched models and
// crashed between the Trace write and the row update resumes (from the Trace) on the new
// model, and the row is brought back in step here.
this.syncEntryModel(entry);
this.entries.set(currentId, entry);
this.registerNoticeListener(currentId, session);
if (discardedBackgroundTasks !== undefined) this.publishBackgroundTasks(currentId);
return entry;
}
/**
* 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 async startBackgroundNoticeTask(sessionId: string): Promise<void> {
try {
await this.withLock(sessionId, async () => {
if (this.closed || this.deletingSessions.has(sessionId)) return;
const row = this.deps.sessions.findById(sessionId);
if (row && this.deletingAgents.has(agentKey(row.projectId, row.agentId))) return;
const entry = this.entries.get(sessionId);
if (!entry) {
// The runtime entry left the active table between the signal and this lock —
// the queued notices left with the released Session object. Say so instead of
// dropping the report invisibly (the sweep pins entries with pending notices,
// so this is a genuine anomaly worth a trace in the log).
this.log(`[background] notice for ${sessionId} dropped: runtime entry not loaded`);
return;
}
// Busy or queued-behind: not a loss — the running/next run's engine drains the
// same notice queue at its own input-assembly boundaries.
if (entry.status !== "idle" || entry.followUps.length > 0) return;
const input = entry.session.takeBackgroundNotices?.() ?? [];
if (input.length === 0) return;
this.launchTask(entry, input);
});
} catch (err) {
this.log(
`[background] notice task start failed: ${err instanceof Error ? err.message : String(err)}`,
);
}
}
/**
* 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 async drive(
entry: RuntimeEntry,
gen: AsyncGenerator<OmniMessage>,
titleSource?: { userExcerpt: string },
): Promise<void> {
const ctx: UsageContext = {
projectId: entry.projectId,
agentId: entry.agentId,
sessionId: entry.sessionId,
provider: entry.provider,
modelId: entry.modelId,
};
// Title policy fires at run start, from the user input alone: the generator persists
// the input's first words as an immediate fallback and issues the LLM replacement
// request without waiting for any model output (maybeGenerate self-guards: manual
// renames are final, one generation in flight per session).
if (titleSource?.userExcerpt.trim()) {
this.deps.titles?.maybeGenerate(ctx, entry.session, {
fallbackText: titleSource.userExcerpt,
material: { userText: titleSource.userExcerpt, assistantText: "" },
});
}
// Every driven run (a Task, a compaction, or a whole goal loop — startGoal hands all of
// its rounds to ONE drive) writes Trace lines: flip the row's has_trace cache here, the
// single choke point, so listing can serve it from the DB without a directory walk (see
// SessionService.listSessions). The same statement stamps last_active_at, so a run costs
// one row write here and one more when it ends (see the finally) — never one per streamed
// message; activity during the run (steering, approvals, queued follow-ups) rides on the
// run-end stamp. Guarded: this runs BEFORE the try below, so an unexpected DB failure
// (a closed handle after shutdown) would otherwise reject drive() with no finally to
// reach — leaving the entry pinned "running" and every later Task 409ing for the
// process's lifetime.
this.touchRow(ctx, (repo, at) => repo.markDriven(ctx.sessionId, at));
// LLM request failures and tool execution failures aren't expressed via throw (core
// converges them into the message stream), so the try/catch below can't catch them:
// the watcher inspects messages one by one and fishes them out for persistence
// (subagent failures flow through this same stream too; see stream-error-watcher).
const watcher = this.deps.errors
? new StreamErrorWatcher(this.deps.errors, {
projectId: entry.projectId,
agentId: entry.agentId,
sessionId: entry.sessionId,
})
: null;
// Subagent (origin) registration: as soon as session_meta arrives, the child Session
// is persisted so it appears immediately in the sidebar (the frontend picks it up
// when it refreshes the list at task completion). The title material is "the prompt
// of the run_subagent call that spawned this subagent" — the subagent's user input
// is never replayed onto the parent stream (ContextEngine writes the Trace but never
// yields it), so we can't rely on the subagent's first user message; instead we use
// the run_subagent tool_call arguments immediately preceding it on the parent stream
// (depth limited to 1, spawned in order, so taking the most recent one suffices).
/** Subagents registered during this run (keyed by session id); each gets its title generated at registration, from its spawning prompt alone. */
const children = new Map<string, ChildSession>();
// Unclaimed run_subagent prompts, queued in call order: a single round may spawn
// multiple subagents in parallel, and a subagent's session_meta only carries the
// session id (no tool_call_id), so pairing can only be approximated via FIFO (when
// spawned in parallel and session_meta arrives out of order, two subagents' titles
// may end up swapped — this only affects the displayed title). A call that will
// never produce a subagent must be dequeued, or its prompt would be mismatched onto
// the next subagent: this covers denied calls (approval_decision ≠ allow), and calls
// that were approved but failed before spawning the subagent (e.g. agent_id doesn't
// exist) — the latter is cleaned up when the parent-level tool_call_output settles;
// if the call is still in the queue at that point, it never produced a session_meta.
const subagentPrompts = new Map<string, string>();
try {
for await (const msg of gen) {
// A parent-level (no origin) run_subagent call: record its prompt for the child
// session_meta that arrives later to use as its title.
if (!msg.origin || msg.origin.length === 0) {
const call = runSubagentCall(msg);
if (call) subagentPrompts.set(call.toolCallId, call.prompt);
const denied = deniedToolCallId(msg);
if (denied) subagentPrompts.delete(denied);
const settled = settledToolCallId(msg);
if (settled) subagentPrompts.delete(settled);
// Steering delivery: core emits exactly one `[user_steering]` user text per queued
// entry, in queue order — shift the display mirror and re-broadcast so the
// composer's "steering queued" hint retires the moment the message is on stream.
if (entry.pendingSteering.length > 0 && isDeliveredSteering(msg)) {
entry.pendingSteering.shift();
this.publishState(entry, entry.status);
}
// The main session's own session_meta is streamed when a model switch opens its new
// context, and the runtime is on that context's model by then: the entry and the row
// follow it here, ahead of the publish below, so a client that re-reads the Session
// on this record already finds the new model. The new context's file is open too, its
// records on it, and what the context it replaced still held pending went with it.
if (isSessionMeta(msg)) {
this.syncEntryModel(entry);
entry.pendingBootstrap = [];
}
} else if (isSessionMeta(msg)) {
// Subagent registration is only a "side effect" — it must never interrupt the
// main run flow on error: wrap the whole thing in a defensive try/catch.
try {
const child = this.registerChildSession(entry, msg, children);
// Only a **direct** subagent (origin length 1) claims a queued parent-level
// run_subagent prompt; deeper sessions are spawned by their own parent and
// shouldn't consume from this queue.
if (child && msg.origin!.length === 1) {
const [pendingId] = subagentPrompts.keys();
if (pendingId !== undefined) {
child.prompt = subagentPrompts.get(pendingId) ?? "";
subagentPrompts.delete(pendingId); // Consumed by this session_meta
}
// The subagent's title is generated right here at registration, from the
// spawning prompt alone (its "user input") — never waiting for the
// subagent's own output. It piggybacks a one-shot request on the parent
// Session's bare LLM (the child Session object never leaves the SDK):
// Session/Agent record the subagent (the title belongs to it), but the
// model reference keeps ctx's parent-Session (provider, modelId) pair —
// a subagent may switch models via run_subagent's model_id.
if (child.prompt.trim()) {
this.deps.titles?.maybeGenerate(
{ ...ctx, agentId: child.agentId, sessionId: child.sessionId },
entry.session,
{
fallbackText: child.prompt,
material: { userText: child.prompt, assistantText: "" },
notifyOn: entry.sessionId, // Notify the frontend via the parent Session's SSE channel
},
);
}
}
} catch (err) {
this.log(
`[subagent] Failed to register child session: ${err instanceof Error ? err.message : String(err)}`,
);
this.deps.errors?.record({
source: "subagent",
err,
ctx,
code: "subagent_register_failed",
});
}
}
// Bootstrap records (first-run MCP connect + toolset): held for GET /messages
// until the engine's deferred Trace write catches up (see pendingBootstrap).
if (!msg.origin || msg.origin.length === 0) {
const bt = (msg.payload as { type?: string }).type;
if (bt === "mcp_connect_begin" || bt === "mcp_connect_end" || bt === "tool_list_ready") {
entry.pendingBootstrap.push(msg);
}
// First request of the run: the engine writes input → bootstrap records → tool
// list to the Trace BEFORE issuing the request, so both holds are persisted by
// now — end them here rather than at idle. Holding for the whole run would
// outlive the messages endpoint's tail-window dedup: once the Task appends
// more records than the window, the input would be judged "not yet in the
// Trace" and served a second time at the end of history.
if (bt === "request_begin") {
entry.pendingInputs = [];
entry.pendingBootstrap = [];
}
}
// Live-tail bookkeeping in the same synchronous tick as the publish below: the
// messages endpoint captures "channel cursor + open fragments" between two
// publishes, so the pair is always a consistent snapshot (see live-tail.ts).
this.liveTail.observe(entry.sessionId, msg);
// Re-fetch the channel before every publish (matches publishEvent): the channel
// may have been recycled and recreated during a long wait on approval, and
// holding a stale reference would send output to an orphaned, detached channel.
this.deps.channels.get(entry.sessionId).publish(msg);
watcher?.observe(msg);
try {
await this.deps.recorder.record(ctx, msg);
} catch (err) {
this.log(`[usage] Insert failed: ${err instanceof Error ? err.message : String(err)}`);
this.deps.errors?.record({ source: "usage", err, ctx, code: "usage_insert_failed" });
}
}
} catch (err) {
// The SDK doesn't normally throw (errors are converged into the message stream);
// this is a defensive record here to avoid crashing the runtime.
this.log(
`[session] Run failed: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`,
);
this.deps.errors?.record({ source: "session", err, ctx, code: "session_run_failed" });
} finally {
// Wrap-up: persist any still-pending LLM failure and clear the tool-name cache (the watcher's state doesn't carry across runs).
watcher?.close();
// The run is over: no fragment will ever continue, so drop the live tail before the
// idle flip (GET /messages stops attaching `live` the moment status reads idle).
this.liveTail.clear(entry.sessionId);
// The pending holds are NOT cleared here: a run aborted mid-bootstrap wrote nothing
// to the Trace, so its held input (and the aborted connect pair) are the only copy
// a reload can show until the next run carries the input forward and persists it.
// Runs that issued a request already cleared them at their first request_begin.
// Main approvals only: an origin-tagged approval belongs to a subagent child that
// outlives this task — it stays pending for the user (see ApprovalRegistry.denyMain).
entry.approvals.denyMain();
entry.status = "idle";
entry.abort = null;
entry.running = null;
// The run is over, so core has discarded any undelivered steering (see ContextEngine's
// steeringQueue). What is still in the mirror was therefore never delivered — entries
// are shifted out as their `[user_steering]` message appears on the stream, and this
// runs after that stream is drained — so hand it back to the user rather than dropping
// it: the composer recalls it into its draft. Interrupting while a tool runs is the
// ordinary way to get here, and the typed message must survive it.
if (entry.pendingSteering.length > 0) {
entry.returnedSteering = [...entry.returnedSteering, ...entry.pendingSteering];
entry.pendingSteering = [];
}
entry.lastActivityMs = Date.now();
// Run-end stamp (see the run-start counterpart at the top of drive). Guarded like
// every other write in this finally: what follows — the idle broadcast and the
// auto-start of queued follow-ups (this is its only call site) — must not be
// skippable by a DB failure, or SSE clients would sit on "running" forever with
// their queue stranded. A no-op UPDATE when the row is already gone: deletion
// normally awaits the drive first, so that only happens once its 5s wait times out.
this.touchRow(ctx, (repo, at) => repo.touchLastActive(ctx.sessionId, at));
this.publishState(entry, "idle");
// Queued follow-ups: whenever a run finishes (Task or compaction, abort included),
// the next queued input auto-starts as an ordinary task. Fire-and-forget — it
// revalidates under the session lock.
if (entry.followUps.length > 0) void this.startQueuedFollowUp(entry.sessionId);
// Background completion notices that raced this run's exit (arrived after its last
// input-assembly boundary): start their delivery task now. No-op when a follow-up
// just launched — that run's engine drains the same queue.
else void this.startBackgroundNoticeTask(entry.sessionId);
}
}
/**
* 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(
entry: RuntimeEntry,
msg: OmniMessage,
children: Map<string, ChildSession>,
): ChildSession | null {
if (!isSessionMeta(msg)) return null;
const childSid = msg.origin![msg.origin!.length - 1]!;
if (children.has(childSid)) return null;
const p = msg.payload as SessionMetaPayload;
const agentId = path.basename(path.dirname(p.agent_state));
if (!agentId || agentId === "." || agentId === "..") return null;
// The forwarded session_meta records the source where it is decided (core's spawn site
// writes `subagent`); it is narrowed like any meta read back, so the registry holds what
// the child's Trace head will answer after a restart. It goes into the in-process registry
// only — the index row deliberately stores no source column.
const source = normalizeSessionSource(p.source);
this.deps.sources.set(childSid, source);
const root = this.rootSessionOf(entry.sessionId);
this.childRoots.set(childSid, root);
const createdAt = this.now().toISOString();
// A sub-session of an organization's Session is company mode's own as much as the desk
// or ticket session that spawned it: it inherits the durable "org" stamp, which is the
// only mark it can carry — the organization caches name desks and ticket sessions, never
// what those spawn — and the one development mode's list leaves out. Every other parent
// leaves the marker blank (read as web): the child was spawned by this server's run, not
// opened through the CLI, whatever opened its parent.
const parentClient = this.deps.sessions.findById(entry.sessionId)?.client;
this.deps.sessions.insertOrIgnore({
sessionId: childSid,
projectId: entry.projectId,
agentId,
provider: p.provider,
modelId: p.model_id,
workspace: p.workspace,
// A subagent's approvals are inherited from the parent Session; the index row is
// inserted with defaults (matches the convention for Sessions discovered by the CLI).
approvalMode: "allow-all",
// The root's policy at registration, so the child row stands on its own if it is ever
// resumed directly; while registered it follows the root (see rootSessionOf).
sandbox: this.deps.sessions.findById(root)?.sandbox ?? null,
title: null,
...(parentClient === "org" ? { client: "org" as const } : {}),
// Its Trace exists by construction.
hasTrace: true,
// A subagent's own runs are driven through the PARENT entry's drive, so nothing ever
// stamps this row: it stays at its registration time (see SessionRow.lastActiveAt).
lastActiveAt: createdAt,
createdAt,
});
// Make the subagent appear immediately in the sidebar: notify via the parent
// Session's channel (a frontend currently watching the parent run refreshes its list in place).
this.publishEvent(entry, {
type: "session_created",
projectId: entry.projectId,
agentId,
sessionId: childSid,
source,
});
const child: ChildSession = {
sessionId: childSid,
agentId,
prompt: "",
};
children.set(childSid, child);
return child;
}
/**
* 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(ctx: UsageContext, write: (repo: SessionIndex, at: string) => void): void {
try {
write(this.deps.sessions, this.now().toISOString());
} catch (err) {
this.log(
`[session] last-active bookkeeping failed: ${err instanceof Error ? err.message : String(err)}`,
);
this.deps.errors?.record({ source: "session", err, ctx, code: "session_touch_failed" });
}
}
private publishState(entry: RuntimeEntry, state: SessionStatus): void {
// Every state flip also reports the queued follow-up count, the undelivered steering
// mirror, and the live subagent children, so subscribers can render all three hints
// without a dedicated event type.
const subagents = entry.session.listBackgroundSubagents?.() ?? [];
this.publishEvent(entry, {
type: "task_state",
state,
queued: entry.followUps.length,
...(entry.pendingSteering.length > 0
? { pendingSteering: entry.pendingSteering.map((p) => p.info) }
: {}),
...(entry.returnedSteering.length > 0
? { returnedSteering: entry.returnedSteering.map((p) => p.info) }
: {}),
...(entry.followUps.length > 0
? { pendingFollowUps: entry.followUps.map(followUpInfo) }
: {}),
...(subagents.length > 0 ? { subagents } : {}),
});
// The same flip again, this time on the user channel and carrying the Session id: a tab
// subscribes to the ONE conversation it has open, so the event above can never move any
// other row's badge. Only the queued/steering hints stay session-scoped — they belong to
// the composer of the conversation being watched, not to a list row.
const notify = this.deps.notifyProjectUsers;
if (!notify) return;
let lastActiveAt: string;
let hasTrace: boolean;
try {
// Read the stamp back rather than reconstruct it: the run-end flip is published right
// after the write that stamps it (touchLastActive in drive's finally), so this is what a
// list fetch would return right now and no clock of ours has to agree with the one that
// wrote it.
const row = this.deps.sessions.findById(entry.sessionId);
if (!row) return; // Row already deleted: no list row left to light up.
lastActiveAt = row.lastActiveAt;
// A running Session has by definition started a Task, whatever the row cache says yet:
// markDriven (which sets has_trace) runs inside drive(), and startTask has already
// published the first "running" by then. Reporting the raw flag there would tell a client
// the Session has never run at the exact moment it visibly is running — and a client that
// believed it would draw the hourglass, then nothing at all once the run settled.
hasTrace = row.hasTrace === true || state !== "idle";
} catch {
// Same failure touchRow guards against (DB handle closed by shutdown while a run
// outlives its drain window). A list badge is never worth breaking a run's finally over.
return;
}
notify(entry.projectId, {
type: "session_state",
sessionId: entry.sessionId,
projectId: entry.projectId,
state,
lastActiveAt,
hasTrace,
});
}
private publishEvent(entry: RuntimeEntry, event: ServerEvent): void {
this.deps.channels.get(entry.sessionId).publish(event, "server_event");
}
/**
* 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(sessionId: string): void {
const entry = this.entries.get(sessionId);
if (!entry) return;
const counts = backgroundTaskCounts(entry.session);
const last = entry.backgroundTasks;
if (counts.processes === last.processes && counts.subagents === last.subagents) return;
entry.backgroundTasks = counts;
entry.lastActivityMs = Date.now();
this.deps.notifyProjectUsers?.(entry.projectId, {
type: "session_background",
sessionId: entry.sessionId,
processes: counts.processes,
subagents: counts.subagents,
});
}
/**
* 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(entry: RuntimeEntry): void {
try {
this.deps.notifyProjectUsers?.(entry.projectId, {
type: "session_approvals",
sessionId: entry.sessionId,
count: entry.approvals.size,
});
} catch (err) {
// The notifier reads the Project's audience from the database, which shutdown can close
// while a run outlives its drain window (the failure publishState guards too). A list
// mark is never worth throwing out of an approval's wait, answer or interrupt.
this.log(
`[session] approvals notice failed: ${err instanceof Error ? err.message : String(err)}`,
);
}
}
/** Serialize (mutually exclude) execution by sessionId; cleans up the lock-table entry once its chain drains (avoids unbounded growth). */
private async withLock<T>(sessionId: string, fn: () => Promise<T>): Promise<T> {
// What's stored in the chain is the already-caught version (used only for
// sequencing, never propagates errors); the caller gets the original result from `next`.
const prev = this.locks.get(sessionId) ?? Promise.resolve();
const next = prev.then(fn);
const settled: Promise<void> = next
.then(
() => undefined,
() => undefined,
)
.then(() => {
// Only delete if still the tail of the chain (no later waiter): preserves mutual-exclusion semantics.
if (this.locks.get(sessionId) === settled) this.locks.delete(sessionId);
});
this.locks.set(sessionId, settled);
return next;
}
}
/** The session runtime: one entry per live Session, task mutex, approvals, streaming. */
export abstract class Sessions extends Interface<
Pick<
SessionManager,
| "statusOf"
| "liveSessions"
| "pendingApprovalCount"
| "pendingApprovals"
| "pendingFollowUpCount"
| "pendingSteeringOf"
| "subagentsOf"
| "sendToSubagent"
| "abortSubagentRun"
| "pendingFollowUpsOf"
| "liveFragments"
| "pendingInputs"
| "pendingBootstrap"
| "activeCountForAgent"
| "invalidateAgentRuntimes"
| "invalidateProjectRuntimes"
| "assertCanAcceptTask"
| "startTask"
| "startGoal"
| "startCompact"
| "startSwitch"
| "onModelChanged"
| "decideApproval"
| "steer"
| "recallSteering"
| "recallFollowUp"
| "retryNow"
| "abortTask"
| "listProcesses"
| "probeProcessServices"
| "killProcess"
| "removeProcess"
| "abortProject"
| "beginAgentDeletion"
| "endAgentDeletion"
| "beginSessionDeletion"
| "endSessionDeletion"
| "atIdleBoundary"
| "shutdown"
| "sweepIdle"
>
>() {}
export abstract class SessionServiceIface extends Interface<
Pick<
SessionServiceImpl,
| "toInfo"
| "hasTrace"
| "listSessions"
| "sessionStats"
| "createSession"
| "defaultSandbox"
| "pickSandbox"
| "updateSandbox"
| "latestTracePath"
| "adoptUnmanagedTraceSessions"
>
>() {}
/** The per-spawn policies every Session's command environment is built with. */
@Interface()
export abstract class SessionEnv {
abstract proxyEnv(): ProxyEnvPolicy | null;
abstract controlEnv(ctx: ControlEnvContext): Record<string, string>;
/** The directories at the FRONT of every command's PATH: the harness's own CLI shim (see CreateAgentOptions.pathPrepend). */
abstract pathPrepend(): string[];
abstract confineSpawn(ctx: ControlEnvContext): SpawnConfiner | null;
}
@Module()
export class SessionsModule {
@Use() private readonly config!: Config;
@Use() private readonly channels!: Channels;
@Use() private readonly authState!: AuthState;
@Use() private readonly clock!: Clock;
@Use() private readonly sessionLoaders!: SessionLoaders;
@Use() private readonly titleGenerators!: TitleGenerators;
@Use() private readonly log!: Log;
@Use() private readonly settings!: Settings;
@Use() private readonly sessionsRepo!: SessionIndex;
@Use() private readonly sources!: SessionOrigins;
@Use() private readonly recorder!: UsageRecording;
@Use() private readonly errors!: Errors;
@Use() private readonly modelScopeAuth!: ModelScopeAuth;
@Use() private readonly projectConfig!: ProjectConfigStore;
@Use() private readonly traceIndex!: TraceIndex;
@Use() private readonly traceStore!: TraceIndexStore;
@Use(SandboxModule) private readonly sandbox!: Sandbox;
/** The Sandbox card's presets live in the sandbox's settings group. */
@Use() private readonly pluginConfig!: PluginConfig;
@Use() private readonly projectEvents!: ProjectEvents;
@Use() private readonly messagingRepo!: MessagingBindings;
/** Company-mode caches: which organization owns a Session (read at every command spawn). */
@Use() private readonly orgCache!: OrgCache;
@Provide() manager!: Sessions;
@Provide() sessionService!: SessionServiceIface;
@Provide() env!: SessionEnv;
setup() {
const { config, settings, authState } = this;
const log = (line: string) => this.log.line(line);
const channels = this.channels as ChannelHub;
const sessionsRepo = this.sessionsRepo;
const sources = this.sources;
const recorder = this.recorder;
const errors = this.errors;
const projectConfig = this.projectConfig;
const sandbox = this.sandbox as SandboxService;
const pluginConfig = this.pluginConfig;
const orgCache = this.orgCache;
const modelScopeAuth = this.modelScopeAuth;
const assembly: AgentAssembly = {
resolveModelApiKey: async ({ projectId, provider, modelId }) => {
if (provider !== MODELSCOPE_PROVIDER_ID) return undefined;
await modelScopeAuth.ensureFresh({ projectId, provider });
const apiKey = await projectConfig.getGroupApiKey(projectId, provider);
if (apiKey === undefined) throw modelCredentialMissing(modelId);
return apiKey;
},
};
projectConfig.setModelApiKeyResolver(assembly.resolveModelApiKey!);
// Which commands run confined, under which policy, by which backend is policy — the
// sandbox module's; core only carries the spawn seam, reached through this getter.
const env: SessionEnv = {
proxyEnv: (): ProxyEnvPolicy | null => {
if (!settings.getProxyForAgent()) return { mode: "strip" };
const url = settings.getProxyUrl();
return url === null ? null : { mode: "inject", url, noProxy: mergedNoProxy() };
},
controlEnv: (ctx: ControlEnvContext): Record<string, string> => {
const host =
config.host === "0.0.0.0" || config.host === "::"
? "127.0.0.1"
: (loopbackHostRoles(config.host)?.app ?? config.host);
const token = authState.apiToken;
const orgId = orgCache.ownerOfSession(ctx.sessionId)?.orgId ?? null;
return {
ADELIE_API_URL: `http://${host}:${config.port}`,
...(token !== null ? { ADELIE_API_TOKEN: token } : {}),
ADELIE_PROJECT_ID: ctx.projectId,
ADELIE_AGENT_ID: ctx.agentId,
ADELIE_SESSION_ID: ctx.sessionId,
// A desk or ticket session also learns its organization, so `penguin org` needs no
// --org-id inside it. Looked up per spawn from the cache the ledger and the tickets
// project into.
...(orgId !== null ? { ADELIE_ORG_ID: orgId } : {}),
};
},
// The directory core puts at the FRONT of PATH for every command an Agent runs (and for
// its hook scripts): the shim directory bootAppDeps wrote this harness's own `penguin`
// into. Derived from the config rather than passed along, so the platform half needs no
// new capability — and read for truth rather than for null, because a runtime older than
// this field publishes a config without it and wrote no shim either: no field, no
// directory, feature off, rather than a push declined over a PATH entry.
pathPrepend: (): string[] => (config.cliEntry ? [cliShimDir(config.root)] : []),
// Each Session confines under its OWN policy — the snapshot on its row, its root's for a
// subagent — so a settings change reaches only Sessions created after it. A row from
// before snapshots takes the settings at its first command and keeps them from then on.
confineSpawn: (ctx: ControlEnvContext) =>
sandbox.confinerFor(() => {
const root = manager.rootSessionOf(ctx.sessionId);
const row = sessionsRepo.findById(root);
if (row?.sandbox) return row.sandbox;
const snapshot = sandbox.currentSettings();
if (row !== null) sessionsRepo.updateSandbox(root, snapshot);
return snapshot;
}),
};
const notifyProjectUsers = (projectId: string, event: ServerEvent): void =>
this.projectEvents.notifyProjectUsers(projectId, event);
const titles = this.titleGenerators.create({
sessions: sessionsRepo,
channels,
recorder,
errors,
log,
notifyProjectUsers,
});
const manager = new SessionManager({
sessions: sessionsRepo,
channels,
loader: this.sessionLoaders.create(config.root, sources, {
proxyEnv: env.proxyEnv,
controlEnv: env.controlEnv,
pathPrepend: env.pathPrepend,
confineSpawn: env.confineSpawn,
assembly,
}),
sources,
recorder,
errors,
modelScopeAuth: this.modelScopeAuth,
titles,
log,
notifyProjectUsers,
// A person talking to a desk (the chat page, a bound bot) starts a new @-chain: the
// desk's next channel message is hop 1 again, whatever mention last woke it.
onHumanInput: (sessionId) => {
if (orgCache.ownerOfSession(sessionId) !== null) orgCache.setTriggerHop(sessionId, 0);
},
now: () => this.clock.now(),
});
const sessionService = new SessionService({
root: config.root,
sessions: sessionsRepo,
manager,
projectConfig,
sources,
traceIndex: this.traceIndex,
traceStore: this.traceStore,
proxyEnv: env.proxyEnv,
controlEnv: env.controlEnv,
notifyProjectUsers,
messagingChannel: (sessionId) => enabledMessagingChannel(this.messagingRepo, sessionId),
// Company mode: which organization owns a Session, so development mode's list can hide
// organization sessions and the company sidebar can group its own. The caches are a
// projection of the organization's files, rebuilt every reconcile pass, so a row that
// has not been projected yet reads as an ordinary Session for one pass — never as the
// wrong organization.
orgIdOfSession: (sessionId) => orgCache.ownerOfSession(sessionId)?.orgId,
orgIdsOfProject: (projectId) => orgCache.orgIdsOfProject(projectId),
pathPrepend: env.pathPrepend,
confineSpawn: env.confineSpawn,
assembly,
sandboxDefaults: () => sandbox.currentSettings(),
sandboxDimensions: () => [...new Set(sandbox.backends().flatMap((b) => b.dimensions))],
sandboxUnavailable: () => sandbox.failures(),
sandboxBackends: () => sandbox.backends().map((b) => b.name),
// The Sandbox card's presets, read per view: a rename there reaches the next read.
sandboxPresets: () =>
sandboxPresetsOf(pluginConfig.schema(SANDBOX_GROUP), pluginConfig.get(SANDBOX_GROUP)),
sandboxSwitchOn: () => sandboxEnabledOf(pluginConfig.get(SANDBOX_GROUP)),
// The default preset's approval mode, while the switch is on.
sandboxDefaultApproval: () =>
sandboxStartOf(pluginConfig.schema(SANDBOX_GROUP), pluginConfig.get(SANDBOX_GROUP))
.approvalMode,
});
this.manager = manager;
this.sessionService = sessionService;
this.env = env;
}
}
/** Builds the loader a manager runs sessions through; a test stands in a fake session. */
@Interface()
export abstract class SessionLoaders {
abstract create(
root: string,
sources: Opaque<"SessionOrigins", SessionOrigins>,
env: Opaque<"SessionLoaderEnv", Parameters<typeof createCoreSessionLoader>[2]>,
): Opaque<"SessionLoader", SessionLoader>;
}
@Component()
export class CoreSessionLoaders implements SessionLoaders {
create(
root: string,
sources: SessionOrigins,
env: Parameters<typeof createCoreSessionLoader>[2],
): SessionLoader {
return createCoreSessionLoader(root, sources, env);
}
}
/** Builds the title generator; a test stands in a notifier that never calls a model. */
@Interface()
export abstract class TitleGenerators {
abstract create(
deps: Opaque<"TitleGeneratorDeps", ConstructorParameters<typeof TitleGenerator>[0]>,
): Opaque<"TitleNotifier", TitleNotifier>;
}
@Component()
export class DefaultTitleGenerators implements TitleGenerators {
create(deps: ConstructorParameters<typeof TitleGenerator>[0]): TitleNotifier {
return new TitleGenerator(deps);
}
}