@prismshadow/penguin-server 0.2.1 → 0.2.3

package/dist/api/types.d.ts

@@ -1,4 +1,4 @@
-import { OmniMessage, ToolCallPayload } from '@prismshadow/penguin-core/omnimessage';
+import { OmniMessage, ToolCallPayload, CompactionMode } from '@prismshadow/penguin-core/omnimessage';
 import { ThinkingLevelName, ToolDefinitionConfig, MCPServerConfig } from '@prismshadow/penguin-core/interfaces';
 
 /**
@@ -49,8 +49,9 @@ interface AuthResponse {
 interface MeResponse {
     user: UserInfo;
     /**
-     * Whether Workspace HTML previews open on a separate origin (see design §
-     * "Workspace 文件预览"). False means this deployment has no usable preview origin —
+     * Whether Workspace HTML previews open on a separate origin (the loopback
+     * counterpart of the App host, or PENGUIN_PREVIEW_ORIGIN when set). False means this
+     * deployment has no usable preview origin —
      * the App is reached on something other than a loopback name and
      * PENGUIN_PREVIEW_ORIGIN is unset — so previews fall back to the same-origin sandbox,
      * where `localStorage`, cookies and third-party embeds do not work. Computed per
@@ -61,7 +62,7 @@ interface MeResponse {
      * Whether this server runs in desktop mode (spawned by the desktop shell with
      * PENGUIN_DESKTOP_TOKEN). The web app then hides the logout entry, the
      * initial-password banner and the self-update entry, and omits the old-password
-     * field when changing the password. See design § "桌面端原型".
+     * field when changing the password.
      */
     desktopMode: boolean;
     /**
@@ -71,6 +72,38 @@ interface MeResponse {
      * token) may omit it.
      */
     sessionVia: "password" | "desktop";
