@prismshadow/penguin-server 0.2.2 → 0.2.4

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';
 
 /**
@@ -72,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. */
@@ -119,11 +151,23 @@ interface ServerSettings {
      */
     proxyForAgent: boolean;
     /**
-     * The shared explicit proxy address (canonical `http(s)://host[:port]`), or null =
-     * follow the proxy environment variables. When set it takes precedence over
-     * HTTP_PROXY / HTTPS_PROXY wherever the owning switch is on.
+     * 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;
@@ -133,12 +177,38 @@ interface ServerSettingsUpdateRequest {
     proxyForApp?: boolean;
     proxyForAgent?: boolean;
     /**
-     * New proxy address. Accepted forms: `http://host[:port]`, `https://host[:port]`, 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`.
+     * 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;
+}
+/**
+ * One draft-screen shortcut: a prompt the user wrote, filed under a name they chose. Clicking it
+ * fills the composer exactly like a built-in example does, and sends nothing. Deliberately holds
+ * no Skill list — a saved prompt is not authored against a known Skill catalog the way a shipped
+ * example is, and the Agent it will run under is picked after the click.
+ */
+interface DraftShortcut {
+    /** Stable client-generated id: what an edit or a delete addresses the row by. Unique per user. */
+    id: string;
+    title: string;
+    prompt: string;
 }
 /** User UI preferences (SQLite ui_prefs, free-form JSON; known keys declared here). */
 interface UiPrefs {
@@ -154,6 +224,13 @@ interface UiPrefs {
     showCliSessions?: boolean;
     /** The initial-password notice banner (app layout) was permanently dismissed by the user. */
     initialPasswordBannerDismissed?: boolean;
+    /**
+     * The draft screen's user-defined shortcuts, in display order. Replaced whole on every write
+     * (the merge is shallow, so the array is one field like any other) and bounded on write by
+     * services/draft-shortcuts.ts — count, title length and prompt length — because this is the one
+     * known key holding user-authored text rather than a flag or an id.
+     */
+    draftShortcuts?: DraftShortcut[];
     [key: string]: unknown;
 }
 interface PrefsResponse {
@@ -236,7 +313,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
@@ -251,9 +328,24 @@ 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;
+    /**
+     * Masked preview (same rule as `credential.apiKeyMasked`) of the value the server process
+     * currently holds for `envKey` — the plaintext is never serialized. Reported only for
+     * first-party official entries (vendor group, catalog shape unmodified); gateway, custom
+     * and user-defined groups never carry it. Absent = the variable is unset or empty, or the
+     * entry is not first-party.
+     */
+    envKeyMasked?: string;
     credential?: CredentialInfo;
     isDefault: boolean;
 }
@@ -293,6 +385,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;
@@ -333,6 +427,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
@@ -353,6 +486,71 @@ 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[];
+}
+/**
+ * Endpoint model listing (POST /api/projects/:p/models/list, owner): given a base URL and
+ * the protocol `/detect` reported, returns every model id the endpoint serves (AgentHub's
+ * `listModels()` on the routed client). Used by the add-group dialog to import a provider's
+ * whole listing in one go; the ids come back in the endpoint's own order.
+ */
+interface EndpointModelListRequest {
+    /** Endpoint base URL (as typed in the add-group dialog). */
+    baseUrl: string;
+    /** AgentHub client type to speak (normally a detected generic protocol; whole-endpoint listings need one). */
+    clientType: string;
+    /** Newly entered API key (plaintext); omitted = the SDK's environment fallback for the protocol. */
+    apiKey?: string;
+}
+/** Listing outcome: model ids on success, a truncated provider/SDK reason otherwise. */
+interface EndpointModelListResponse {
+    ok: boolean;
+    /** The model ids the endpoint serves, in the order the endpoint returned them (ok only). */
+    models?: string[];
+    /** The routed client has no models endpoint (AgentHub UnsupportedOperationError) — callers offer the manual path. */
+    unsupported?: boolean;
+    message?: string;
+}
 /**
  * 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
@@ -385,10 +583,40 @@ interface ChatDefaultsDto {
     /**
      * 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">;
 }
+/**
+ * One deny rule of the sandbox command policy — plain project-editable data. The factory
+ * rules are seeded into new projects and carry no special status thereafter: every rule
+ * can be edited, disabled, or deleted.
+ */
+interface CommandPolicyRuleDto {
+    name: string;
+    /** JavaScript regex source, matched against the whitespace-normalized command. */
+    pattern: string;
+    /** What the rule catches (free text). */
+    description?: string;
+    /** Per-rule switch, effective value (defaults on). */
+    enabled: boolean;
+}
+/**
+ * Per-Project sandbox command policy: deny rules for shell commands, evaluated ahead of
+ * the approval mode (a hit is denied even under allow-all). Serves as the GET response and
+ * the PUT response. The PUT request body carries `enabled?` plus the full `rules` list
+ * (required — a PUT always materializes the list into the config, model-presets style);
+ * per-rule `enabled` may be omitted there and defaults to on. Owner-only to write; any
+ * member may read.
+ */
+interface CommandPolicyDto {
+    /** Effective master switch; an absent stored value reads as true (the policy defaults on). */
+    enabled: boolean;
+    /** The effective rule list — the factory set when the project predates seeding and has none stored. */
+    rules: CommandPolicyRuleDto[];
+    /** The factory set, served for the settings UI's "restore defaults". */
+    defaultRules: CommandPolicyRuleDto[];
+}
 /** Read-only vault entry display: key name + masked value; plaintext is never sent. */
 interface VaultEntryInfo {
     key: string;
@@ -596,6 +824,8 @@ interface MemoryScopeInfo {
     workspacePath?: string;
     /** Number of Markdown topic files in the directory (the `MEMORY.md` index not counted). */
     fileCount: number;
+    /** Whether the directory holds a `MEMORY.md` index, so an import confirmation can say whether one would be replaced. */
+    hasIndex: boolean;
     /** Most recent topic-file mtime in the directory (ISO 8601); unset when the directory holds no topic file. */
     updatedAt?: string;
 }
@@ -635,6 +865,64 @@ interface MemoryFileResponse {
     file: MemoryFileInfo;
     content: string;
 }
+/** One topic file inside a transfer document: the name it had in its scope, and its whole text. */
+interface MemoryTransferFile {
+    /** File name inside the scope directory, e.g. `prefers-pnpm.md` — a name, never a path. */
+    name: string;
+    /** The file's full Markdown text, frontmatter included. */
+    content: string;
+}
+/**
+ * GET …/memory/scopes/:key/export, and the body a POST …/import carries back: everything one
+ * scope holds, as one JSON document — the topic files and the scope's own `MEMORY.md`.
+ */
+interface MemoryScopeExport {
+    /** Format marker, so a foreign JSON file is refused with a clear reason rather than half-imported. */
+    format: "penguin-memory-scope";
+    /** Document version. A reader accepts exactly this; a later format bumps it and states its own compatibility. */
+    version: 1;
+    /** The scope this was exported from. Informational: an import writes into the scope its URL names. */
+    scopeKey: string;
+    kind: MemoryScopeInfo["kind"];
+    /** The Workspace the source scope stood for, when it had a `.workspace` marker. */
+    workspacePath?: string;
+    /** When the document was produced (ISO 8601). */
+    exportedAt: string;
+    /** The scope's `MEMORY.md`, or null when the scope has none. Only the index reaches the model's context. */
+    index: string | null;
+    files: MemoryTransferFile[];
+}
+/**
+ * What an import does with a name the target scope already holds:
+ *   - `skip` — keep what is on disk, write only names the scope does not have (destroys nothing);
+ *   - `overwrite` — replace a same-named file's content;
+ *   - `replace` — additionally delete every topic file the document does not carry.
+ * The two destructive modes require `confirm`.
+ */
+type MemoryImportMode = "skip" | "overwrite" | "replace";
+/** POST …/memory/scopes/:key/import */
+interface MemoryImportRequest {
+    /** Defaults to `skip`. */
+    mode?: MemoryImportMode;
+    /** Required by `overwrite` and `replace`; without it they are refused with 409 `memory_import_confirm_required`. */
+    confirm?: boolean;
+    payload: MemoryScopeExport;
+}
+/** What one import did, name by name, so the UI can report it rather than claim success. */
+interface MemoryImportResponse {
+    scopeKey: string;
+    mode: MemoryImportMode;
+    /** Names written that the scope did not have. */
+    added: string[];
+    /** Names whose existing content was replaced. */
+    overwritten: string[];
+    /** Names left untouched because the scope already had them (`skip` only). */
+    skipped: string[];
+    /** Names deleted because `replace` dropped everything the document did not carry. */
+    removed: string[];
+    /** Whether the scope's `MEMORY.md` was written or extended. */
+    indexWritten: boolean;
+}
 interface SessionInfo {
     sessionId: string;
     projectId: string;
@@ -645,11 +933,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;
@@ -719,11 +1031,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. */
@@ -791,7 +1128,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
@@ -814,17 +1151,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";
@@ -835,9 +1181,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;
     /**
@@ -912,6 +1259,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. */
@@ -919,6 +1268,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";
 }
@@ -944,6 +1330,8 @@ interface SessionProcessInfo {
     cwd: string;
     startedAt: string;
     running: boolean;
+    /** The service the process serves, when detected: the last local URL its output printed, else an origin probed from its listening ports. */
+    serviceUrl?: string;
 }
 interface SessionProcessesResponse {
     processes: SessionProcessInfo[];
@@ -966,6 +1354,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). */
  | {
@@ -973,6 +1363,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";
@@ -991,6 +1407,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";
@@ -1093,12 +1514,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
@@ -1358,35 +1789,47 @@ interface UsageGroupRow {
     cost: number | null;
     hasUncosted: boolean;
 }
-interface UsageTrendPoint {
-    date: string;
-    total: number;
-    cost: number | null;
-    /** Daily Token buckets (for the cost center's "Token Changes" stacked chart: cacheRead/cacheWrite/output). */
+/** Time-series precision for the usage series (`granularity` query parameter). `minute` requires the `fromTs`/`toTs` window bounds. */
+type UsageGranularity = "minute" | "hour" | "day" | "week" | "month";
+/**
+ * One bucket of the usage time series (for the cost center's time-series charts).
+ * Buckets are zero-filled across the whole requested range, so consecutive points
+ * are always adjacent in time. Bucket keys by granularity: minute
+ * `yyyy-mm-ddThh:mm` and hour `yyyy-mm-ddThh:00` (server-local clock), day
+ * `yyyy-mm-dd`, week the ISO week's Monday `yyyy-mm-dd`, month `yyyy-mm`.
+ */
+interface UsageSeriesPoint {
+    bucket: string;
     cacheRead: number;
     cacheWrite: number;
     output: number;
+    total: number;
+    /** Cost converted at query time (USD); null when no priced Model contributed. */
+    cost: number | null;
+    requests: number;
+    /** Successful requests in the bucket. */
+    completed: number;
+    /** Success-rate denominator: all requests minus aborted (a user interruption is not a model failure). */
+    denominator: number;
 }
-/** Invocation count per Agent (for the cost center's "Agent Invocation Count" chart). */
-interface UsageAgentCount {
+/**
+ * One entity's per-bucket request and success counts, aligned index-for-index
+ * with `series` (the requests-and-success-rate chart draws one such entity —
+ * or stacks them all). `denominator` excludes aborted, same as elsewhere.
+ */
+interface UsageEntitySeriesCounts {
+    requests: number[];
+    completed: number[];
+    denominator: number[];
+}
+/** Per-Agent counts per bucket. */
+interface UsageAgentSeries extends UsageEntitySeriesCounts {
     agentId: string;
-    requests: number;
-    total: number;
 }
-/** Request success rate per Model (for the cost center's "Model Success Rate" chart; rows broken down by (provider, modelId)). */
-interface UsageSuccessRate {
+/** Per-Model counts per bucket (entity identity is the (provider, modelId) pair). */
+interface UsageModelSeries extends UsageEntitySeriesCounts {
     provider: string;
     modelId: string;
-    /** Number of successful requests. */
-    completed: number;
-    /** Success rate denominator = all requests − aborted (user-initiated interruption isn't a model failure and shouldn't lower the success rate). */
-    total: number;
-    /** Count of user interruptions (excluded from success rate, shown separately). */
-    aborted: number;
-    /** Failure breakdown (shown on hover; unknown statuses count toward total but not these three). */
-    failed: number;
-    timeout: number;
-    malformed: number;
 }
 /** Occurrence count of an error for a given source · code (the "most common" metric in the stats center's error panel). */
 interface UsageErrorCount {
@@ -1439,12 +1882,27 @@ interface UsageResponse {
     };
     groupBy: UsageGroupBy;
     groups: UsageGroupRow[];
-    /** Daily trend for the last 30 days (includes Token buckets and cost; affected by agent/model filters). */
-    trend: UsageTrendPoint[];
-    /** Invocation count per Agent (affected by date/model filters). */
-    byAgent: UsageAgentCount[];
-    /** Raw success rate counts per Model (affected by date/agent filters). */
-    success: UsageSuccessRate[];
+    /** Effective precision of `series` (the validated `granularity` query parameter; defaults to day). */
+    granularity: UsageGranularity;
+    /**
+     * Usage time series over the requested from/to range (defaulting to the last 30
+     * days), zero-filled at `granularity`; affected by agent/model filters. Carries
+     * everything the time-series charts draw: Token buckets, cost, request count,
+     * and per-bucket success counts.
+     */
+    series: UsageSeriesPoint[];
+    /**
+     * Per-Agent counts per bucket, aligned index-for-index with `series`, sorted
+     * by total requests descending. Unaffected by the agent filter — the by-Agent
+     * chart draws the whole breakdown — but affected by date/model filters.
+     */
+    byAgentSeries: UsageAgentSeries[];
+    /**
+     * Per-Model counts per bucket, aligned index-for-index with `series`, sorted
+     * by total requests descending. Unaffected by the model filter — the by-Model
+     * chart draws the whole breakdown — but affected by date/agent filters.
+     */
+    byModelSeries: UsageModelSeries[];
     /** Server-side error capture stats (affected by date/agent filters; unaffected by model filter). */
     errors: UsageErrors;
     /** List of Agent ids that have appeared in this Project (for the filter dropdown; unaffected by current filters). */
@@ -1663,6 +2121,51 @@ interface UpdateCheckResponse {
     /** Why the lookup failed: unreachable network / GitHub rate limit / unusable response. */
     error?: "network" | "rate_limited" | "bad_response";
 }
+/**
+ * The desktop shell's updater snapshot, pushed to the embedded server over the
+ * utilityProcess message channel and served at GET /api/desktop/update. `state` is the
+ * discriminator; the optional fields belong to the states named on them.
+ *
+ * A `downloaded` build stays the reported state until it is installed: a later periodic
+ * check (or its failure) must not hide the actionable "restart to install" step.
+ */
+interface DesktopUpdateStatus {
+    /** Installed shell version (Electron app.getVersion()). */
+    appVersion: string;
+    /**
+     * Bumped by the shell on every updater event it folds, whether or not the visible
+     * state changed. A row-initiated check settles when the seq has moved past its
+     * at-click value and the state is no longer `checking` — snapshot equality can't
+     * carry that signal (a check that ends where it started is byte-identical).
+     */
+    seq?: number;
+    state: "idle" | "checking" | "up-to-date" | "downloading" | "downloaded" | "error" | "unsupported";
+    /** Newer release being fetched / ready to install (`downloading`, `downloaded`). */
+    version?: string;
+    /** Download progress 0–100 (`downloading`). */
+    percent?: number;
+    /** Updater failure text (`error`). */
+    message?: string;
+    /** Why this install form cannot update itself (`unsupported`): dev run, or a Linux install that is not an AppImage (e.g. .deb — the system package manager owns it). */
+    reason?: "dev" | "linux-not-appimage";
+}
+/**
+ * GET /api/desktop/update (desktop-shell sessions only): the latest shell snapshot.
+ * `status` is null until the shell's first push lands (a beat after server start).
+ */
+interface DesktopUpdateStatusResponse {
+    status: DesktopUpdateStatus | null;
+}
+/** Shell → server push over the utilityProcess message channel. */
+interface DesktopUpdaterStatusMessage {
+    type: "desktop-updater-status";
+    status: DesktopUpdateStatus;
+}
+/** Server → shell command over the utilityProcess message channel (relayed from POST /api/desktop/update/check|install). */
+interface DesktopUpdaterCommandMessage {
+    type: "desktop-updater-command";
+    action: "check" | "install";
+}
 /**
  * POST /api/version/update (admin only): runs the CLI self-update (`penguin update --yes`)
  * on the server host. `unsupported` covers both a server not launched via the CLI and the
@@ -1678,4 +2181,4 @@ interface UpdateRunResponse {
     needsRestart: boolean;
 }
 
-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, McpServerTestResponse, MeResponse, MemberAddRequest, MemberAddResponse, MemberInfo, MembersResponse, MemoryFileInfo, MemoryFileResponse, MemoryFilesResponse, MemoryOverviewResponse, MemoryScopeInfo, 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, ServerSettings, ServerSettingsResponse, ServerSettingsUpdateRequest, SessionCategory, SessionCategoryCounts, SessionCreateRequest, SessionCreateResponse, 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, 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, CommandPolicyDto, CommandPolicyRuleDto, CredentialInfo, DefaultModelResponse, DefaultModelUpdateRequest, DesktopUpdateStatus, DesktopUpdateStatusResponse, DesktopUpdaterCommandMessage, DesktopUpdaterStatusMessage, DirEntryInfo, DirListResponse, DraftShortcut, EndpointModelListRequest, EndpointModelListResponse, ErrorBody, FilesStatRequest, FilesStatResponse, GoalResponse, GoalServerEvent, GoalStateView, HistoryMessage, McpServerTestResponse, MeResponse, MemberAddRequest, MemberAddResponse, MemberInfo, MembersResponse, MemoryFileInfo, MemoryFileResponse, MemoryFilesResponse, MemoryImportMode, MemoryImportRequest, MemoryImportResponse, MemoryOverviewResponse, MemoryScopeExport, MemoryScopeInfo, MemoryTransferFile, 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, UsageAgentSeries, UsageBucket, UsageEntitySeriesCounts, UsageErrorCount, UsageErrorItem, UsageErrors, UsageErrorsPage, UsageGranularity, UsageGroupBy, UsageGroupRow, UsageModelSeries, UsageResponse, UsageSeriesPoint, UsageTrendPointInTrace, UserInfo, VaultEntryInfo, VaultEntryUpdate, VaultResponse, VaultUpdateRequest, VersionResponse, WorkspaceFileEntry, WorkspaceFilesResponse };