+    /**
+     * The upload limits currently in force, so the composer can refuse an oversize pick before
+     * reading it and can name the real number in the message. They are admin-settable and ride
+     * `/api/me` rather than `/api/admin/settings` because every user's composer needs them, not
+     * just an admin's.
+     */
+    uploadLimits: UploadLimits;
+}
+/**
+ * Upload limits as the web app sees them: whole MB, the same unit the admin form uses, so the
+ * number in the error message is the number the admin typed.
+ */
+interface UploadLimits {
+    /** Per-file cap for composer file attachments. */
+    attachmentMaxMb: number;
+    /** Per-message total of decoded attachment bytes. */
+    attachmentTotalMb: number;
+    /** Per-message file count. Fixed server-side, not admin-settable. */
+    attachmentMaxCount: number;
+    /**
+     * Per-image cap for images that ride the conversation inline. Fixed server-side and
+     * deliberately far below the attachment cap — an inline image enters the conversation and the
+     * Trace, where its size is paid again on every history page and every resume.
+     */
+    imageMaxMb: number;
+    /**
+     * The range the two admin-settable limits may be set to. Carried here so the admin form states
+     * the real bounds without compiling its own copy of them — the server is the only place that
+     * decides how large an upload it can survive.
+     */
+    attachmentLimitMinMb: number;
+    attachmentLimitMaxMb: number;
 }
 interface PasswordChangeRequest {
     /** Omitted only by desktop-established sessions (desktop mode); required otherwise. */
@@ -94,6 +127,77 @@ interface AdminPasswordResetRequest {
     /** New initial password (at least 8 characters); resets invalidate all of the user's sessions. */
     password: string;
 }
+/**
+ * Admin-level server-global settings (SQLite server_settings):
+ * two independent proxy switches sharing one optional explicit address. In every
+ * on-state the effective NO_PROXY always includes localhost/127.0.0.1/::1 (loopback is
+ * never proxied), and changes apply to newly initiated connections/spawns immediately —
+ * no restart.
+ */
+interface ServerSettings {
+    /**
+     * "Application uses the proxy" (default on): the server's own outbound traffic (LLM
+     * requests, the update check, image fetches). On with `proxyUrl` set = that address
+     * for both http and https; on without an address = the proxy environment variables
+     * HTTP_PROXY / HTTPS_PROXY (both spellings); off = always direct.
+     */
+    proxyForApp: boolean;
+    /**
+     * "Agent environment uses the proxy" (default on): agent command subprocess
+     * environments. On with `proxyUrl` set = HTTP_PROXY / HTTPS_PROXY (plus lowercase
+     * twins) injected as that address with the merged NO_PROXY, overriding inherited
+     * values; on without an address = the host environment passes through unchanged;
+     * off = the proxy variables are stripped (NO_PROXY kept).
+     */
+    proxyForAgent: boolean;
+    /**
+     * The shared explicit proxy address (a canonical URL — http(s):// or socks5:// /
+     * socks://), or null = follow the proxy environment variables. When set it takes
+     * precedence over HTTP_PROXY / HTTPS_PROXY wherever the owning switch is on.
+     */
+    proxyUrl: string | null;
+    /**
+     * Per-file cap for composer file attachments, in whole MB (default 100). Applies to the very
+     * next upload — the validators read it per request, nothing is snapshotted at boot.
+     */
+    attachmentMaxMb: number;
+    /**
+     * Per-message total of decoded attachment bytes, in whole MB (default 120). Never below
+     * `attachmentMaxMb`, so a message may always carry one full-size attachment. The global request
+     * body cap is derived from this value (base64 inflates it by 4/3, plus headroom for one inline
+     * image and the JSON framing), which is why raising it needs no separate setting.
+     */
+    attachmentTotalMb: number;
+}
+interface ServerSettingsResponse {
+    settings: ServerSettings;
+}
+/** PUT body: every field optional, omitted fields keep their current value (mirrors prefs). */
+interface ServerSettingsUpdateRequest {
+    proxyForApp?: boolean;
+    proxyForAgent?: boolean;
+    /**
+     * New proxy address. Accepted forms: any proxy URL undici's dispatcher takes —
+     * `http://`, `https://`, `socks5://` / `socks://`, credentials allowed — or bare
+     * `host[:port]` (normalized to `http://…`; only normalized values are stored, and the
+     * response echoes the stored form). Empty/whitespace-only or null clears the address
+     * (follow the environment variables); anything else is 400 `invalid_proxy_url`.
+     */
+    proxyUrl?: string | null;
+    /**
+     * New per-file attachment cap in whole MB. Must be an integer between 1 and 200; anything else
+     * — a fraction, a string, 102400 for "100GB" — is 400 `invalid_attachment_limit` and writes
+     * nothing.
+     */
+    attachmentMaxMb?: number;
+    /**
+     * New per-message total attachment cap in whole MB. Same 1..200 integer range, and additionally
+     * must not be below the *effective* per-file cap (the value in the same PUT, or the stored one
+     * when this PUT does not change it) — a total below the per-file cap would make a legal single
+     * attachment unsendable. Violations are 400 `invalid_attachment_limit`.
+     */
+    attachmentTotalMb?: number;
+}
 /** User UI preferences (SQLite ui_prefs, free-form JSON; known keys declared here). */
 interface UiPrefs {
     theme?: "light" | "dark";
@@ -106,6 +210,8 @@ interface UiPrefs {
      * scanning (#139).
      */
     showCliSessions?: boolean;
+    /** The initial-password notice banner (app layout) was permanently dismissed by the user. */
+    initialPasswordBannerDismissed?: boolean;
     [key: string]: unknown;
 }
 interface PrefsResponse {
@@ -188,7 +294,7 @@ interface ModelInfo {
     /** Display name: explicit TOML field (user-edited) takes priority, then the built-in catalog; falls back to unset (frontend shows modelId). */
     displayName?: string;
     contextWindow?: number;
-    /** AgentHub client protocol (`openai`, etc.); defaults to AgentHub inferring it from modelId. */
+    /** AgentHub client protocol (`openai-chat`, `openai-responses`, etc.); defaults to AgentHub inferring it from modelId. */
     clientType?: string;
     /**
      * Whether image input (vision/multimodal) is supported: the TOML `vision` annotation takes
@@ -203,6 +309,13 @@ interface ModelInfo {
      * seeded per-Agent default (32000), which cannot fit into e.g. a 32k context window.
      */
     maxTokens?: number;
+    /**
+     * Per-model fast mode (TOML `fast_mode` annotation; user-only, never preset by the
+     * built-in catalog): when true, session requests opt into the provider's faster serving
+     * tier at premium pricing (AgentHub UniConfig `fast_mode`). Only `true` is reported;
+     * unset = off. Models without a fast tier reject requests carrying it.
+     */
+    fastMode?: boolean;
     pricing?: ModelPricingDto;
     /** Environment variable name to fall back to when api_key is empty (e.g. ANTHROPIC_API_KEY); unset if no known fallback. */
     envKey?: string;
@@ -245,6 +358,8 @@ interface ModelUpdateEntry {
     vision?: boolean;
     /** Per-model max output tokens, a positive integer (wins over the Agent config); omitted = inherit the Agent value (the annotation is cleared). */
     maxTokens?: number;
+    /** Per-model fast mode: only `true` is persisted; omitted or `false` clears the annotation (absent = off). */
+    fastMode?: boolean;
     pricing?: ModelPricingDto;
     /** Providing it overwrites and updates createdAt; omitting it keeps the existing value. */
     apiKey?: string;
@@ -285,6 +400,45 @@ interface ModelTestRequest {
     baseUrl?: string | null;
     /** AgentHub client protocol; required for unsaved custom models (otherwise the id can't be auto-routed). */
     clientType?: string;
+    /**
+     * Test with fast mode (the frontend always sends the form's current value, so an unsaved
+     * toggle — either direction — is what gets tested); omitted falls back to the stored
+     * annotation. Lets "Test connection" surface a fast-mode rejection before saving.
+     */
+    fastMode?: boolean;
+}
+/**
+ * Vision capability probe: sends one 1x1 image and a one-word prompt on this model's
+ * credential, to decide whether the models dialog's "supports vision" switch should be
+ * turned on. The body mirrors the connectivity test (same paired reference and same
+ * not-yet-saved overrides), so an unsaved model can be probed before it exists on disk.
+ *
+ * Unlike protocol detection this is a real, billed completion — an image request cannot be
+ * shaped to cost nothing — so it only ever runs when the user presses the control.
+ */
+interface ModelVisionDetectRequest {
+    provider: string;
+    modelId: string;
+    /** Newly entered API key (plaintext); the stored one backs the probe when omitted. */
+    apiKey?: string;
+    /** "Clear saved API key" is checked: do not fall back to the stored key. */
+    clearApiKey?: boolean;
+    /** Form's current base URL; null means "explicitly none" (as in the connectivity test). */
+    baseUrl?: string | null;
+    /** Protocol to speak, when the form has one; otherwise the stored/auto-routed client. */
+    clientType?: string;
+}
+/**
+ * Vision probe verdict. `supported` = the model took the image and answered; `unsupported`
+ * = it answered specifically that it will not take an image (a definitive negative, not an
+ * error); `failed` = the probe never got a usable answer (auth, network, an unrelated
+ * error), so nothing about the capability was learned and the setting is left alone.
+ */
+type ModelVisionOutcome = "supported" | "unsupported" | "failed";
+/** Vision probe result; `message` carries the truncated provider error for the failed case. */
+interface ModelVisionDetectResponse {
+    outcome: ModelVisionOutcome;
+    message?: string;
 }
 /**
  * Connectivity test result: carries round-trip latency when ok, and a reason on failure
@@ -305,6 +459,48 @@ interface ModelTestResponse {
     tps?: number;
     message?: string;
 }
+/**
+ * Protocol auto-detection (POST /api/projects/:p/models/detect, owner): probes which of
+ * AgentHub's generic protocol clients a custom base URL serves — `openai-responses` first,
+ * then `ant-messages`, then `openai-chat` — and reports the first hit. Used by the custom
+ * model dialog to fill `clientType` from the endpoint itself; costs no tokens (each probe
+ * is a minimal invalid request whose error reveals the protocol shape).
+ */
+interface ModelProtocolDetectRequest {
+    /** Base URL to probe (as typed in the form); each probe appends its protocol path. */
+    baseUrl: string;
+    /** Newly entered API key (plaintext); used for probe auth if provided. Detection also works keyless: a protocol-shaped 401/403 still proves the route. */
+    apiKey?: string;
+    /** "Clear saved API key" is checked: do not fall back to the stored key (probe the current draft). */
+    clearApiKey?: boolean;
+    /** Optional paired reference: when it names a stored entry and no apiKey is given, that entry's saved key backs the probes (mirrors the connectivity test). */
+    provider?: string;
+    modelId?: string;
+}
+/**
+ * One probe's outcome: `served` = the route answered in an API shape (including auth
+ * failures — 401/403 with a protocol-shaped body proves the route exists);
+ * `route_missing` = 404/405; `server_error` = 5xx (proves nothing about the path);
+ * `junk` = HTML / non-JSON / JSON matching no API shape; `timeout` / `network_error` =
+ * the request itself failed.
+ */
+type ProtocolProbeOutcome = "served" | "route_missing" | "server_error" | "junk" | "timeout" | "network_error";
+/** One probe, for debugging display: the probed URL derives from baseUrl only (never contains the key). */
+interface ModelProtocolProbeDto {
+    /** AgentHub client type this probe stands for (`openai-responses` / `ant-messages` / `openai-chat`). */
+    clientType: string;
+    /** Full URL probed (base URL + the protocol's path). */
+    url: string;
+    outcome: ProtocolProbeOutcome;
+    /** HTTP status, when a response arrived at all. */
+    status?: number;
+}
+/** Detection result: probes run sequentially and stop at the first served protocol, so `probes` lists only the ones actually run, in order. */
+interface ModelProtocolDetectResponse {
+    /** The first protocol the endpoint serves (an AgentHub client type); absent when none of the three matched. */
+    detected?: string;
+    probes: ModelProtocolProbeDto[];
+}
 /**
  * PUT /api/projects/:p/models/default (owner): narrow default-model switch — flips the same
  * top-level `default_model` the models page's whole-table PUT writes, without resending the
@@ -330,14 +526,14 @@ interface DefaultModelResponse {
 interface ChatDefaultsDto {
     /** Preselected Agent; must reference an existing Agent of the Project (400 unknown_agent). */
     agentId?: string;
-    /** Prefilled Workspace directory; absent/empty = auto temp directory. */
+    /** Prefilled Workspace directory; absent/empty = a temporary workspace. */
     workspace?: string;
     /** Prefilled approval mode; absent = the built-in "allow-all". */
     approvalMode?: ApprovalMode;
     /**
      * Fallback thinking level for Agents whose config has no explicit `model.thinking_level`
      * (resolution chain: Agent explicit > this project default > built-in "medium"). Never
-     * "none" — only the four selectable tiers.
+     * "none" — only the selectable tiers.
      */
     thinkingLevel?: Exclude<ThinkingLevelName, "none">;
 }
@@ -377,12 +573,16 @@ interface AgentSummary {
     toolCount: number;
     /** Agent State version number (the `version` in system_config.yaml; treated as 1 if missing). */
     version: number;
+    /** Whether the config's kernel stamp is behind the current defaults generation (a missing stamp counts as outdated) — drives the list card's update hint. */
+    kernelOutdated: boolean;
     /** Vault key count (number of keys in agent_state/.vault.toml). */
     vaultKeyCount: number;
     /** Schedule count (number of .toml files under agent_state/schedule/, including invalid ones). */
     scheduleCount: number;
     /** Installed Skill count (number of agent_state/skills/<name>/ directories with a SKILL.md). */
     skillCount: number;
+    /** Memory count (topic files summed over the scope directories under agent_state/memory/, independent of the memory switch). */
+    memoryCount: number;
 }
 interface AgentsResponse {
     agents: AgentSummary[];
@@ -408,16 +608,69 @@ interface AgentCompactionConfigDto {
     mode?: "summarize" | "discard";
     prompt?: string;
 }
+/** Memory config. All fields report effective values (a config with no `memory` section reads as enabled with the built-in prompts, matching core); the prompts are edited on the Memory tab. */
+interface AgentMemoryConfigDto {
+    enabled: boolean;
+    /** The always-injected half of the `{{MEMORY}}` block (carries `{{USER_MEMORY_INDEX}}`; the User directory is literal text). */
+    prompt: string;
+    /** Appended only in a persistent Workspace (carries `{{WORKSPACE_MEMORY_INDEX}}` and the rendered `{{WORKSPACE_MEMORY_DIR}}` directory). */
+    workspacePrompt: string;
+}
+/**
+ * Vault prompt-injection config, edited on the Vault tab. `enabled` / `prompt` report
+ * effective values (a config with no `vault` section reads as enabled with the built-in
+ * prompt, matching core); the last two are read-only facts computed from the stored template.
+ */
+interface AgentVaultConfigDto {
+    /** Whether the Vault section enters the model context (values are injected into subprocesses regardless). */
+    enabled: boolean;
+    /** The `{{VAULT}}` block (carries `{{VAULT_KEYS}}`). */
+    prompt: string;
+    /** Whether the stored template carries `{{VAULT}}`; POST …/vault/template-placeholder inserts (or migrates to) it explicitly. */
+    templateHasPlaceholder: boolean;
+    /** Whether the stored template still carries the legacy hardcoded # Vault section verbatim (a pre-`{{VAULT}}` Agent) — the migration case of the insert endpoint. */
+    legacySectionPresent: boolean;
+}
+/** Skills prompt-injection config, edited on the Skills tab; same field semantics as AgentVaultConfigDto, for `{{SKILLS}}` / `{{SKILL_METADATA}}` and the legacy # Skills section. */
+interface AgentSkillsConfigDto {
+    /** Whether the Skills section enters the model context (installed skills remain explicitly invocable regardless). */
+    enabled: boolean;
+    /** The `{{SKILLS}}` block (carries `{{SKILL_METADATA}}`). */
+    prompt: string;
+    /** Whether the stored template carries `{{SKILLS}}`; POST …/skills/template-placeholder inserts (or migrates to) it explicitly. */
+    templateHasPlaceholder: boolean;
+    /** Whether the stored template still carries the legacy hardcoded # Skills section verbatim — the migration case of the insert endpoint. */
+    legacySectionPresent: boolean;
+}
+/** Schedules prompt-injection config, edited on the Schedules tab. No legacy field: Schedules never had a hardcoded template section. */
+interface AgentSchedulesConfigDto {
+    /** Whether the Scheduled Tasks section enters the model context (the server fires configured tasks regardless). */
+    enabled: boolean;
+    /** The `{{SCHEDULES}}` block (carries `{{SCHEDULE_LIST}}`). */
+    prompt: string;
+    /** Whether the stored template carries `{{SCHEDULES}}`; POST …/schedules/template-placeholder inserts it explicitly. */
+    templateHasPlaceholder: boolean;
+}
 /** Structured view of system_config.yaml (for the edit form). */
 interface AgentConfigDto {
     name?: string;
     description?: string;
     /** Agent State version number (treated as 1 if missing; shown in the settings page overview). */
     version: number;
+    /** The stored kernel stamp (`kernel_version`): which defaults generation the config is based on; null when the config predates the kernel-version mechanism. */
+    kernelVersion: string | null;
+    /** The current defaults generation (core's KERNEL_VERSION) — what a kernel update would stamp. */
+    kernelLatest: string;
+    /** Whether the stamp is behind kernelLatest (a missing stamp counts as outdated). */
+    kernelOutdated: boolean;
     systemPrompt: string;
     maxTurns?: number;
     model?: AgentModelConfigDto;
     compaction?: AgentCompactionConfigDto;
+    memory: AgentMemoryConfigDto;
+    vault: AgentVaultConfigDto;
+    skills: AgentSkillsConfigDto;
+    schedules: AgentSchedulesConfigDto;
     toolsBuiltin: ToolDefinitionConfig[];
     mcpServers: MCPServerConfig[];
 }
@@ -430,6 +683,29 @@ interface AgentConfigResponse {
     stateDir: string;
     activeSessionCount: number;
 }
+/**
+ * POST …/config/kernel-update result: the smart merge's outcome (core's applyKernelUpdate).
+ * Paths are dotted config leaves (`system_prompt`, `memory.prompt`, `tools.builtin.<name>`…)
+ * in defaults-traversal order; the client maps them to display names.
+ */
+interface AgentKernelUpdateResponse {
+    /** Leaves advanced to the new default (previously missing, or an untouched old default). */
+    advanced: string[];
+    /** Leaves kept because the stored value matches no recorded defaults generation (user customizations, kept conservatively). */
+    kept: string[];
+    /** The kernel stamp written (the current defaults generation). */
+    kernelVersion: string;
+}
+/** POST …/config/mcp-test result: reachability of one MCP Server entry. */
+interface McpServerTestResponse {
+    ok: boolean;
+    /** Discovered tool names (`mcp__<server>__<tool>`), present on success. */
+    tools?: string[];
+    /** Failure detail (connect error, timeout, server stderr tail), present on failure. */
+    error?: string;
+    /** Connect + discovery wall time (both outcomes) — the models test reports latency, this matches. */
+    latencyMs?: number;
+}
 /** PUT any subset: only provided keys are updated (remaining YAML content and comments preserved); agentsMd overwrites the whole file. */
 interface AgentConfigUpdateRequest {
     agentsMd?: string;
@@ -440,10 +716,73 @@ interface AgentConfigUpdateRequest {
         maxTurns?: number;
         model?: AgentModelConfigDto;
         compaction?: AgentCompactionConfigDto;
+        memory?: Partial<AgentMemoryConfigDto>;
+        /** Only the writable half of the DTO — the template facts (templateHasPlaceholder / legacySectionPresent) are computed, never written. */
+        vault?: {
+            enabled?: boolean;
+            prompt?: string;
+        };
+        skills?: {
+            enabled?: boolean;
+            prompt?: string;
+        };
+        schedules?: {
+            enabled?: boolean;
+            prompt?: string;
+        };
         toolsBuiltin?: ToolDefinitionConfig[];
         mcpServers?: MCPServerConfig[];
     };
 }
+/** One Memory scope directory: `agent_state/memory/user/` or `agent_state/memory/<workspaceKey>/`. */
+interface MemoryScopeInfo {
+    /** Directory name under `memory/`: `user`, or a Workspace's `<safe-basename>-<hash>` key. */
+    scopeKey: string;
+    /** `user` — the scope every Session reads, temporary Workspaces included; `workspace` — one Workspace's scope. */
+    kind: "user" | "workspace";
+    /** Workspace path the key was derived from, read from the directory's `.workspace` marker; unset on the user scope (it stands for no path) and for a directory edited by hand. */
+    workspacePath?: string;
+    /** Number of Markdown topic files in the directory (the `MEMORY.md` index not counted). */
+    fileCount: number;
+    /** Most recent topic-file mtime in the directory (ISO 8601); unset when the directory holds no topic file. */
+    updatedAt?: string;
+}
+/** One Memory topic file, as listed (frontmatter only — the body is fetched per file). */
+interface MemoryFileInfo {
+    /** File name inside the scope directory, e.g. `prefers-pnpm.md`. */
+    name: string;
+    /** Frontmatter `name`; falls back to the file name. */
+    title: string;
+    /** Frontmatter `description`; empty when the file declares none. */
+    description: string;
+    /** Frontmatter `updated_at`, verbatim. */
+    updatedAt?: string;
+    /** File size in bytes. */
+    size: number;
+    /** File mtime (ISO 8601). */
+    modifiedAt: string;
+}
+/** GET …/memory — the tab's landing payload: the switch and every scope group, user scope first. */
+interface MemoryOverviewResponse {
+    /** Whether Memory reaches the model context (the Agent-level switch). */
+    enabled: boolean;
+    /** Whether the prompt template carries the `{{MEMORY}}` placeholder. An Agent created before Memory has none and injects nothing; POST …/memory/template-placeholder inserts it explicitly. */
+    templateHasMemory: boolean;
+    /** Absolute path of `agent_state/memory/`. */
+    memoryDir: string;
+    scopes: MemoryScopeInfo[];
+}
+/** GET …/memory/scopes/:key/files */
+interface MemoryFilesResponse {
+    scopeKey: string;
+    files: MemoryFileInfo[];
+}
+/** GET …/memory/scopes/:key/files/:name */
+interface MemoryFileResponse {
+    scopeKey: string;
+    file: MemoryFileInfo;
+    content: string;
+}
 interface SessionInfo {
     sessionId: string;
     projectId: string;
@@ -454,11 +793,35 @@ interface SessionInfo {
     modelId: string;
     workspace: string;
     approvalMode: ApprovalMode;
+    /**
+     * Thinking level pinned for this Session (set via PATCH; the Web App's in-chat picker).
+     * Unset = never pinned: runs that carry no level of their own fall back to the Agent
+     * config's `model.thinking_level`, so config edits keep taking effect. Once pinned it
+     * survives reloads and applies to every later run of this Session, and an Agent-config
+     * change no longer moves it.
+     */
+    thinkingLevel?: ThinkingLevelName;
     /** Short title auto-generated by the model after the first turn; unset until generated (frontend shows "New Chat"). */
     title?: string;
     /** Session source (for list badges/folders), derived from core session_meta — the single source of truth (not stored in the DB); unset for user-created sessions. */
     source?: SessionSource;
     createdAt: string;
+    /**
+     * Last activity the server drove for this Session (ISO 8601, same convention as
+     * createdAt), monotonic — it never moves backwards. Set to createdAt at creation, then
+     * stamped when a run starts and again when it ends; a run here is one Task, one
+     * compaction, or one whole goal loop (every round of a goal belongs to a single run, so
+     * an N-round goal stamps twice, not 2N times).
+     *
+     * Two kinds of row therefore stay at createdAt no matter how busy they look: Sessions
+     * adopted from a CLI Trace (this server drives none of their runs) and subagent rows
+     * (their work is driven through the parent Session's entry). Reading real activity for
+     * those would mean consulting the Trace tree, which this field deliberately does not do.
+     *
+     * Rows that predate the field are backfilled once at startup from the Session's most
+     * recent request timestamp, falling back to createdAt.
+     */
+    lastActiveAt: string;
     status: SessionStatus;
     /** Number of approvals awaiting human decision (a persisted count outside server events, for list badges). */
     pendingApprovalCount: number;
@@ -528,11 +891,36 @@ interface SessionCreateRequest {
 interface SessionCreateResponse {
     session: SessionInfo;
 }
+/** Immutable location of one record in a Session's append-only Trace. */
+interface TracePosition {
+    /** Trace shard index (`001` on disk becomes `1`). */
+    fileIndex: number;
+    /** Zero-based record ordinal within the parsed shard. */
+    ordinal: number;
+}
+/** History-only transport metadata; `tracePosition` is never persisted into Trace JSONL. */
+type HistoryMessage = OmniMessage & {
+    tracePosition?: TracePosition;
+};
+interface SessionForkRequest {
+    /** The final root assistant text record of the completed Task to keep. */
+    position: TracePosition;
+}
+interface SessionForkResponse {
+    session: SessionInfo;
+}
 interface SessionResponse {
     session: SessionInfo;
 }
 interface SessionPatchRequest {
     approvalMode?: ApprovalMode;
+    /**
+     * Pin this Session's thinking level (`none | low | medium | high | xhigh | max`, anything else
+     * is a 400). It applies to every later run of the Session that doesn't carry its own
+     * level, and replaces the Agent-config fallback for this Session. There is no unpin:
+     * the picker only offers concrete levels.
+     */
+    thinkingLevel?: ThinkingLevelName;
     /** Archive / unarchive (default list hides archived). */
     archived?: boolean;
     /** Manual rename; non-empty string, overrides the auto-generated title. */
@@ -581,7 +969,7 @@ interface MessagesPageInfo {
     before?: string;
     /**
      * Outline turns (the Web conversation outline's entry rule) opened BEFORE this
-     * window: the client offsets its global `第 N 轮` numbering by this, so a partial
+     * window: the client offsets its global "round N" numbering by this, so a partial
      * window never mis-numbers. 0 when the window starts at the beginning.
      */
     earlierTurns: number;
@@ -600,7 +988,7 @@ interface MessagesPageInfo {
 }
 /** Message history: the full messages and events from concatenating all of this Session's Trace files in order (excludes partial_*). */
 interface MessagesResponse {
-    messages: OmniMessage[];
+    messages: HistoryMessage[];
     /**
      * Present only while the Session is running/compacting: the in-progress stream tail
      * (open streaming fragments + the channel cursor they cover), so a client joining
@@ -623,17 +1011,26 @@ interface MessagesResponse {
 type TaskInputPart = {
     type: "text";
     text: string;
-} | {
+}
+/**
+ * An image that rides the conversation inline, as a base64 `data:` URL or an http(s) URL.
+ * A data URL is capped at 20MB (413 `image_too_large`) — a fixed limit that does NOT follow
+ * the admin-settable attachment cap, because an inline image is written into the Trace and
+ * read back on every history page and every resume.
+ */
+ | {
     type: "image_url";
     imageUrl: string;
 }
 /**
  * File attachment (the composer's "+" menu): `dataUrl` is a base64 `data:` URL of the
- * file's bytes, capped at 10MB each (413 `file_too_large` beyond that; the request as a
- * whole still has to fit the global 20MB body limit). The server writes it into the
- * Session scratchpad under a sanitized name and appends an `[attached file: <path>]` line
- * to the message text — the bytes never enter the conversation, the model opens the file
- * by path. `fileName` is the original name (no path separators, no `..`).
+ * file's bytes, capped per file and per message by the admin-settable upload limits
+ * (defaults 100MB / 120MB; 413 `file_too_large` / `payload_too_large` / `too_many_files`,
+ * and the request as a whole still has to fit the body cap those limits derive). The
+ * server writes it into the Session scratchpad under a sanitized name and appends an
+ * `[attached file: <path>]` line to the message text — the bytes never enter the
+ * conversation, the model opens the file by path. `fileName` is the original name (no path
+ * separators, no `..`).
  */
  | {
     type: "file";
@@ -644,9 +1041,10 @@ interface TaskCreateRequest {
     input: TaskInputPart[];
     /**
      * Thinking level for this Task's LLM requests (a per-turn parameter; one of
-     * `none | low | medium | high | xhigh`, anything else is a 400). Omitted = falls back to
-     * the session's default (the Agent config's `model.thinking_level`). A queued follow-up
-     * (`queueIfBusy`) keeps its level and applies it when it auto-starts.
+     * `none | low | medium | high | xhigh | max`, anything else is a 400). Omitted = falls back to
+     * the Session's pinned level (`SessionInfo.thinkingLevel`) and, when that is unset too,
+     * to the Agent config's `model.thinking_level`. A queued follow-up (`queueIfBusy`) keeps
+     * its level and applies it when it auto-starts.
      */
     thinkingLevel?: ThinkingLevelName;
     /**
@@ -721,6 +1119,8 @@ interface SteerRequest {
  * stream, and the whole list drops when the run exits (core discards undelivered steering).
  */
 interface PendingSteeringInfo {
+    /** Server-assigned id, stable for the entry's queued lifetime: the handle DELETE /steer/:steerId recalls it by. */
+    id: string;
     /** The message text as accepted (trimmed); may be empty when images/files carry the message. */
     text: string;
     /** Number of images that rode along. */
@@ -728,6 +1128,43 @@ interface PendingSteeringInfo {
     /** Number of file attachments that rode along. */
     files: number;
 }
+/**
+ * One follow-up task queued with `queueIfBusy` but not yet auto-started. Carried on
+ * `task_state` events and the SSE subscribe snapshot (like `pendingSteering`) so the
+ * composer can show each queued message's content with a recall affordance; entries leave
+ * the list when they auto-start on idle — or when DELETE /follow-ups/:followUpId recalls one.
+ */
+interface PendingFollowUpInfo {
+    /** Server-assigned id, stable for the entry's queued lifetime: the handle DELETE /follow-ups/:followUpId recalls it by. */
+    id: string;
+    /** The queued input's text parts, joined; may be empty when images/files carry the message. */
+    text: string;
+    /** Number of images in the queued input. */
+    images: number;
+    /** Number of file attachments in the queued input. */
+    files: number;
+}
+/**
+ * Response of the two recall endpoints — DELETE /api/sessions/:id/steer/:steerId and
+ * DELETE /api/sessions/:id/follow-ups/:followUpId: the withdrawn message's original content,
+ * for the composer to restore into the input box for editing and resending (#287). File
+ * attachments are read back from the Session scratchpad (then deleted from it); one that
+ * disappeared meanwhile is omitted rather than failing the recall. 409 `not_pending` when
+ * the entry is no longer queued — steering already delivered to the model, or a follow-up
+ * already auto-started (or unknown id either way).
+ */
+interface RecalledMessageResponse {
+    text: string;
+    /** The images as submitted (`data:` / http(s) URLs). */
+    images: string[];
+    /** The file attachments, re-encoded as base64 data URLs (the shape the composer submits them in). */
+    files: {
+        fileName: string;
+        dataUrl: string;
+    }[];
+    /** Follow-up recall only: the per-turn thinking level the entry was queued with, when one was. */
+    thinkingLevel?: ThinkingLevelName;
+}
 interface ApprovalDecisionRequest {
     decision: "allow" | "deny";
 }
@@ -740,6 +1177,23 @@ interface ApprovalDecisionRequest {
 interface RetryNowResponse {
     skipped: boolean;
 }
+/**
+ * One background command process started by the Session (an exec_command promoted past
+ * its yield window). Served from the ACTIVE runtime only: a session whose runtime entry
+ * is gone truthfully reports an empty list.
+ */
+interface SessionProcessInfo {
+    processId: string;
+    /** OS pid of the process-group leader; null when the spawn itself failed. */
+    pid: number | null;
+    cmd: string;
+    cwd: string;
+    startedAt: string;
+    running: boolean;
+}
+interface SessionProcessesResponse {
+    processes: SessionProcessInfo[];
+}
 /** Docs: /docs/server-api § "Streaming (SSE)". */
 type ServerEvent = 
 /**
@@ -758,6 +1212,8 @@ type ServerEvent =
     queued?: number;
     /** Steering messages queued but not yet delivered (absent = none): lets the composer's hint and its content survive reloads. */
     pendingSteering?: PendingSteeringInfo[];
+    /** Queued follow-up tasks awaiting auto-start (absent = none): per-entry content + recall handle, alongside the `queued` count. */
+    pendingFollowUps?: PendingFollowUpInfo[];
 }
 /** The model-generated title after the first turn has been persisted (for in-place list updates). */
  | {
@@ -765,6 +1221,32 @@ type ServerEvent =
     sessionId: string;
     title: string;
 }
+/**
+ * The user-channel counterpart of `task_state`: the same run-state flip, named by
+ * `sessionId`, delivered on GET /api/events.
+ *
+ * `task_state` is session-scoped and deliberately carries no id, so it only ever reaches the
+ * one conversation a tab has subscribed to — every OTHER row in that tab's Session list would
+ * otherwise keep whatever status its last list fetch returned. This event exists so the list
+ * can stay live without polling; the per-Session contract is unchanged.
+ *
+ * `lastActiveAt` and `hasTrace` are the row's own fields as they stand after the flip, both
+ * written just before publishing (`markDriven` at run start sets has_trace and stamps
+ * last_active_at; `touchLastActive` stamps again at run end). They are what let a list act on
+ * the flip without refetching: the stamp separates "this finished while I was looking
+ * elsewhere" from "this finished before I last looked", and `hasTrace` separates a Session
+ * that has now run from one that never has — a first run would otherwise settle back into the
+ * blank "never ran" row the client still believes in.
+ *
+ * Published only to the user channels of the Project's owner and members.
+ */
+ | {
+    type: "session_state";
+    sessionId: string;
+    state: SessionStatus;
+    lastActiveAt: string;
+    hasTrace: boolean;
+}
 /** Last-Event-ID has been evicted from the buffer: the frontend should re-fetch the history endpoint before continuing to consume this connection. */
  | {
     type: "resync_required";
@@ -783,6 +1265,11 @@ type ServerEvent =
  | {
     type: "hello";
 }
+/** The served web assets were hot-swapped by a platform upgrade: clients reload to pick them up. */
+ | {
+    type: "web_updated";
+    rev: string;
+}
 /** New session registered (pushed over the parent session's channel for subagent sessions): frontend refreshes the list in place. */
  | {
     type: "session_created";
@@ -885,12 +1372,22 @@ interface TraceTaskStats {
     taskIndex: number;
     /**
      * This turn is a **compaction turn** (compaction forms its own turn); the UI marks it with
-     * a "Compaction" badge accordingly. It's treated the same as a user turn: it has Token /
+     * a badge accordingly. It's treated the same as a user turn: it has Token /
      * cost / duration / TPS, and **counts normally toward global stats** — the global totals are
      * just the sum of the per-turn cards below, the two scopes match, so adding up the per-turn
      * numbers must equal the total.
      */
     compaction?: boolean;
+    /**
+     * Which kind of compaction turn it is, from the turn's `compaction_begin`. Additive beside
+     * the flag rather than folded into it: `compaction` stays the sole gate on "is this a
+     * compaction turn", so a client that only knows the boolean keeps working unchanged, and one
+     * that reads this can name the turn for what it did — the two modes are different operations,
+     * and only `summarize` actually compacts anything (`discard` drops the old context outright).
+     * Absent on a turn analyzed before this field existed, or whose `compaction_begin` carried no
+     * mode; treat an absent value as `summarize`, which is what the badge said before the split.
+     */
+    compactionMode?: CompactionMode;
     /**
      * This turn's message index range within the **entire file** (inclusive). A single
      * sequential scan on the server tells which turn each message belongs to; the frontend
@@ -1007,6 +1504,23 @@ interface TraceToolSpan {
     /** The Task that initiated this tool (grouped with its tool_call segment): async output belongs to this Task even if it arrives after request_end. */
     taskIndex: number;
 }
+/**
+ * Non-tool auxiliary phase on the timeline: rendered in its own lane under the "other"
+ * legend category — deliberately not a tool span, since nothing was called. Currently the
+ * first run's MCP connect + discovery (from the mcp_connect_begin/end event pair).
+ */
+interface TraceOtherSpan {
+    /** Unique bar key (e.g. `mcp-connect-<beginTs>`). */
+    key: string;
+    /** Lane label, e.g. "mcp connect". */
+    name: string;
+    startTs: string;
+    endTs: string;
+    /** Attached to the Task that follows the phase (same grouping convention as toolSpans). */
+    taskIndex: number;
+    /** True when the phase ended with failures (some servers unreachable) or was aborted. */
+    failed?: boolean;
+}
 interface UsageTrendPointInTrace {
     ts: string;
     requestTotal: number;
@@ -1028,6 +1542,8 @@ interface TraceAnalysisResponse {
     modelSegments: TraceModelSegment[];
     /** Execution timeline: each tool's approval/execution phases (independent lane, can overlap with model decoding). */
     toolSpans: TraceToolSpan[];
+    /** Execution timeline: non-tool auxiliary phases (their own "other" lanes — currently the first run's MCP connect + discovery). */
+    otherSpans: TraceOtherSpan[];
     /** Number of request_end events with status ∈ {timeout, malformed}. */
     reconnectCount: number;
     /** Number of compaction_begin events. */
@@ -1451,4 +1967,4 @@ interface UpdateRunResponse {
     needsRestart: boolean;
 }
 
-export type { AdminPasswordResetRequest, AdminUserCreateRequest, AdminUserCreateResponse, AdminUsersResponse, AgentCompactionConfigDto, AgentConfigDto, AgentConfigResponse, AgentConfigUpdateRequest, AgentCreateRequest, AgentCreateResponse, AgentImportRequest, AgentImportResponse, AgentModelConfigDto, AgentSkillsResponse, AgentSummary, AgentTraceDateGroup, AgentTraceFileRef, AgentTraceSessionEntry, AgentTraceSessionFile, AgentTraceSessionGroup, AgentTracesResponse, AgentsResponse, ApprovalDecisionRequest, ApprovalMode, AuthLoginRequest, AuthResponse, BenchmarkCaseScore, BenchmarkCaseSummary, BenchmarkCasesResponse, BenchmarkEvaluation, BenchmarkRunScore, BenchmarkSummary, BenchmarksResponse, CaseMaterial, ChatDefaultsDto, CredentialInfo, DefaultModelResponse, DefaultModelUpdateRequest, DirEntryInfo, DirListResponse, ErrorBody, FilesStatRequest, FilesStatResponse, GoalResponse, GoalServerEvent, GoalStateView, MeResponse, MemberAddRequest, MemberAddResponse, MemberInfo, MembersResponse, MessagesLiveTail, MessagesPageInfo, MessagesResponse, ModelInfo, ModelPricingDto, ModelRefDto, ModelTestRequest, ModelTestResponse, ModelUpdateEntry, ModelsResponse, ModelsUpdateRequest, PasswordChangeRequest, PendingSteeringInfo, PrefsResponse, ProjectCreateRequest, ProjectCreateResponse, ProjectRole, ProjectSummary, ProjectUpdateRequest, ProjectUpdateResponse, ProjectsResponse, RequestSpan, RetryNowResponse, ScheduleItem, ScheduleServerEvent, ScheduleStatus, ScheduleUpsertRequest, SchedulesResponse, ServerEvent, SessionCategory, SessionCategoryCounts, SessionCreateRequest, SessionCreateResponse, SessionInfo, SessionPatchRequest, SessionResponse, SessionSource, SessionStatus, SessionTracesResponse, SessionsResponse, SkillArchiveInstallRequest, SkillGroupItem, SkillInstallRequest, SkillLibraryResponse, SkillMetadataItem, SteerRequest, TaskCreateRequest, TaskCreateResponse, TaskInputPart, ToolCallSpan, TraceAnalysisResponse, TraceEventsResponse, TraceFileInfo, TraceImportRequest, TraceImportResponse, TraceModelSegment, TraceTaskStats, TraceToolSpan, UiPrefs, UpdateCheckResponse, UpdateRunResponse, UsageAgentCount, UsageBucket, UsageErrorCount, UsageErrorItem, UsageErrors, UsageErrorsPage, UsageGroupBy, UsageGroupRow, UsageResponse, UsageSuccessRate, UsageTrendPoint, UsageTrendPointInTrace, UserInfo, VaultEntryInfo, VaultEntryUpdate, VaultResponse, VaultUpdateRequest, VersionResponse, WorkspaceFileEntry, WorkspaceFilesResponse };
+export type { AdminPasswordResetRequest, AdminUserCreateRequest, AdminUserCreateResponse, AdminUsersResponse, AgentCompactionConfigDto, AgentConfigDto, AgentConfigResponse, AgentConfigUpdateRequest, AgentCreateRequest, AgentCreateResponse, AgentImportRequest, AgentImportResponse, AgentKernelUpdateResponse, AgentMemoryConfigDto, AgentModelConfigDto, AgentSchedulesConfigDto, AgentSkillsConfigDto, AgentSkillsResponse, AgentSummary, AgentTraceDateGroup, AgentTraceFileRef, AgentTraceSessionEntry, AgentTraceSessionFile, AgentTraceSessionGroup, AgentTracesResponse, AgentVaultConfigDto, AgentsResponse, ApprovalDecisionRequest, ApprovalMode, AuthLoginRequest, AuthResponse, BenchmarkCaseScore, BenchmarkCaseSummary, BenchmarkCasesResponse, BenchmarkEvaluation, BenchmarkRunScore, BenchmarkSummary, BenchmarksResponse, CaseMaterial, ChatDefaultsDto, CredentialInfo, DefaultModelResponse, DefaultModelUpdateRequest, DirEntryInfo, DirListResponse, ErrorBody, FilesStatRequest, FilesStatResponse, GoalResponse, GoalServerEvent, GoalStateView, HistoryMessage, McpServerTestResponse, MeResponse, MemberAddRequest, MemberAddResponse, MemberInfo, MembersResponse, MemoryFileInfo, MemoryFileResponse, MemoryFilesResponse, MemoryOverviewResponse, MemoryScopeInfo, MessagesLiveTail, MessagesPageInfo, MessagesResponse, ModelInfo, ModelPricingDto, ModelProtocolDetectRequest, ModelProtocolDetectResponse, ModelProtocolProbeDto, ModelRefDto, ModelTestRequest, ModelTestResponse, ModelUpdateEntry, ModelVisionDetectRequest, ModelVisionDetectResponse, ModelVisionOutcome, ModelsResponse, ModelsUpdateRequest, PasswordChangeRequest, PendingFollowUpInfo, PendingSteeringInfo, PrefsResponse, ProjectCreateRequest, ProjectCreateResponse, ProjectRole, ProjectSummary, ProjectUpdateRequest, ProjectUpdateResponse, ProjectsResponse, ProtocolProbeOutcome, RecalledMessageResponse, RequestSpan, RetryNowResponse, ScheduleItem, ScheduleServerEvent, ScheduleStatus, ScheduleUpsertRequest, SchedulesResponse, ServerEvent, ServerSettings, ServerSettingsResponse, ServerSettingsUpdateRequest, SessionCategory, SessionCategoryCounts, SessionCreateRequest, SessionCreateResponse, SessionForkRequest, SessionForkResponse, SessionInfo, SessionPatchRequest, SessionProcessInfo, SessionProcessesResponse, SessionResponse, SessionSource, SessionStatus, SessionTracesResponse, SessionsResponse, SkillArchiveInstallRequest, SkillGroupItem, SkillInstallRequest, SkillLibraryResponse, SkillMetadataItem, SteerRequest, TaskCreateRequest, TaskCreateResponse, TaskInputPart, ToolCallSpan, TraceAnalysisResponse, TraceEventsResponse, TraceFileInfo, TraceImportRequest, TraceImportResponse, TraceModelSegment, TraceOtherSpan, TracePosition, TraceTaskStats, TraceToolSpan, UiPrefs, UpdateCheckResponse, UpdateRunResponse, UploadLimits, UsageAgentCount, UsageBucket, UsageErrorCount, UsageErrorItem, UsageErrors, UsageErrorsPage, UsageGroupBy, UsageGroupRow, UsageResponse, UsageSuccessRate, UsageTrendPoint, UsageTrendPointInTrace, UserInfo, VaultEntryInfo, VaultEntryUpdate, VaultResponse, VaultUpdateRequest, VersionResponse, WorkspaceFileEntry, WorkspaceFilesResponse };