@prismshadow/penguin-server 0.2.13 → 0.2.16

package/dist/api/types.d.ts

@@ -1,6 +1,96 @@
-import { OmniMessage, ToolCallPayload, CompactionMode } from '@prismshadow/penguin-core/omnimessage';
+import { SessionSource, OmniMessage, ToolCallPayload, CompactionMode } from '@prismshadow/penguin-core/omnimessage';
+export { SessionSource } from '@prismshadow/penguin-core/omnimessage';
 import { ThinkingLevelName, ToolDefinitionConfig, MCPServerConfig } from '@prismshadow/penguin-core/interfaces';
-import { VersionReport } from '@prismshadow/penguin-core';
+import { HarnessHistory, VersionReport } from '@prismshadow/penguin-core';
+export { HarnessHistoryEntry, IfacesSummary } from '@prismshadow/penguin-core';
+import { IfacesDiff } from '@prismshadow/penguin-hmr';
+export { IfaceChange, IfacesDiff, MemberChange, ModuleChange } from '@prismshadow/penguin-hmr';
+
+/** A request the workbench's handler receives (the HTTP shape, minus the transport). */
+interface WorkbenchRequest {
+    method: string;
+    /** Path below the workbench's `api/` mount, always starting with `/`. */
+    path: string;
+    query: Record<string, string>;
+    /** Request headers, names lower-cased. The app's own credentials (`cookie`, `authorization`) are withheld. */
+    headers: Record<string, string>;
+    /** The parsed body of a JSON request; `null` otherwise (GET/HEAD, no body, another content type). */
+    body: unknown;
+    /** The body as sent, when there is one and it is not JSON: a form, an upload, plain text. */
+    bytes?: Uint8Array;
+}
+interface WorkbenchResponse {
+    /** HTTP status; 200 when absent. */
+    status?: number;
+    /**
+     * Response headers. Naming a `content-type` is what makes the response something other than
+     * JSON; `location` with a 3xx status redirects. `set-cookie` is dropped — a workbench does not
+     * write the app's cookies.
+     */
+    headers?: Record<string, string>;
+    /** JSON by default (`null` when absent); with a `content-type` header, a string sent as written. */
+    body?: unknown;
+    /** A binary body (an image, a font, a download); wins over `body`. */
+    bytes?: Uint8Array;
+    /**
+     * A body sent as it is produced — server-sent events, a model's answer token by token, a
+     * large download — each chunk written to the client when the iterator yields it; wins over
+     * `bytes` and `body`. A client that goes away ends the iteration: `return()` is called, so
+     * a `finally` in the generator is where an upstream request is aborted — but a generator
+     * suspended inside an `await` receives it only once that await settles, so a relay whose
+     * upstream can hang should carry its own deadline rather than rely on the disconnect.
+     */
+    stream?: AsyncIterable<Uint8Array | string>;
+}
+/** How the Web App draws a contributed tab: a page of the workbench, or a renderer it carries. */
+type WorkbenchTabRenderer = {
+    iframe: {
+        src: string;
+    };
+} | {
+    builtin: string;
+};
+/**
+ * One tab beside Chat, as the workbench contributed it (`WebModule.sessionTabs`). In a
+ * manifest `renderer.iframe.src` is a path inside the workbench folder, under `ui/`; in a
+ * `WorkbenchInfo` it is the URL that file is served from.
+ */
+interface WorkbenchTab {
+    id: string;
+    /** Unique within the workbench; the tab's stable name (it appears in the full-page URL). */
+    key: string;
+    title: string;
+    titleZh?: string;
+    renderer: WorkbenchTabRenderer;
+}
+interface WorkbenchInfo {
+    id: string;
+    name: string;
+    version: string | null;
+    /** Content revision of the whole folder (what history records). */
+    revision: string;
+    /** Content revision of `ui/`: the cache key of the workbench's pages. Null when it has no `ui/`. */
+    uiRev: string | null;
+    /** The tabs of the instance that is SERVING — the previous one's while `error` is set. */
+    tabs: WorkbenchTab[];
+    loadedAt: string;
+    /** The boot error when the current files do not load (the previous instance, if any, keeps serving). */
+    error: string | null;
+    /**
+     * What loaded but is probably not what its author meant, each with the edit that settles it
+     * — pages under `ui/` that no tab shows, say. Never a failure: `error` is that.
+     */
+    hints: string[];
+}
+interface WorkbenchVersion {
+    revision: string;
+    savedAt: string;
+    name: string;
+    version: string | null;
+    uiRev: string | null;
+    /** The files of that version (relative paths), for display. */
+    files: string[];
+}
 
 /**
  * Web API DTO contract — request/response types shared between server routes and the
@@ -18,19 +108,26 @@ import { VersionReport } from '@prismshadow/penguin-core';
  * public route/SSE reference for this contract — keep it in sync when changing DTOs.
  */
 
-/** Unified error response body; `code` is a machine-readable error code, `message` is a Chinese user-facing message. */
+/**
+ * Unified error response body: `code` is a machine-readable error code, `message` an English
+ * user-facing message, and `details`, on the errors that have them, the facts a client acts on
+ * beside the code (the Benchmark id a 409 `benchmark_exists` is about, say) — read from there,
+ * never parsed out of the message.
+ */
 interface ErrorBody {
     error: {
         code: string;
         message: string;
+        details?: ErrorDetails;
     };
 }
+/** An error's structured facts, by name; each code that carries them documents its own. */
+type ErrorDetails = Readonly<Record<string, string>>;
 /** Session approval mode (reuses the CLI enum). */
 type ApprovalMode = "allow-all" | "deny-all" | "read-only" | "always-ask";
 /** Session run status: idle / Task in progress / compacting. */
 type SessionStatus = "idle" | "running" | "compacting";
-/** Session source marker (default = user-created): triggered by Schedule / registered as a subagent session / created by a Benchmark evaluation or optimization. */
-type SessionSource = "schedule" | "subagent" | "benchmark";
+
 interface UserInfo {
     /** Semantic id, i.e. login name: `^[a-z][a-z0-9_-]{1,31}$`, immutable after creation. */
     userId: string;
@@ -107,8 +204,9 @@ interface MeResponse {
      * "desktop" is the shell's own window (one-shot token); "setup" was claimed through the
      * first-login link on a server whose admin password has never been set. Both may set a
      * password without the old one (it is random and was never shown); only "desktop" opens
-     * desktop-only routes. "token" marks a request authenticated by the local API token's
-     * Bearer header (the CLI and agent-driven calls) — no stored session at all.
+     * desktop-only routes. "token" marks the local API token's authority, carried by a Bearer
+     * header or an exchanged Remote cookie; neither can perform writes requiring a person's
+     * sign-in.
      */
     sessionVia: "password" | "desktop" | "setup" | "token";
     /**
@@ -220,6 +318,19 @@ interface ServerSettings {
      * reports it so clients hide the mode switch. Organizations on disk are untouched.
      */
     companyMode: boolean;
+    /**
+     * Whether users may drive their own Chrome through the PenguinHarness Browser extension
+     * (default on). Off closes every connected extension (close code 4009), refuses new
+     * connections, and makes the chrome backend unavailable (`extension_disabled`); pairings are
+     * kept, so turning it on again lets the extensions reconnect.
+     */
+    browserExtensionsEnabled: boolean;
+    /**
+     * Whether external programs may talk to Agents through the Agent API (default on). Off answers
+     * every `/api/amsp/v1` request 403 `agent_api_disabled` (a CORS preflight excepted); every
+     * Agent's API switch, approval mode and keys are kept, so turning it on again restores them.
+     */
+    agentApiEnabled: boolean;
 }
 interface ServerSettingsResponse {
     settings: ServerSettings;
@@ -230,6 +341,10 @@ interface ServerSettingsUpdateRequest {
     proxyForAgent?: boolean;
     /** Company mode master switch; see `ServerSettings.companyMode`. */
     companyMode?: boolean;
+    /** Chrome extension switch; see `ServerSettings.browserExtensionsEnabled`. */
+    browserExtensionsEnabled?: boolean;
+    /** Agent API switch; see `ServerSettings.agentApiEnabled`. */
+    agentApiEnabled?: boolean;
     /**
      * New proxy address. Accepted forms: any proxy URL undici's dispatcher takes —
      * `http://`, `https://`, `socks5://` / `socks://`, credentials allowed — or bare
@@ -311,6 +426,19 @@ interface DraftShortcut {
     title: string;
     prompt: string;
 }
+/**
+ * The account's keyboard shortcut overrides, one section per platform (the Web App's `Mod` token
+ * is ⌘ on macOS and Ctrl elsewhere, so a deliberate macOS-only binding must not leak to Windows).
+ * Each section maps a command id to a chord string ("Mod+Shift+KeyW") or null (explicitly
+ * unbound); only rows that differ from the Web App's default are present. Bounded on write by
+ * services/keybindings.ts.
+ */
+interface StoredKeybindings {
+    v: 1;
+    mac?: Record<string, string | null>;
+    windows?: Record<string, string | null>;
+    linux?: Record<string, string | null>;
+}
 /** User UI preferences (SQLite ui_prefs, free-form JSON; known keys declared here). */
 interface UiPrefs {
     theme?: "light" | "dark";
@@ -334,14 +462,29 @@ interface UiPrefs {
      * known key holding user-authored text rather than a flag or an id.
      */
     draftShortcuts?: DraftShortcut[];
+    /** Keyboard shortcut overrides, replaced whole on every write and validated by services/keybindings.ts. */
+    keybindings?: StoredKeybindings;
     /** Personal company-mode switch (default on): off only hides this user's mode switch; organizations keep running. */
     companyMode?: boolean;
     /** The work mode the user last chose in the shell: development (default) or company. */
     workMode?: "dev" | "company";
     /** The organization last opened in company mode, as `<projectId>/<orgId>`. */
     lastOrgKey?: string;
+    /** The one group balance shown beside the user name (pinned on the models page); null when unpinned. */
+    pinnedBalance?: PinnedBalance | null;
+    /**
+     * The browser this user's agents drive. Written only through PUT /api/builtin-browser/backend
+     * (PUT /api/me/prefs refuses it): absent means built-in for an admin on the desktop, chrome
+     * everywhere else.
+     */
+    browserBackend?: BrowserBackend;
     [key: string]: unknown;
 }
+/** A group balance pinned beside the user name: which Project's key reads which group's balance. */
+interface PinnedBalance {
+    projectId: string;
+    provider: string;
+}
 interface PrefsResponse {
     prefs: UiPrefs;
 }
@@ -395,7 +538,7 @@ interface MemberAddResponse {
 }
 /**
  * Model reference DTO: `(provider, modelId)` pair.
- * `modelId` is the upstream request id, sent to AgentHub as-is — `<provider>/<id>` string
+ * `modelId` is the upstream request id, sent to MMSP as-is — `<provider>/<id>` string
  * concatenation is forbidden throughout the pipeline.
  */
 interface ModelRefDto {
@@ -408,6 +551,37 @@ interface ModelPricingDto {
     cacheWrite: number;
     output: number;
 }
+/**
+ * One group's `[providers.<id>]` connection as the page reads it: the values the GROUP stores
+ * (never the catalog's), the key masked. An absent field is unset: a row with no value of its
+ * own then gets the client's default.
+ */
+interface ProviderConnectionDto {
+    baseUrl?: string;
+    clientType?: string;
+    apiKeyMasked?: string;
+    /** When the group key was written (ISO 8601). */
+    createdAt?: string;
+}
+/** Where an effective connection value comes from: the row itself, its group, or nowhere (the client's default). */
+type ConnectionSourceDto = "model" | "provider" | "none";
+/**
+ * What a row is actually used with, after core's effectiveConnection (row -> group -> none,
+ * per field; the file's values only — the catalog is not consulted), and where each value
+ * came from. The group's key counts only where it reaches the row (core's groupKeyReaches).
+ * The row's own values stay in `clientType` / `credential` (what the form edits); this is for
+ * display.
+ */
+interface ModelEffectiveConnection {
+    baseUrl?: string;
+    baseUrlSource: ConnectionSourceDto;
+    clientType?: string;
+    clientTypeSource: ConnectionSourceDto;
+    /** `env` = no row or group key, and the environment lends one on the effective endpoint (modelEnvFallback). */
+    apiKeySource: "model" | "provider" | "env" | "none";
+    /** Mask of the key the row would use, whichever source; absent when none. */
+    apiKeyMasked?: string;
+}
 /** Read-only credential display: masked key and creation time; plaintext is never sent. */
 interface CredentialInfo {
     apiKeyMasked?: string;
@@ -417,7 +591,7 @@ interface CredentialInfo {
 interface ModelInfo {
     /** Provider group id (anthropic / openai / …, see core's MODEL_PROVIDERS; custom models use `custom`). */
     provider: string;
-    /** Upstream model id (the request id actually sent to AgentHub); paired with `provider` forms the entry's unique key. */
+    /** Upstream model id (the request id actually sent to MMSP); paired with `provider` forms the entry's unique key. */
     modelId: string;
     /**
      * Display name: explicit TOML field (user-edited) takes priority, then the built-in catalog;
@@ -427,12 +601,15 @@ interface ModelInfo {
      */
     displayName?: string;
     contextWindow?: number;
-    /** AgentHub client protocol (`openai-chat`, `openai-responses`, etc.); defaults to AgentHub inferring it from modelId. */
+    /**
+     * The row's OWN MMSP client type (`openai-chat`, `openai-responses`, etc.) — an override of
+     * its group's; absent = the row follows its group (see `effective`).
+     */
     clientType?: string;
     /**
-     * Whether image input (vision/multimodal) is supported: the TOML `vision` annotation takes
-     * priority, falling back to the built-in catalog annotation; if neither exists, defaults to
-     * unset (= treated as supported).
+     * Whether image input (vision/multimodal) is supported: the TOML `vision` annotation only
+     * (a new Project writes `false` where the catalog says so); absent = unset, treated as
+     * supported. The catalog is not consulted.
      */
     vision?: boolean;
     /**
@@ -445,22 +622,36 @@ interface ModelInfo {
     /**
      * 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;
+     * tier at premium pricing (MMSP 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. */
+    /** Running promotion for this row — a fraction in (0, 1) off `pricing`, which is the list price — read from web.db. Absent when the row has none. */
+    discount?: number;
+    /**
+     * Environment variable name the entry falls back to when api_key is empty (e.g.
+     * ANTHROPIC_API_KEY); unset when it gets no fallback — an id nothing routes, or an entry
+     * whose base URL is not the vendor's own official endpoint (a gateway preset, a custom /
+     * vLLM / user-created row with its own endpoint, a vendor row re-pointed at a proxy).
+     */
     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.
+     * currently holds for `envKey` — the plaintext is never serialized. Reported only where the
+     * fallback may be presented as covering the entry (core's modelEnvPreviewKey): a row whose
+     * effective base URL is a vendor endpoint (or the Penguin Go relay), or a row with no base URL
+     * in a built-in group other than custom, on the client its id's family names. Gateway rows
+     * never carry it, and neither do custom / vLLM / user-defined rows with no base URL,
+     * although those do fall back. Absent = the variable is unset or empty, or the entry is not
+     * previewable. Computed on the effective shape, and only when no row or group key reaches
+     * the row.
      */
     envKeyMasked?: string;
+    /** The row's OWN key (masked) and base URL — overrides of its group's; see `effective`. */
     credential?: CredentialInfo;
+    /** The connection the row is actually used with, and where each value comes from. */
+    effective: ModelEffectiveConnection;
     isDefault: boolean;
 }
 interface ModelsResponse {
@@ -475,13 +666,32 @@ interface ModelsResponse {
      * (the key was fixed since). Absent when the Project has no config file yet.
      */
     updatedAt?: string;
+    /** Every group's stored connection (`[providers.<id>]`), keyed by provider id; a group with none is absent. */
+    providers: Record<string, ProviderConnectionDto>;
     models: ModelInfo[];
 }
+/**
+ * A change to one group's connection (`PUT /models/providers/:provider`, or a member of
+ * `ModelsUpdateRequest.providers`). Omitted fields are kept.
+ */
+interface ProviderConnectionUpdate {
+    /** `null` clears it; omitted keeps it. */
+    baseUrl?: string | null;
+    /**
+     * `null` or `""` clears it; omitted keeps it. Any group takes one: a row that stores its own
+     * protocol keeps it.
+     */
+    clientType?: string | null;
+    /** A non-empty key; sets `createdAt`. Rows with their own key keep it. */
+    apiKey?: string;
+    /** When true, clears the group key (rows with their own key keep it). */
+    clearApiKey?: boolean;
+}
 /** PUT full-table replace semantics: models not present are deleted; omitting apiKey = keep existing value. Key = (provider, modelId). */
 interface ModelUpdateEntry {
     /** Provider group (an independent entry field, always submitted with the request). */
     provider: string;
-    /** Upstream model id (sent to AgentHub as-is). */
+    /** Upstream model id (sent to MMSP as-is). */
     modelId: string;
     /**
      * Display name; the server does not persist it when it matches the built-in catalog (keeps
@@ -497,7 +707,10 @@ interface ModelUpdateEntry {
      */
     renamedFrom?: ModelRefDto;
     contextWindow?: number;
-    /** Empty string/omitted = unspecified (AgentHub infers it from modelId). */
+    /**
+     * Empty string/omitted = the row stores none: it follows its group's protocol, else MMSP
+     * routes by the vendor family the modelId begins with.
+     */
     clientType?: string;
     /** Whether image input (vision/multimodal) is supported; omitted = supported (not persisted). */
     vision?: boolean;
@@ -506,6 +719,12 @@ interface ModelUpdateEntry {
     /** Per-model fast mode: only `true` is persisted; omitted or `false` clears the annotation (absent = off). */
     fastMode?: boolean;
     pricing?: ModelPricingDto;
+    /**
+     * Promotion to store for this row, a fraction in (0, 1) off `pricing`; `null` clears it. Omitted
+     * keeps the stored promotion — unless this entry renames the row or changes its pricing, which
+     * clears it.
+     */
+    discount?: number | null;
     /** Providing it overwrites and updates createdAt; omitting it keeps the existing value. */
     apiKey?: string;
     /** When true, clears the stored api_key. */
@@ -518,8 +737,30 @@ interface ModelsUpdateRequest {
     defaultModel?: ModelRefDto;
     /** Vision model used as a proxy reader for read_file: must be included in models and not annotated vision=false; omitted keeps the existing value. */
     visionModel?: ModelRefDto;
+    /** Group connection changes, merged per provider; a provider absent here keeps its table. */
+    providers?: Record<string, ProviderConnectionUpdate>;
     models: ModelUpdateEntry[];
 }
+/**
+ * `POST /models/sync-presets` (owner): `add` adds the catalog's presets the Project lacks
+ * (retired rows never), as a new Project stores them, writes the catalog's
+ * `[providers.<id>]` table for a group that has neither rows nor a table yet, and seeds the
+ * added rows' promotions, touching nothing else; `restore` makes the model configuration a new
+ * Project's and keeps only the API keys: the presets in catalog order, the catalog's group
+ * tables, default model and promotions, no vision model, and every other row and every
+ * user-defined group deleted. Penguin Go included: its platform's next sync brings back the
+ * platform's own models and promotions.
+ */
+type PresetSyncMode = "add" | "restore";
+interface PresetSyncRequest {
+    mode: PresetSyncMode;
+}
+interface PresetSyncResponse extends ModelsResponse {
+    /** Preset rows added (both modes). */
+    added: number;
+    /** Preset rows the Project already had that `restore` changed (0 for `add`). */
+    restored: number;
+}
 /**
  * Connectivity test (POST /api/projects/:p/models/test): the model reference is submitted as
  * a pair in the request body; the rest are optional overrides (for trying out an unsaved
@@ -529,7 +770,7 @@ interface ModelsUpdateRequest {
 interface ModelTestRequest {
     /** Provider group of the model under test (paired with modelId). */
     provider: string;
-    /** Upstream id of the model under test (sent to AgentHub as-is). */
+    /** Upstream id of the model under test (sent to MMSP as-is). */
     modelId: string;
     /** Newly entered API key (plaintext); used for the test if provided. */
     apiKey?: string;
@@ -543,7 +784,7 @@ interface ModelTestRequest {
      * `undefined` means fall back to the stored value only when not provided.
      */
     baseUrl?: string | null;
-    /** AgentHub client protocol; required for unsaved custom models (otherwise the id can't be auto-routed). */
+    /** MMSP client type; required for an unsaved custom model whose id begins with no known vendor family (otherwise it can't be routed). */
     clientType?: string;
     /**
      * Test with fast mode (the frontend always sends the form's current value, so an unsaved
@@ -606,7 +847,7 @@ interface ModelTestResponse {
 }
 /**
  * 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,
+ * MMSP'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).
@@ -618,7 +859,12 @@ interface ModelProtocolDetectRequest {
     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). */
+    /**
+     * 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), else its group's.
+     * `provider` may be sent without `modelId` (the group settings dialog has no model): the
+     * group key backs the probes.
+     */
     provider?: string;
     modelId?: string;
 }
@@ -632,7 +878,7 @@ interface ModelProtocolDetectRequest {
 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`). */
+    /** MMSP 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;
@@ -646,7 +892,7 @@ interface ModelProtocolProbeDto {
  * ones actually run, in order.
  */
 interface ModelProtocolDetectResponse {
-    /** The first protocol an endpoint serves (an AgentHub client type); absent when none of the three matched. */
+    /** The first protocol an endpoint serves (an MMSP client type); absent when none of the three matched. */
     detected?: string;
     /**
      * The base URL the detected protocol answered at — the typed URL normalized (endpoint
@@ -660,14 +906,14 @@ interface ModelProtocolDetectResponse {
 }
 /**
  * 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
+ * the protocol `/detect` reported, returns every model id the endpoint serves (MMSP'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). */
+    /** MMSP 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;
@@ -677,7 +923,7 @@ 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. */
+    /** The routed client has no models endpoint (MMSP UnsupportedOperationError) — callers offer the manual path. */
     unsupported?: boolean;
     message?: string;
 }
@@ -695,6 +941,54 @@ interface DefaultModelUpdateRequest {
 interface DefaultModelResponse {
     defaultModel: ModelRefDto;
 }
+/** One balance in one currency. */
+interface ModelBalanceAmount {
+    /** Decimal string in `currency`'s major unit, as the vendor states it (TokenDance's micro-yuan are converted to yuan). */
+    amount: string;
+    /** ISO 4217 code: `CNY`, `USD`, … */
+    currency: string;
+}
+/**
+ * Why a group's balance could not be read:
+ * - `unsupported`: the group publishes no balance endpoint (no `balance` descriptor in the catalog);
+ * - `no_key`: the group has no API key to ask with — none stored, and no environment variable
+ *   the credential rule lends its rows for the balance endpoint's host;
+ * - `upstream_failed`: the vendor could not be reached in time, refused the request, or answered
+ *   without a readable balance.
+ */
+type ModelBalanceErrorCode = "unsupported" | "no_key" | "upstream_failed";
+/**
+ * GET /api/projects/:p/models/balance?provider=<group>[&force=1] (Project member): the account
+ * balance behind the group's API key — the stored one, or else the environment key its rows
+ * fall back to under the credential rule (DeepSeek's DEEPSEEK_API_KEY) — read server-side from
+ * the endpoint the catalog's `balance` descriptor names. The key never reaches the browser, and
+ * neither does the vendor's own text. Like the connectivity test, a balance that cannot be read is an answer
+ * (`ok: false` with a code), not a failed request. Readings and vendor failures are cached for
+ * 60 s per Project and group, for as long as the group's key is the same; `force=1` skips the
+ * cache and refreshes it.
+ */
+type ModelBalanceResponse = ModelBalanceReading | ModelBalanceFailure;
+interface ModelBalanceReading extends ModelBalanceAmount {
+    ok: true;
+    provider: string;
+    /** Whether the account can make requests right now (DeepSeek's `is_available`); absent when the vendor does not say. */
+    available?: boolean;
+    /** Further currencies the account holds, after the one in `amount` / `currency`; absent when there is only one. */
+    others?: ModelBalanceAmount[];
+    /** When the server read it from the vendor (ISO 8601); a cached answer keeps its original time. */
+    fetchedAt: string;
+}
+interface ModelBalanceFailure {
+    ok: false;
+    provider: string;
+    error: ModelBalanceErrorCode;
+    /** The vendor's HTTP status, when it answered with an error. */
+    status?: number;
+    /** English detail for logs and bug reports; the Web App words each code itself. */
+    message: string;
+    /** When the answer was settled (ISO 8601). */
+    fetchedAt: string;
+}
 /**
  * How the authorization code travels back. `callback` sends the browser to a harness URL
  * the provider redirects to; `manual` asks the provider for a one-time code the user copies
@@ -749,6 +1043,33 @@ interface ModelOAuthCodeResponse {
     applied?: number;
     error?: ModelOAuthErrorCode;
 }
+interface PlatformAuthStartResponse {
+    flowId: string;
+    authorizeUrl: string;
+    expiresAt: string;
+}
+type PlatformAuthFlowErrorCode = "unreachable" | "upstream_failed" | "invalid_key" | "expired" | "locked" | "already_delivered" | "apply_failed";
+interface PlatformAuthFlowStatusResponse {
+    status: "pending" | "applying" | "completed" | "cancelled" | "apply_failed" | "error";
+    error?: PlatformAuthFlowErrorCode;
+    applied?: number;
+}
+/** Result of refreshing Penguin Go's catalog with the Project's stored platform key. */
+interface PlatformModelSyncResponse extends ModelsResponse {
+    added: number;
+    updated: number;
+}
+/**
+ * The wire shapes are Penguin Go's, deliberately: both flows create a request, poll it, and
+ * report the same six states and the same seven failure codes, so the App drives both with one
+ * dialog. They are aliases rather than a second declaration because a copy would be the same
+ * fields with the same meaning, and a shape that drifted apart in one of the two would be a
+ * bug rather than a distinction. The endpoints stay separate regardless — a flow id issued by
+ * one is not accepted by the other.
+ */
+type ModelScopeAuthStartResponse = PlatformAuthStartResponse;
+type ModelScopeAuthFlowErrorCode = PlatformAuthFlowErrorCode;
+type ModelScopeAuthFlowStatusResponse = PlatformAuthFlowStatusResponse;
 /**
  * Per-Project new-chat defaults: prefill for the chat draft page. Every key is optional —
  * an absent key means "not set" (the pre-existing behavior). Serves as the GET response,
@@ -770,6 +1091,11 @@ interface ChatDefaultsDto {
      * "none" — only the selectable tiers.
      */
     thinkingLevel?: Exclude<ThinkingLevelName, "none">;
+    /**
+     * Read-only, GET only: the sandbox policy a new Session starts with — the server's Sandbox
+     * settings. Not part of the Project's block; PUT ignores it.
+     */
+    sandbox?: SessionSandbox;
 }
 /**
  * One deny rule of the sandbox command policy — plain project-editable data. The factory
@@ -820,11 +1146,15 @@ interface VaultEntryUpdate {
 interface VaultUpdateRequest {
     entries: VaultEntryUpdate[];
 }
-/** One installed plugin (a skill or a hook package) the library carries a higher version of (see {@link AgentSummary.pluginUpdates}). */
+/** One library plugin an Agent's installed copy is behind on — one of its skills or its hook package carries an older dated version than the library's same part (see {@link AgentSummary.pluginUpdates}). */
 interface PluginUpdateRef {
     /** Plugin name — what `POST …/plugins` reinstalls to bring the Agent up to date. */
     name: string;
-    /** The LIBRARY's version (`YYYY.MM.DD.N`), i.e. what installing again would bring, not what is on disk. */
+    /**
+     * The LIBRARY's content version: the newest dated version (`YYYY.MM.DD.N`) among the plugin's
+     * parts, i.e. the date of what installing again would bring, not what is on disk. A label —
+     * it moves whenever any part changes, so a dismissed update comes back for the next one.
+     */
     version: string;
 }
 interface AgentSummary {
@@ -850,21 +1180,43 @@ interface AgentSummary {
     vaultKeyCount: number;
     /** Schedule count (number of .toml files under agent_state/schedule/, including invalid ones). */
     scheduleCount: number;
+    /** Workbench folders with a manifest, including ones with a load error. */
+    workbenchCount: number;
     /** Installed Skill count (number of agent_state/skills/<name>/ directories with a SKILL.md). */
     skillCount: number;
     /** Installed hook-package count (number of agent_state/hooks/<name>/ directories with a hooks.json). */
     hookCount: number;
     /**
      * Installed plugins the built-in library has moved past — a skill or a hook package whose
-     * on-disk version is behind the library plugin that ships it — each with the library version
-     * on offer: the plugin-library update gate, riding along on the Agent list so a badge over
-     * that page costs no request of its own. Empty when nothing is behind. Skills the library
-     * does not carry (installed from a zip or a picked directory) are never listed: there is no
-     * library version for them to be behind.
+     * on-disk dated version is behind the library's same part (compared part by part, never
+     * against the plugin's npm version) — each with the library's content version on offer: the
+     * plugin-library update gate, riding along on the Agent list so a badge over that page costs
+     * no request of its own. Empty when nothing is behind. Skills the library does not carry
+     * (installed from a zip or a picked directory) are never listed: there is no library version
+     * for them to be behind.
      */
     pluginUpdates: PluginUpdateRef[];
     /** Memory count (topic files summed over the scope directories under agent_state/memory/, independent of the memory switch). */
     memoryCount: number;
+    /** Whether the Agent's API tab switch is on (this server's web.db, see AgentApiSettings.enabled): the list card's API mark. */
+    apiEnabled: boolean;
+    /**
+     * The organizations of this Project that employ the Agent, one entry per organization:
+     * every organization directory the Project holds, paused ones included, plus the CEO id of
+     * an organization whose chart does not parse. Absent or empty = not an employee. An
+     * employed Agent cannot be deleted (`DELETE` answers 409 `agent_employed`) until it leaves
+     * every one of them; development mode lists employees in a section of their own.
+     */
+    employments?: Employment[];
+}
+/** One organization employing an Agent, as the Agent list carries it (see {@link AgentSummary.employments}). */
+interface Employment {
+    orgId: string;
+    /** The organization's display name (`org_config.toml`), the id when the config does not parse. */
+    orgName: string;
+    /** The Agent's title in that organization's chart; "CEO" for the CEO of a chart that does not parse. */
+    title: string;
+    status: OrgStatus;
 }
 interface AgentsResponse {
     agents: AgentSummary[];
@@ -1012,13 +1364,20 @@ interface AgentKernelUpdateResponse {
     /** The kernel stamp written (the current defaults generation). */
     kernelVersion: string;
 }
-/** POST …/config/mcp-test result: reachability of one MCP Server entry. */
+/**
+ * POST …/config/mcp-test result: reachability of one MCP Server entry. Its `${KEY}` references
+ * are filled in from the Agent's vault only when the entry is saved on the Agent exactly as
+ * tested (same name, same config — the user's rule); a new or changed entry that references the
+ * vault is not filled in and not contacted (`saveFirst`).
+ */
 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. */
+    /** Failure detail (connect error, timeout, server stderr tail; "needs setup: …" naming a vault key a saved entry references and the vault lacks, with nothing contacted), present on failure. */
     error?: string;
+    /** The entry references the vault and is not saved as it is: nothing was filled in or contacted — save it, then test (`error` says so in English). */
+    saveFirst?: boolean;
     /** Connect + discovery wall time (both outcomes) — the models test reports latency, this matches. */
     latencyMs?: number;
 }
@@ -1054,6 +1413,73 @@ interface AgentConfigUpdateRequest {
         mcpServers?: MCPServerConfig[];
     };
 }
+/** One API key of an Agent, as listed: the secret itself is shown once, at creation, and never again. */
+interface AgentApiKeyInfo {
+    keyId: string;
+    /** 1-64 characters, given by whoever created it. */
+    name: string;
+    /** The key's first 16 characters (`penguin_` + 8), enough to tell keys apart. */
+    prefix: string;
+    /** user_id of the Project owner who created it. */
+    createdBy: string;
+    createdAt: string;
+    /** Last run request that authenticated with it; null = never used. */
+    lastUsedAt: string | null;
+}
+/**
+ * One Agent's public API settings — this server's, kept in web.db, never in the Agent State or
+ * the Project file, so the Agent cannot expose itself or loosen its own approvals. An Agent
+ * never configured reads as disabled, keyed, allow-all, with no keys.
+ */
+interface AgentApiSettings {
+    /** The API tab's switch; off = every AMSP request for this Agent is 404 `agent_not_found`. */
+    enabled: boolean;
+    /** Keyless access: a request without `Authorization` is accepted; off = 401 `unauthorized`. */
+    open: boolean;
+    /**
+     * The approval mode an API Session is created with. It is copied onto each API Session when
+     * that Session is created, and the Session's own mode is what every decision reads, so a
+     * change here applies to API Sessions created afterwards.
+     */
+    approvalMode: ApprovalMode;
+    /** Null follows the Project's default model. Applied only to new API Sessions. */
+    model: ModelRefDto | null;
+    /** Null follows the Agent/Project thinking configuration. */
+    thinkingLevel: ThinkingLevelName | null;
+    /** Null creates a temporary Workspace for each new API Session. */
+    workspace: string | null;
+    /** Positive integer. Checked for each API run; defaults to four concurrent Agent sessions. */
+    maxConcurrentRuns: number;
+    keys: AgentApiKeyInfo[];
+}
+interface AgentApiResponse {
+    api: AgentApiSettings;
+    /**
+     * The admin's server-wide switch (`ServerSettings.agentApiEnabled`), which only an admin can
+     * read through /api/admin/settings: off, every Agent's API is refused (403) whatever `api` says.
+     */
+    serverEnabled: boolean;
+}
+/** PUT body (owner only): every field optional, omitted fields keep their current value. */
+interface AgentApiUpdateRequest {
+    enabled?: boolean;
+    open?: boolean;
+    approvalMode?: ApprovalMode;
+    model?: ModelRefDto | null;
+    thinkingLevel?: ThinkingLevelName | null;
+    workspace?: string | null;
+    maxConcurrentRuns?: number;
+}
+/** POST …/api/keys body (owner only). */
+interface AgentApiKeyCreateRequest {
+    /** 1-64 characters. */
+    name: string;
+}
+/** The one response that carries the secret (`penguin_` + 43 base64url characters); only its hash is stored. */
+interface AgentApiKeyCreateResponse {
+    key: AgentApiKeyInfo;
+    secret: string;
+}
 /** 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. */
@@ -1163,16 +1589,119 @@ interface MemoryImportResponse {
     /** Whether the scope's `MEMORY.md` was written or extended. */
     indexWritten: boolean;
 }
+/** How far a Session's commands may reach the filesystem (the sandbox's confinement mode). */
+type SessionSandboxMode = "read-only" | "workspace-write" | "danger-full-access";
+/**
+ * The part of a Session's sandbox policy a person picks from the composer: the filesystem
+ * mode and the network level. The Session keeps its own copy — taken from the server's
+ * Sandbox settings when it was created — so editing those settings only changes what NEW
+ * Sessions start with.
+ */
+interface SessionSandbox {
+    mode: SessionSandboxMode;
+    /** `open` = unrestricted, `local` = only the host's localhost, `none` = no network. */
+    network: SessionSandboxNetwork;
+    /**
+     * Response only, ignored in requests: whether a sandbox backend on this server can enforce
+     * the `read-only` and `workspace-write` modes. False on a deployment with no backend
+     * installed, where either mode would refuse every command: the composer shows them greyed
+     * out, saying no backend is installed.
+     */
+    confinementSupported?: boolean;
+    /** Response only, ignored in requests: the same for the `none` network level. */
+    noNetworkSupported?: boolean;
+    /**
+     * Response only, ignored in requests: whether a sandbox backend on this server can enforce
+     * the `local` level. When false the composer shows it greyed out, and picking it is refused
+     * (400 `sandbox_unsupported`).
+     */
+    localNetworkSupported?: boolean;
+    /** Response only, ignored in requests: whether a backend here can enforce `masksPaths`. */
+    maskPathsSupported?: boolean;
+    /**
+     * Response only, ignored in requests: true when this policy hides paths (the Sandbox card's
+     * masked paths, kept by every pick). Where `maskPathsSupported` is false, every level then
+     * refuses every command, and the composer says so.
+     */
+    masksPaths?: boolean;
+    /**
+     * Response only, ignored in requests: the names of the sandbox backends in use here, which the
+     * composer names when a level is beyond what they enforce. Absent with none in use.
+     */
+    backendsInUse?: string[];
+    /**
+     * Response only, ignored in requests: the sandbox backends that are enabled here but failed
+     * to load or failed their check (a WSL distro not set up, a wrong program path), each with
+     * why. A backend for another platform is not listed. With none mounted and one listed, the
+     * composer marks the confining levels unavailable and gives the first one's reason.
+     */
+    unavailableBackends?: UnavailableSandboxBackend[];
+    /**
+     * Response only, ignored in requests: the server's sandbox presets (the Sandbox card's table),
+     * in table order, disabled rows included. The composer lists the enabled ones and names the
+     * Session's level by the first row matching its mode, network and approval mode. A server
+     * that does not report it gets the composer's built-in table.
+     */
+    presets?: SessionSandboxPreset[];
+    /**
+     * Response only, ignored in requests: true when this Session's policy holds something the
+     * presets do not show — masked paths, or the temp directory not writable.
+     */
+    advanced?: boolean;
+    /**
+     * Response only, chat defaults only: the approval mode a new Session starts with when its
+     * request names none — the Sandbox card's default preset's, while the switch is on. Absent:
+     * the server's own fallback (`allow-all`).
+     */
+    defaultApprovalMode?: ApprovalMode;
+    /**
+     * Response only, ignored in requests: the Sandbox card's switch on this server — whether new
+     * Sessions start confined. Off, the composer offers the approval modes alone (a Session keeps
+     * its own policy either way). A server that does not report it is read as on.
+     */
+    switchOn?: boolean;
+}
+/** One sandbox preset: a named mode, network level and approval mode. */
+interface SessionSandboxPreset {
+    id: string;
+    /** The name an administrator gave it, or its declared English name. */
+    name: string;
+    /** Its declared Chinese name, while it has not been renamed. */
+    nameZh?: string;
+    /** Whether the composer's menu lists it. */
+    enabled: boolean;
+    mode: SessionSandboxMode;
+    network: SessionSandboxNetwork;
+    approvalMode: ApprovalMode;
+    /**
+     * Response-only: its file mode or network is wider than the server's sandbox settings (the
+     * ceiling for non-admins), so a non-admin's pick of it is refused with `403 sandbox_forbidden`.
+     * The same comparison as that refusal; absent when it is within them.
+     */
+    aboveCeiling?: true;
+}
+/** An enabled sandbox backend that is not in use on this server, and why. */
+interface UnavailableSandboxBackend {
+    name: string;
+    reason: string;
+}
+/** The network levels, widest first. */
+type SessionSandboxNetwork = "open" | "local" | "none";
 interface SessionInfo {
     sessionId: string;
     projectId: string;
     agentId: string;
-    /** Provider group of the session's model (paired with `modelId` to form a model reference). */
+    /**
+     * Provider group of the session's **current** model (paired with `modelId` to form a model
+     * reference). It moves with each in-session switch (`POST /api/sessions/:id/switch-model`).
+     */
     provider: string;
-    /** Upstream model_id of the session's model (the request id sent to AgentHub). */
+    /** Upstream model_id of the session's current model (the request id sent to MMSP). */
     modelId: string;
     workspace: string;
     approvalMode: ApprovalMode;
+    /** The Session's own sandbox policy (see {@link SessionSandbox}). */
+    sandbox: SessionSandbox;
     /**
      * Thinking level pinned for this Session (set via PATCH; the Web App's in-chat picker).
      * Unset = never pinned: each model context the Session opens reads the Agent config's
@@ -1185,7 +1714,18 @@ interface SessionInfo {
     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. */
+    /**
+     * What kind of conversation this is, read from core session_meta — the single source of
+     * truth (the DB stores no source). With the user's marks it decides where the Session is
+     * listed (`archived`): a `user` Session is in the sidebar until archived; an `api`,
+     * `schedule`, `cli` or `workbench` Session is archived until the user keeps it, and in the sidebar marked
+     * with its source once kept; a `subagent` or `company` Session is in no list — its parent's
+     * Agent panel and company mode's own views open them. A Trace head that records no source
+     * (written before it was required) reads as `company` for a row the organization runtime
+     * opened (`client: "org"`), else as `user`; so does such a row before its first run. Absent
+     * only while any other row is not yet classified (its Trace head has not been read yet),
+     * which renders as `user`.
+     */
     source?: SessionSource;
     createdAt: string;
     /**
@@ -1211,7 +1751,13 @@ interface SessionInfo {
     pendingFollowUpCount: number;
     /** Whether a Trace record exists (a Task has been started). */
     hasTrace: boolean;
-    /** Whether archived (hidden from the default list, grouped under "Archived"). */
+    /**
+     * Whether the Session is archived — the listing rule's answer, never the bare mark: the user
+     * archived it, or a program opened it (source `api`, `schedule`, `cli` or `workbench`) and the user has
+     * not kept it. An archived Session is left out of the sidebar and listed on the archive page
+     * (`/api/me/archived-sessions`). Always false for a `subagent` or `company` Session, which is
+     * in no list.
+     */
     archived: boolean;
     /**
      * Absolute path of the session's latest Trace file (the current context shard); absent
@@ -1226,22 +1772,23 @@ interface SessionInfo {
     /**
      * Company mode: the organization that owns this Session — a desk session of one of its
      * employees, or a session contributing to one of its tickets — read from the organization
-     * caches. Absent for every ordinary Session. Development mode's list and its time buckets
-     * hide every row that carries it (only while company mode is available to that user: it is
-     * stamped either way, and company mode is what lists these Sessions instead), and the
-     * company sidebar's 工位 / 工单会话 groups are where they are listed.
+     * caches. Absent for every ordinary Session. Development mode's list asks the server to
+     * leave every such row out (`excludeOrg=1` on the list route — page and totals alike) and
+     * still drops one that reaches it by another door; the company sidebar's 工位 group and the
+     * tickets are where these Sessions are reached instead.
      */
     orgId?: string;
     /**
      * Which client opened the Session, as stored on the index row: "cli" from the CLI (a
      * Session adopted from a legacy CLI-direct Trace included), "org" from the organization
-     * runtime (a desk or a ticket session), "web" otherwise. Absent only on a row that
-     * predates the column, which reads as "web". Unlike {@link SessionInfo.orgId} — projected
-     * from the organization caches, so it disappears with the organization and is not read
-     * while company mode is off — this is a durable stamp on the row: development mode's list
-     * hides an "org" Session either way.
+     * runtime (a desk or a ticket session, and every sub-session one of those spawns), "api"
+     * from an Agent API run (the only Sessions the API may continue), "web" otherwise. Absent
+     * only on a row that predates the column, which reads as "web". Unlike
+     * {@link SessionInfo.orgId} — projected from the organization caches, so it disappears with
+     * the organization and is not read while company mode is off — this is a durable stamp on
+     * the row: development mode's list hides an "org" Session either way.
      */
-    client?: "web" | "cli" | "org";
+    client?: "web" | "cli" | "org" | "api" | "workbench";
     /**
      * Background work the Session's loaded runtime still owns: command sessions running past
      * their yield window (`exec_command` promotions and `run_in_background` launches) and
@@ -1261,45 +1808,241 @@ interface SessionBackgroundTasks {
     subagents: number;
 }
 /**
- * Session list category, the sidebar's five-way split applied server-side: archived wins
- * regardless of origin (archiving is an explicit user action), then the origin's bucket,
- * and a Session with no (or an unknown) source is `active` — user-created rows.
+ * Session list category, the listing rule applied server-side: `archived` when the user
+ * archived the Session, or when a program opened it (source `api`, `schedule`, `cli` or `workbench`) and the
+ * user has not kept it — unarchiving keeps it; otherwise `active`. A `subagent` or `company`
+ * Session belongs to neither, whatever its marks: the list leaves it out of every category and
+ * every total (a parent's Agent panel and company mode's own views open them).
  */
-type SessionCategory = "active" | SessionSource | "archived";
+type SessionCategory = "active" | "archived";
 /** Per-category totals across an Agent's whole Session list (returned when the list is requested with counts). */
 type SessionCategoryCounts = Record<SessionCategory, number>;
+/**
+ * GET /api/projects/:projectId/agents/:agentId/sessions. Every query parameter is optional:
+ *
+ * - `order`: `created` (the default) lists newest creation first; `activity` lists most recent
+ *   `lastActiveAt` first, ties broken by `sessionId` descending, both compared as plain strings
+ *   (code points, never locale collation) so a client can compute the same order.
+ * - `limit` (1–1000) with `offset` (≥ 0): an offset page, in either order. Offsets suit only the
+ *   `created` order, which activity never reshuffles.
+ * - `before=<lastActiveAt>,<sessionId>` with `limit`: under `order=activity` only, the rows
+ *   strictly below that cursor — the key of the last row the client holds. A row that becomes
+ *   active between pages moves above the cursor and is not served again, and no other row is
+ *   skipped (`session_state` tells the client about the moved one). 400 without
+ *   `order=activity`, beside `offset`, without `limit`, or when not a parseable stamp and a
+ *   valid id split at the first comma.
+ * - `category`, `workspaceGroup`, `excludeOrg=1` filter before paging; `counts=1` adds the
+ *   whole-list totals below, which no cursor or offset narrows. A request with `category`,
+ *   `workspaceGroup` or `counts=1` leaves every `subagent` and `company` Session out of the page
+ *   and the totals (they are in no category); one with none of them serves every row.
+ */
 interface SessionsResponse {
+    /**
+     * The page. With `excludeOrg=1` on the request, the rows an organization owns — its desk
+     * and ticket sessions and the sub-sessions they spawned — are left out of it and of every
+     * total below, so a caller drawing the user's own conversations is never handed a total
+     * for rows it will not be handed. Without the flag every row is served, whichever client
+     * created it.
+     */
     sessions: SessionInfo[];
     /** Present when the request asked for counts (`counts=1`): totals per category over the full list, not just the returned page. */
     counts?: SessionCategoryCounts;
     /**
      * Present with `counts`: the same totals broken down by Workspace path (only paths
      * with at least one Session appear). The sidebar's workspace grouping decides each
-     * group's folders and "More" from its own share, so a group never advertises
+     * group's existence and "More" from its own active share, so a group never advertises
      * content that lives in other Workspaces.
      */
     workspaceCounts?: Record<string, SessionCategoryCounts>;
     /**
      * Present with `counts`: each Workspace path's newest Session (any category), as its
-     * `createdAt`. With `workspaceCounts` this is what lets the sidebar list every Workspace
-     * that holds Sessions and place the groups by recency before — or without — loading any
-     * of their rows.
+     * `createdAt` — the Workspace picker's "recently used", which counts every Session that
+     * worked there.
      */
     workspaceLatest?: Record<string, string>;
+    /**
+     * Present with `counts`: each Workspace path's newest `active` Session, as its `createdAt`
+     * (a path holding none is absent). With `workspaceCounts` this is what lets the sidebar list
+     * every Workspace that holds conversations and place the groups by recency before — or
+     * without — loading any of their rows; an archived Session does not move a group it is not
+     * shown in.
+     */
+    workspaceLatestActive?: Record<string, string>;
+}
+/**
+ * The archive page's source filter: `user` is a conversation the user archived by hand (source
+ * `user`, or a row whose Trace has not been read yet); the other three are what a program
+ * opened. `subagent` and `company` Sessions are never archived, so never listed.
+ */
+type ArchivedSessionSource = "user" | "api" | "schedule" | "cli" | "workbench";
+/** Query of GET /api/me/archived-sessions/groups, and the part every archive query shares. */
+interface ArchivedSessionsQuery {
+    /** Case-insensitive substring of the title (the DB title, else the Trace's first-prompt title); at most 200 characters. */
+    q?: string;
+    source?: ArchivedSessionSource;
+    /** One Project the user can open (404 `project_not_found` otherwise); absent = every Project they own or are a member of. */
+    projectId?: string;
+}
+/** One group of the archive page: one Workspace of one Project. */
+interface ArchivedSessionGroup {
+    projectId: string;
+    projectName: string;
+    /** The Workspace path, as the sidebar groups it; `temp` for the merged temporary Workspaces. */
+    workspace: string;
+    /** Archived Sessions in the group matching the query. */
+    count: number;
+    /** The newest `lastActiveAt` in the group — the order the groups come in, newest first. */
+    latest: string;
+}
+/** GET /api/me/archived-sessions/groups. */
+interface ArchivedSessionGroupsResponse {
+    groups: ArchivedSessionGroup[];
+    /** Sum of the groups' counts. */
+    total: number;
+    /**
+     * The server's time when these counts were taken (ISO). A group's batch passes it as its
+     * filter's `until`, so it acts on the Sessions the count saw and on none that came after.
+     */
+    asOf: string;
+}
+/** Query of GET /api/me/archived-sessions: one group's page, newest activity first. */
+interface ArchivedSessionsRowsQuery extends ArchivedSessionsQuery {
+    projectId: string;
+    /** The group's `workspace` (a path, or `temp`). */
+    workspace: string;
+    /** 1–100. */
+    limit: number;
+    /** `<lastActiveAt>,<sessionId>` of the last row held, as the Session list's cursor. */
+    before?: string;
+}
+/** GET /api/me/archived-sessions. */
+interface ArchivedSessionsResponse {
+    /** `title` falls back to the Trace's first-prompt title when the row has none. */
+    sessions: SessionInfo[];
+    hasMore: boolean;
+}
+/** What an archive-page batch acts on: explicit ids (1–500), or every archived row a filter matches. */
+type ArchivedSessionsBatch = {
+    sessionIds: string[];
+} | {
+    filter: ArchivedSessionsBatchFilter;
+};
+/** A batch's filter: the archive query, one group's Workspace, and the snapshot it was counted at. */
+interface ArchivedSessionsBatchFilter extends ArchivedSessionsQuery {
+    workspace?: string;
+    /**
+     * The groups response's `asOf` the user acted on (ISO): only Sessions archived by then and
+     * not active since are acted on, so one archived or run after the count is left alone.
+     */
+    until?: string;
+    /** Sessions left out although the filter matches them — rows unticked after Select all (1–500). */
+    exclude?: string[];
+}
+/** POST /api/me/archived-sessions/unarchive and /delete. */
+interface ArchivedSessionsBatchResponse {
+    /**
+     * Sessions acted on. Unarchive counts only the ones that were archived. Delete counts every
+     * named one; a filter's delete leaves a running Session alone (it is not aborted) and does not
+     * count it.
+     */
+    done: number;
+    /** Ids that name nothing the user can open (the ids form only; a filter never reports any). */
+    missing: string[];
+}
+/**
+ * One page request inside POST /api/projects/:p/sessions/batch — the same knobs the
+ * Agent-level list takes, carried per entry so one call can stand in for a whole sidebar
+ * reload (one first page per Agent, plus every other page pair already open).
+ */
+interface SessionBatchPageRequest {
+    agentId: string;
+    /** Rows per page, 1–1000. */
+    limit: number;
+    /** `activity`: last activity first — the sidebar's order. Omitted: creation order. */
+    order?: "created" | "activity";
+    /** Rows to skip from the top (default 0). Not beside `before`. */
+    offset?: number;
+    /**
+     * Activity order only: rows strictly below this cursor — the last row of the previous page
+     * (`lastActiveAt` + `sessionId`, the pair the list endpoint's `before` param carries).
+     */
+    before?: {
+        lastActiveAt: string;
+        sessionId: string;
+    };
+    category?: SessionCategory;
+    workspaceGroup?: string;
+    /**
+     * Totals per category over the Agent's whole list, with the per-Workspace counts and newest
+     * stamps beside them (`counts=1` on the Agent-level list).
+     */
+    withCounts?: boolean;
+    /** The user's own rows only: leave an organization's own sessions out of page and totals. */
+    excludeOrg?: boolean;
+}
+/**
+ * One entry's answer. `ok: false` is a real answer about THAT Agent, never about the batch:
+ * `absent` is an Agent this server does not host (its rows come from the machine that does),
+ * `error` is a failure to answer at all — which the caller must not read as "no rows".
+ */
+type SessionBatchResult = ({
+    agentId: string;
+    ok: true;
+} & SessionsResponse) | {
+    agentId: string;
+    ok: false;
+    reason: "absent" | "error";
+};
+interface SessionsBatchRequest {
+    requests: SessionBatchPageRequest[];
+}
+interface SessionsBatchResponse {
+    /** One entry per requested page, in request order (repeated Agent ids stay repeated). */
+    results: SessionBatchResult[];
 }
-/** Server directory browsing (advanced new-Workspace picker): starts from the home directory by default, can navigate up to the root. */
+/** Server directory browsing (the Workspace picker): starts from the home directory by default, can navigate up to the root. */
 interface DirEntryInfo {
     name: string;
-    /** Absolute path of this subdirectory (can be submitted directly as a Workspace). */
+    /** Absolute path of this entry (a folder's can be submitted directly as a Workspace). */
+    path: string;
+    /**
+     * `file` for anything that is not a folder (a symlink counts as what it points to). Absent
+     * means a folder: a machine listed over ssh reports folders only.
+     */
+    kind?: "dir" | "file";
+    /** Last modification, epoch milliseconds; absent when unknown (listings over ssh, an entry stat could not reach). */
+    mtime?: number;
+    /** Hidden by the machine's own rules beyond the dot-name convention (Windows hidden/system attribute). */
+    hidden?: true;
+}
+/** A storage location the machine offers beside its folders: a Windows drive, a macOS volume, a Linux root or mount. */
+interface DirLocation {
+    /** Absolute path it opens (`C:\`, `/`, `/Volumes/USB`, `/media/me/USB`, `/mnt/c`). */
     path: string;
+    kind: "drive" | "removable" | "network" | "optical" | "volume" | "root";
+    /** The machine's own name for it (volume label, volume name, share `\\nas\media`, WSL `C:`); absent when none. */
+    label?: string;
+}
+/** The platform's standard folders as that machine resolves them; only those that exist. */
+interface DirStandardFolders {
+    desktop?: string;
+    documents?: string;
+    downloads?: string;
+    pictures?: string;
 }
 interface DirListResponse {
     /** Absolute path of the current directory (realpath). */
     path: string;
     /** Absolute path of the parent directory; null when already at the root. */
     parent: string | null;
-    /** Subdirectory list (sorted by name, files excluded). */
+    /** Entries sorted by name, hidden ones included (the picker drops them). */
     entries: DirEntryInfo[];
+    /** The listed machine's `process.platform`; absent for a machine listed over ssh. */
+    platform?: string;
+    /** Home request with `places=1` only. */
+    standardFolders?: DirStandardFolders;
+    /** Home request with `places=1` only, in the order the sidebar lists them. */
+    locations?: DirLocation[];
 }
 /** One Skill found in a picked directory: metadata plus which of the two layouts it came from. */
 interface DirectorySkillItem extends SkillMetadataItem {
@@ -1325,6 +2068,11 @@ interface SessionCreateRequest {
     workspace?: string;
     /** Defaults to allow-all. */
     approvalMode?: ApprovalMode;
+    /**
+     * The Session's sandbox policy; either half omitted takes the server's Sandbox settings.
+     * A non-admin may not pick anything looser than those settings (403 `sandbox_forbidden`).
+     */
+    sandbox?: Partial<SessionSandbox>;
     /**
      * Creating-client hint stored on the Session row: "cli" when the CLI creates the
      * Session through the API, "org" when the organization runtime opened it (a desk or a
@@ -1332,16 +2080,17 @@ interface SessionCreateRequest {
      * not the organization still exists); defaults to "web". A REQUEST may send only "web" or
      * "cli": the runtime writes "org" by calling the service directly, so no caller can claim
      * an organization's provenance for its own Session. Lists serve every row regardless of
-     * client; only development mode's session list filters on it.
+     * client unless asked for the user's own rows only (`excludeOrg=1`), which is what
+     * development mode's session list asks for.
      */
     client?: "web" | "cli" | "org";
     /**
-     * Marks the Session as created by a Benchmark evaluation or optimization (the Evaluation
-     * Center's Use flows, and the Test Sessions agent-evaluation launches through the CLI). Only
-     * this value is accepted from a client: `subagent` and `schedule` are written by the server
-     * itself. The Web App files such Sessions into the Evaluations folder of the session list.
+     * The Session's source, when it is not a person's conversation: only `cli` is accepted from
+     * a client (`penguin run` sends it); every other source is the server's own to write, and
+     * absent means `user`. The retired `benchmark` is still accepted, as `cli`, until 0.3.0, for
+     * an older CLI or Web App that still sends it.
      */
-    source?: "benchmark";
+    source?: "cli";
 }
 interface SessionCreateResponse {
     session: SessionInfo;
@@ -1369,6 +2118,11 @@ interface SessionResponse {
 }
 interface SessionPatchRequest {
     approvalMode?: ApprovalMode;
+    /**
+     * Change this Session's sandbox policy; applies from its next command. A non-admin may not
+     * pick anything looser than the server's Sandbox settings (403 `sandbox_forbidden`).
+     */
+    sandbox?: Partial<SessionSandbox>;
     /**
      * Pin this Session's thinking level (`none | low | medium | high | xhigh | max`, anything else
      * is a 400). It replaces the Agent-config fallback for this Session and applies from the
@@ -1377,7 +2131,11 @@ interface SessionPatchRequest {
      * is no unpin: the picker only offers concrete levels.
      */
     thinkingLevel?: ThinkingLevelName;
-    /** Archive / unarchive (default list hides archived). */
+    /**
+     * `true` archives (clears the keep mark); `false` unarchives and writes the keep mark, so a
+     * background Session stays in the sidebar through later runs. Announced as `session_archived`.
+     * 409 `session_not_listed` on a `subagent` or `company` Session, which is in no list.
+     */
     archived?: boolean;
     /** Manual rename; non-empty string, overrides the auto-generated title. */
     title?: string;
@@ -1413,7 +2171,10 @@ interface MessagesLiveTail {
  * only; the parameterless full read never carries it). A window is a run of whole
  * message-bearing units — one unit = one Task in the Web reducer's sense, opened by a
  * main-session user prompt — cut so that no pairing (tool_call/output), compaction span
- * or steering group ever splits across windows.
+ * or steering group ever splits across windows. Besides the unit count, a window stops
+ * before the unit that would take its serialized messages past 4 MiB, but always holds at
+ * least one unit; such a window carries `before` like any other, with fewer units than
+ * asked for.
  */
 interface MessagesPageInfo {
     /**
@@ -1449,9 +2210,31 @@ interface MessagesPageInfo {
         sessionTokens: number;
         contextTokens: number;
     };
+    /**
+     * The model of the context this window starts in — what the `session_meta` heading that
+     * context's Trace file names. A Session can switch models between contexts, and a window
+     * that starts partway into one does not hold that record: the client seeds it, so the Tasks
+     * ahead of the window's first `session_meta` have their model, and a switch further down the
+     * window is told from a plain rotation. Absent when the Session has no Trace yet.
+     */
+    contextModel?: ModelRefDto;
+    /**
+     * Agent State directory recorded by the starting context's `session_meta`. Seeds memory
+     * change detection when that record falls before the window. Absent without a Trace.
+     */
+    agentState?: string;
 }
 /** Message history: the full messages and events from concatenating all of this Session's Trace files in order (excludes partial_*). */
 interface MessagesResponse {
+    /**
+     * On windowed requests, images are served by reference: in every record that carries a
+     * `tracePosition`, an inline PNG / JPEG / GIF / WebP `data:` URL — a user `image_url`, or
+     * an entry of a tool output's `images` — is replaced by
+     * `/api/sessions/<sessionId>/trace-image?file=<fileIndex>&ordinal=<ordinal>[&i=<k>]`
+     * (`i` = the index into `images`), an immutable, access-checked image response. Expanded
+     * subagent messages, held inputs not yet in the Trace, other image types and the
+     * parameterless full read keep their data URLs.
+     */
     messages: HistoryMessage[];
     /**
      * Present only while the Session is running/compacting: the in-progress stream tail
@@ -1534,6 +2317,32 @@ interface GoalResponse {
     /** The Session's most recent goal run; null if it never ran one. */
     goal: GoalStateView | null;
 }
+/**
+ * `POST /api/sessions/:sessionId/switch-model`: switch this Session to another model in place.
+ * The running context is closed on the model it ran on, then the next one opens on the target.
+ *
+ * - **202** {@link TaskCreateResponse} — the switch streams, the Session status `compacting`.
+ *   A context with a completed turn is closed by an ordinary `manual` compaction pair (always
+ *   summarize); one without — just compacted, or its first request never finished — has
+ *   nothing to summarize and streams no pair. Then come the new context's opener records
+ *   and, last, its `session_meta`: its `provider` / `model_id` name the model the Session now
+ *   runs on, the Session reads report that pair from this record on, and `task_state` turns
+ *   idle after it.
+ *   A compaction that ends other than `completed` means no switch — no `session_meta` follows
+ *   and the Session keeps its model.
+ * - **200** {@link SessionResponse} — a Session that never ran has no context to close: it
+ *   switched inside the request, and nothing is streamed.
+ * - **409**, one code per refusal, before any event: `task_in_progress` / `compacting` (busy),
+ *   `same_model`, `model_not_configured` (the target is not in the Project config),
+ *   `model_unavailable` (its client cannot be constructed, e.g. no credential), and
+ *   `compaction_not_configured`.
+ */
+interface SessionSwitchModelRequest {
+    /** Provider group of the target model. */
+    provider: string;
+    /** Upstream model_id of the target model. */
+    modelId: string;
+}
 interface TaskCreateResponse {
     /** Current actual session_id: a Trace-less invalid Session self-heals and returns a new id; the frontend updates its route accordingly. */
     sessionId: string;
@@ -1735,6 +2544,20 @@ interface MessagingRuntimeStatus {
         at: string;
         detail: string;
     };
+    /**
+     * Since when (ISO 8601) the bot has been HOLDING replies it could not deliver yet, to send
+     * them with the chat's next inbound message; absent while nothing is held. WeChat only: the
+     * platform accepts a bot's messages only for a while after the user's last one, and only
+     * about ten per message, so a long run or a quiet user leaves replies waiting rather than
+     * lost.
+     *
+     * Not a failure, and deliberately not `lastDeliveryError`: nothing is broken and nobody has
+     * to act beyond what the panel says — message the bot in WeChat and the held replies arrive
+     * first. Cleared the moment they have been delivered. Unlike the fields above it is not
+     * scoped to one connection: held replies are stored, so a backlog from before a restart is
+     * reported again as soon as the connection opens.
+     */
+    heldReplySince?: string;
 }
 /**
  * What a messaging binding carries whatever channel it is: the connection intent, the three
@@ -2228,11 +3051,17 @@ type ServerEvent =
  * 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.
  *
+ * `projectId` names the Session's Project: a list showing one Project ignores another's flips
+ * without a request, and a flip for a Session of its own Project that it holds no row for is a
+ * row it is missing — one that became active below its activity cursor (see SessionsResponse) —
+ * which it fetches by id.
+ *
  * Published only to the user channels of the Project's owner and members.
  */
  | {
     type: "session_state";
     sessionId: string;
+    projectId: string;
     state: SessionStatus;
     lastActiveAt: string;
     hasTrace: boolean;
@@ -2250,6 +3079,19 @@ type ServerEvent =
     processes: number;
     subagents: number;
 }
+/**
+ * A Session's count of tool calls waiting for a person's approval changed: a call was
+ * escalated (every call under always-ask, rw/unknown calls under read-only), answered, or
+ * denied by an interrupt. The count is the row's `pendingApprovalCount` as it stands after
+ * the change, zeros included, so a list moves its mark without refetching; the calls
+ * themselves are on the Session's own stream (`approval_request`, replayed on subscribe).
+ * Published to the user channels of the Project's owner and members, like `session_state`.
+ */
+ | {
+    type: "session_approvals";
+    sessionId: string;
+    count: number;
+}
 /** 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";
@@ -2273,22 +3115,75 @@ type ServerEvent =
     type: "web_updated";
     rev: string;
 }
-/** New session registered (pushed over the parent session's channel for subagent sessions): frontend refreshes the list in place. */
+/**
+ * A Session now exists. On the user channel for every creation — the CLI, another tab,
+ * a schedule, an agent spawning a child — so the list learns about rows it did not make;
+ * and on the parent Session's channel for a subagent, which no list shows. `source` is what
+ * the new Session's meta records, and it tells a client which list, if any, the row joins.
+ */
  | {
     type: "session_created";
     projectId: string;
     agentId: string;
     sessionId: string;
     source: SessionSource;
-} | ScheduleServerEvent | GoalServerEvent | CompanyServerEvent;
-/** Goal-mode progress on the session channel (the chat page drives its goal banner from these). */
-type GoalServerEvent = 
-/** A goal run began (published before the first round). */
-{
-    type: "goal_started";
-    sessionId: string;
-    objective: string;
-    budget: number;
+}
+/**
+ * The user's listing decision on one Session changed (PATCH `archived`, the archive page's
+ * batch unarchive): an archived row leaves the sidebar, an unarchived one joins it. One per
+ * Session, to the Project's users.
+ */
+ | {
+    type: "session_archived";
+    sessionId: string;
+    projectId: string;
+    agentId: string;
+    archived: boolean;
+}
+/**
+ * A Session was deleted (DELETE, the subagent children deleted with it, the archive page's
+ * batch delete): every client drops the row. One per Session, to the Project's users.
+ */
+ | {
+    type: "session_deleted";
+    sessionId: string;
+    projectId: string;
+} | ScheduleServerEvent | GoalServerEvent | CompanyServerEvent | BuiltinBrowserServerEvent | MachineServerEvent;
+/**
+ * The machines' two events on the user channel, published to admins only — the Machines page,
+ * and the `/server/<id>` proxy everything else about a machine goes through, are admin-only.
+ */
+type MachineServerEvent = 
+/**
+ * Something the machines list reports changed — a job queued, started, moved to its next
+ * step, logged a line or ended; a connection was held or dropped; a reconnect began, failed
+ * or succeeded; a machine joined or left a Project; a checkout's install image started or
+ * finished building. No payload: a page re-reads `GET …/machines`, which is its one account
+ * of every machine. Coalesced, so a burst of log lines costs a few reads, not one per line.
+ */
+{
+    type: "machines_changed";
+}
+/**
+ * One of a connected machine's own user-channel events, relayed by this server from that
+ * machine's `GET /api/events` (machines/event-relay.ts). The page holds one event stream to
+ * this server whatever the number of machines: a stream per machine made five connected
+ * machines take the browser's whole HTTP/1.1 allowance of six connections to one origin, and
+ * every other request of the page then waited behind them for good.
+ */
+ | {
+    type: "machine_event";
+    machineId: string;
+    event: ServerEvent;
+};
+/** Goal-mode progress on the session channel (the chat page drives its goal banner from these). */
+type GoalServerEvent = 
+/** A goal run began (published before the first round). */
+{
+    type: "goal_started";
+    sessionId: string;
+    objective: string;
+    budget: number;
 }
 /** A round is starting; `used` is the runner's accounting up to this point. */
  | {
@@ -2323,6 +3218,20 @@ type ScheduleServerEvent =
     agentId: string;
     name: string;
     sessionId: string;
+}
+/** A workbench of the Agent was (re)loaded — its folder changed, a reload was requested, or a version was restored. */
+ | {
+    type: "workbench_updated";
+    projectId: string;
+    agentId: string;
+    workbench: WorkbenchInfo;
+}
+/** A workbench's folder is gone — removed from the Web App or deleted on disk. */
+ | {
+    type: "workbench_removed";
+    projectId: string;
+    agentId: string;
+    workbenchId: string;
 };
 interface TraceFileInfo {
     /** Trace file index (one file corresponds to one complete model context). */
@@ -2405,7 +3314,10 @@ interface TraceEventsResponse {
     events: OmniMessage[];
     offset: number;
     limit: number;
-    /** Total line count of the file (basis for pagination). */
+    /**
+     * Record count of the file (basis for pagination), in the ordinals `tracePosition` and the
+     * analysis' `messageFrom` / `messageTo` use: malformed lines are not records.
+     */
     total: number;
 }
 /** Duration span of a single LLM Request (request_begin/request_end paired by proximity). */
@@ -2557,7 +3469,11 @@ interface WorkspaceFilesResponse {
     path: string;
     entries: WorkspaceFileEntry[];
 }
-/** Write one Workspace file whole (the Upload button, a drop, and the Files panel's editor). */
+/**
+ * Write one Workspace file whole (the Upload button, a drop, and the Files panel's editor). A
+ * write answers 204 with the written file's version in `ETag` — the marker the next conditional
+ * write of the same file carries, so an editor can keep editing after a save.
+ */
 interface FilesWriteRequest {
     /** The entire file, base64-encoded (≤14MB decoded). */
     dataBase64: string;
@@ -2572,7 +3488,7 @@ interface FilesWriteRequest {
      */
     ifVersion?: string;
 }
-/** Move or rename one Workspace file (the Files panel's context menu). */
+/** Move or rename one Workspace file or folder (the Files panel's context menu). */
 interface FilesMoveRequest {
     /** Source path, relative to the Workspace root. */
     from: string;
@@ -2585,12 +3501,23 @@ interface FilesMoveRequest {
      * has none, because the caller never read it, which is why an occupied destination is
      * refused with 409 `target_exists` rather than overwritten.
      *
-     * A directory `from` is a 400 whatever this field says: a directory carries no single
-     * version marker, so the precondition that protects this operation cannot be expressed for
-     * one, and silently moving a tree without that protection is worse than refusing to move it.
+     * A directory `from` takes none, and one sent with it is a 400: a directory carries no
+     * single version marker, so no precondition can be stated for it. A folder moves whole and
+     * unconditionally — nothing is lost that way, since whatever the Agent wrote into it meanwhile
+     * moves with it — and is refused only when the destination is occupied or lies inside it.
      */
     ifVersion?: string;
 }
+/**
+ * Create one empty text file or one folder in a Workspace (the Files panel's New menu). Missing
+ * parent directories are created as a write creates them. Anything already at `path` — a file,
+ * a folder or a link — is refused with 409 `target_exists` and nothing is written.
+ */
+interface FilesCreateRequest {
+    /** The new entry's path, relative to the Workspace root. */
+    path: string;
+    kind: "file" | "dir";
+}
 /**
  * One Workspace search match. `kind`, `sizeBytes` and `mtime` are named and typed exactly as
  * {@link WorkspaceFileEntry} names them: a hit is drawn by the same row renderer as a tree
@@ -2701,6 +3628,19 @@ interface TraceAnalysisResponse {
      * scope every total here shares). Absent exactly when the turns carry no `cost`.
      */
     cost?: number;
+    /**
+     * `cost` split by pricing bucket: every Request's Tokens at the rates and tier its share of
+     * `cost` was priced at, summed per bucket over the file. Present exactly when `cost` is; the
+     * turns carry no split.
+     */
+    costParts?: CostParts;
+    /**
+     * The model's context window as the file's head `session_meta` records it
+     * (`model_context_window`), for the context ring. The panel no longer reads every event, so the
+     * analysis carries it; absent when the head records none (an older server, or a file without
+     * one), and the panel then falls back as it always has.
+     */
+    modelContextWindow?: number | string;
     requests: RequestSpan[];
     /** Token / duration aggregated per Task (used directly by the Trace page's context ring and per-turn TPS). */
     tasks: TraceTaskStats[];
@@ -2793,6 +3733,17 @@ interface TraceImportResponse {
     date: string;
 }
 type UsageGroupBy = "date" | "agent" | "model" | "session";
+/**
+ * A cost split by the three pricing buckets, in USD: cached input (`cacheRead`), uncached input
+ * (`cacheWrite`, input Tokens on a cache miss) and output. Each part is its bucket's Tokens at the
+ * rate the whole cost was priced at, so the three sum to the cost they accompany (up to
+ * floating-point rounding).
+ */
+interface CostParts {
+    cacheRead: number;
+    cacheWrite: number;
+    output: number;
+}
 interface UsageBucket {
     total: number;
     requests: number;
@@ -2812,6 +3763,12 @@ interface UsageGroupRow {
     total: number;
     requests: number;
     cost: number | null;
+    /**
+     * `cost` split by pricing bucket, each record at the same rates, tier and promotion that
+     * priced it in `cost`. Present exactly when `cost` is not null; a row's unpriced usage is in
+     * neither.
+     */
+    costParts?: CostParts;
     hasUncosted: boolean;
 }
 /** Time-series precision for the usage series (`granularity` query parameter). `minute` requires the `fromTs`/`toTs` window bounds. */
@@ -2886,13 +3843,22 @@ interface UsageErrorCount {
     kind: string;
     count: number;
 }
-/** A single error summary (one row in the stats center's error panel table). */
+/**
+ * One row of the stats center's error panel table: the records of one calendar day that share
+ * a source, code, kind and message. The day is the viewer's when the request carried
+ * `utcOffsetMinutes`, and the server's own otherwise.
+ */
 interface UsageErrorItem {
+    /** The latest of the records this row stands for. */
     ts: string;
     source: string;
     code: string;
     kind: string;
     message: string;
+    /** How many records this row stands for (the panel's "×N"). */
+    count: number;
+    /** The earliest of them; equal to `ts` for a single record. */
+    firstTs: string;
 }
 /**
  * Server-side error capture stats: not affected by the model
@@ -2903,14 +3869,16 @@ interface UsageErrorItem {
  * items.
  */
 interface UsageErrors {
-    /** Filtered row count — also what a clear of the same filter takes (see {@link UsageErrorsClearResponse}). */
+    /** Filtered record count — also what a clear of the same filter takes (see {@link UsageErrorsClearResponse}). */
     total: number;
     /** Count of unexpected ones (500 / runtime exceptions) among them — the part the frontend highlights. */
     unexpected: number;
     /** The most frequent source · code (null when there are no errors). */
     topCode: UsageErrorCount | null;
-    /** Most recent N items (reverse chronological) — the first page; older ones come from `GET /usage/errors`. */
+    /** Most recent N rows (reverse chronological) — the first page; older ones come from `GET /usage/errors`. */
     recent: UsageErrorItem[];
+    /** How many rows the table has for this filter (records folded per {@link UsageErrorItem}) — what the pager counts. */
+    rows: number;
 }
 /**
  * GET /api/projects/:projectId/usage/errors — one page of the error detail table, newest
@@ -2920,12 +3888,15 @@ interface UsageErrors {
  * or neither), so a page never widens what the summary counted, plus an optional `kind`
  * ({@link UsageErrorKind}) narrowing to one of the two categories — which
  * is how the cost-center badge asks "are there unexpected errors, and how new is the newest"
- * with `limit=1` instead of pulling the whole dashboard aggregate.
+ * with `limit=1` instead of pulling the whole dashboard aggregate. `utcOffsetMinutes` (minutes
+ * east of UTC, the dashboard takes it too) says whose calendar day a row's records share.
  */
 interface UsageErrorsPage {
     items: UsageErrorItem[];
-    /** Filtered row count, so the caller knows when it has reached the end. */
+    /** Filtered record count — the occurrences, which is what the cost-center badge counts. */
     total: number;
+    /** Filtered row count (records folded per {@link UsageErrorItem}), so the caller knows when it has reached the end. */
+    rows: number;
 }
 /**
  * DELETE /api/projects/:projectId/usage/errors — empties the error table for the filter the
@@ -3016,6 +3987,23 @@ interface SchedulesResponse {
         error: string;
     }>;
 }
+/**
+ * One task in the Project-wide listing (GET /api/projects/:projectId/schedules): the agent's
+ * item plus the agent whose schedule directory holds it, since the list spans every agent.
+ */
+interface ProjectScheduleItem extends ScheduleItem {
+    agentId: string;
+}
+interface ProjectSchedulesResponse {
+    /** Every agent's tasks: agents in id order, each agent's tasks in the order its own listing returns them. */
+    schedules: ProjectScheduleItem[];
+    /** Files that failed to parse (skipped from scheduling and logged as errors), with the agent that holds each. */
+    invalidFiles: Array<{
+        agentId: string;
+        name: string;
+        error: string;
+    }>;
+}
 interface ScheduleUpsertRequest {
     prompt: string;
     enabled: boolean;
@@ -3095,13 +4083,43 @@ interface BenchmarkEvaluation {
  * `BenchmarkSummary.status`.
  */
 type BenchmarkStatus = "draft" | "published" | "failed";
+/**
+ * Where a Benchmark's copy came from: `builtin` (seeded when the Project was created), `manual`
+ * (the create form), `agent` (the benchmark-design Skill wrote it), `git` (an Agent imported a
+ * repository folder), `zip` (an uploaded package).
+ */
+type BenchmarkOriginKind = "builtin" | "manual" | "agent" | "git" | "zip";
+/**
+ * Why a Benchmark's manifest cannot be read: the code of core's `BenchmarkManifestError`
+ * (`benchmark_id_mismatch` for an `id` that is not the directory's, `benchmark_manifest_invalid`
+ * for a file that is not TOML or a `version` or `[origin]` out of shape) and its message, which
+ * names the key or the file.
+ */
+interface BenchmarkManifestProblem {
+    code: string;
+    message: string;
+}
+/** The `[origin]` table of a Benchmark's benchmark_config.toml. */
+interface BenchmarkOrigin {
+    kind: BenchmarkOriginKind;
+    /** git: the folder link as the user gave it (a GitHub tree URL). Always an http(s) URL. */
+    url?: string;
+    /** git: the 40-hex commit the import resolved the link to. */
+    ref?: string;
+    /** git: the folder inside the repository. */
+    path?: string;
+    /** git / zip: when this copy was written (ISO 8601; `imported_at` in the file). */
+    importedAt?: string;
+}
 interface BenchmarkSummary {
     /** Directory name is the identifier (semantic naming, e.g. swe-bench-v1). */
     id: string;
-    /** Title from benchmark_config.toml; falls back to the directory name if unset. */
+    /** Title from benchmark_config.toml; the directory name when it gives none or the manifest cannot be read. */
     title: string;
     description?: string;
-    /** Number of runs per case (the `runs` field in benchmark_config.toml, ≥1; defaults to 1). */
+    /** The description in Chinese (`description_zh` in benchmark_config.toml), when the manifest gives one. */
+    descriptionZh?: string;
+    /** Number of runs per case (the `runs` key in benchmark_config.toml, an integer ≥ 1); absent when it gives none or the manifest cannot be read, which reads as 1. */
     runs?: number;
     /**
      * `draft` while the Skill that builds the Benchmark is still writing its cases and
@@ -3109,10 +4127,29 @@ interface BenchmarkSummary {
      * Benchmark is frozen and its Formal Baseline recorded; `failed` when calibration ended
      * without a Pilot result that could be frozen, which leaves the Benchmark unusable — the Web
      * App masks it too and says it has to be deleted and created again. benchmark_config.toml is
-     * read literally: only `draft` is a draft and only `failed` is a failure, so a missing field,
-     * or any other value, reads as published.
+     * read literally: only `draft` is a draft and only `failed` is a failure, so a missing key, or
+     * any other value, reads as published. A Benchmark whose manifest cannot be read lists as
+     * failed, with `manifestError`.
      */
     status: BenchmarkStatus;
+    /**
+     * The manifest's date version, `YYYY.MM.DD.N`: the revision of the Benchmark's content. Absent
+     * when the manifest has none (one written before versions is unversioned), when it cannot be
+     * read, and from a machine whose server predates versions.
+     */
+    version?: string;
+    /**
+     * Where this copy came from, the manifest's `[origin]`. Absent when the manifest has none (where
+     * a copy written before origins came from is unknown), when it cannot be read, and from a
+     * machine whose server predates origins.
+     */
+    origin?: BenchmarkOrigin;
+    /**
+     * Set when the manifest cannot be read. Such a Benchmark lists under its directory name, as
+     * `failed`, with no version or origin, and nothing may use or export it until the file is
+     * fixed; the Web App masks it with this reason.
+     */
+    manifestError?: BenchmarkManifestProblem;
     /** Case count (number of case subfolders). */
     caseCount: number;
     /** Time-ordered evaluation records (the evaluations[] in scoreboard.yaml). */
@@ -3139,10 +4176,11 @@ interface BenchmarkCasesResponse {
 }
 /**
  * POST /api/projects/:p/benchmarks (owner only): create a Benchmark by hand. The
- * server writes the on-disk layout the evaluation Skills read — `benchmark_config.toml`, a
- * `scoreboard.yaml` holding `evaluations: []`, and one `<case id>/` per case with
- * `statement/README.md` and `rubric/README.md`. 409 `benchmark_exists` when the directory is
- * already there; nothing is merged into an existing Benchmark.
+ * server writes the on-disk layout the evaluation Skills read — `benchmark_config.toml`
+ * (published, the day's first version, origin `manual`), a `scoreboard.yaml` holding
+ * `evaluations: []`, and one `<case id>/` per case with `statement/README.md` and
+ * `rubric/README.md`. 409 `benchmark_exists` when the directory is already there; nothing is
+ * merged into an existing Benchmark.
  */
 interface BenchmarkCreateRequest {
     /** Directory name, which is the identifier: letters, digits, `_` and `-` only. */
@@ -3167,6 +4205,47 @@ interface BenchmarkCreateCase {
 interface BenchmarkCreateResponse {
     benchmark: BenchmarkSummary;
 }
+/**
+ * POST /api/projects/:p/benchmarks/archive (any Project member): import a Benchmark package from
+ * a zip. The zip holds `benchmark_config.toml` and the `CASE-*` directories, at its root (where the
+ * manifest must name its `id`) or inside exactly one top-level directory named by the Benchmark's
+ * id — the shape `GET …/benchmarks/:benchmarkId/archive` exports. A zip carrying
+ * `scoreboard.yaml`, `.jobs/` or anything else at its top level, a link, a manifest past the
+ * create form's limits, a package that is not `published` or a case without both READMEs is
+ * refused (400); so is a zip past the caps (413 `benchmark_too_large`: 14MB
+ * zipped, 1000 files, 5MB a file, 20MB inflated). The copy is written with origin `zip` and an
+ * empty scoreboard — or origin `git`, when the request says the package is a repository folder
+ * fetched at a commit. An id already taken is 409 `benchmark_exists` (`details.benchmarkId` names
+ * it) unless `overwrite`.
+ */
+interface BenchmarkArchiveImportRequest {
+    /** The zip, base64-encoded. */
+    dataBase64: string;
+    /**
+     * Replace the Benchmark of the same id whole — its evaluation records and `.jobs/` included.
+     * Refused with 409 `benchmark_busy` while an evaluation of it is still running a trial there.
+     */
+    overwrite?: boolean;
+    /**
+     * The repository folder the package was fetched from, pinned to one commit. The copy's origin
+     * is then `git` with these fields and the import time, instead of `zip`.
+     */
+    origin?: BenchmarkArchiveGitOrigin;
+}
+/** Where a package fetched from a git repository came from. */
+interface BenchmarkArchiveGitOrigin {
+    kind: "git";
+    /** The folder link as the user gave it: an http(s) URL, at most 2048 characters. */
+    url: string;
+    /** The 40-character commit the link was resolved to. */
+    ref: string;
+    /** The folder inside the repository, at most 1024 characters. */
+    path: string;
+}
+interface BenchmarkArchiveImportResponse {
+    /** The imported Benchmark, as the list now reads it. */
+    benchmark: BenchmarkSummary;
+}
 interface SkillMetadataItem {
     /** Skill directory name (the identity key for install / uninstall / Prompt addressing). */
     name: string;
@@ -3181,7 +4260,7 @@ interface SkillMetadataItem {
      * which the plugin item carries once. Absent, the frontend draws the book glyph.
      */
     icon?: string;
-    /** Version (`YYYY.MM.DD.N`, frontmatter version; a copy installed before that spelling still carries `YYYY-MM-DD.N`); an empty string when the frontmatter carries none or a malformed one. */
+    /** The skill's own dated version (`YYYY.MM.DD.N`, frontmatter version; a copy installed before that spelling still carries `YYYY-MM-DD.N`); an empty string when the frontmatter carries none or a malformed one. */
     version: string;
 }
 /** One installed hook package (`agent_state/hooks/<name>/`): its manifest, without the scripts. */
@@ -3197,21 +4276,81 @@ interface HookItem {
     /** The plugin's raw icon.svg, written beside the manifest at install time; absent when the plugin ships none (the frontend draws the hook glyph). */
     icon?: string;
 }
-/** One library plugin as the listing describes it: the manifest fields plus what it ships (skill bodies and scripts are never sent). */
+/**
+ * One library plugin as the listing describes it: the manifest fields (its package.json — npm's
+ * fields and the `penguin` block) plus what it ships (skill bodies and scripts are never sent).
+ * Every field but the identity, the version and the contents is optional: a field the package
+ * does not carry is missing here, and the page says so rather than inventing one.
+ */
 interface PluginItem {
     name: string;
+    /** Display name (`penguin.title`, `title_zh`); absent → the page shows `name`. */
+    title?: string;
+    titleZh?: string;
+    /** English one-liner (package.json `description`); "" when the package carries none. */
     description: string;
     descriptionZh?: string;
     shortDescription?: string;
     shortDescriptionZh?: string;
-    /** `YYYY.MM.DD.N`. */
+    /** The plugin's npm version (its package.json, following the release) — what the card shows. Installed copies are compared part by part instead: each skill's `version`, and {@link hookVersion}. */
     version: string;
-    /** The plugin's skills (metadata only). */
+    /** The npm package the plugin is, e.g. `@penguinharness/a2ui` — what Delete and a server module's row name it by. */
+    package: string;
+    /** Where the plugin comes from: `builtin` — a package this build ships; `installed` — one an admin installed on the server (by name, link or zip). */
+    source: "builtin" | "installed";
+    /** The package's npm `author` (a name), `license`, `homepage` and `repository` URL, for the detail dialog. */
+    author?: string;
+    license?: string;
+    homepage?: string;
+    repository?: string;
+    /** The plugin's skills (metadata only), each with its own dated `version`. */
     skills: SkillMetadataItem[];
+    workbenches?: Array<{
+        name: string;
+        version: string;
+    }>;
     /** The hook points the plugin's hook package answers at (`[]` without one). */
     hooks: string[];
-    /** The plugin's raw icon.svg (beside plugin.json — every built-in plugin ships one), the icon of everything it ships; the frontend draws the puzzle-piece plugin glyph without it. */
+    /** The hook package's own dated version (`penguin.hooks.version`, `YYYY.MM.DD.N`); absent without a hook package. */
+    hookVersion?: string;
+    /** The plugin's raw icon SVG (`icon.svg` at the package root, or `penguin.icon` — every built-in plugin ships one; an unsafe one is never sent), the icon of everything it ships; the frontend draws the puzzle-piece plugin glyph without it. */
     icon?: string;
+    /** The demo the Plugins page's quick start pre-fills (`penguin.quick_start`); absent = pre-select its first skill. */
+    quickStart?: QuickStartItem;
+    /** The MCP servers the plugin installs into an Agent's `tools.mcpServers` (`penguin.mcp_servers`); `[]` without any. */
+    mcpServers: PluginMcpServerItem[];
+}
+/** An MCP transport, as an entry resolves it (`transport`, else inferred from `command` / `url`). */
+type McpTransport = "stdio" | "http" | "sse";
+/** One vault key a plugin's MCP server needs before it can connect: declared in the manifest, or only referenced (then the key is all there is to show). */
+interface PluginSetupKeyItem {
+    key: string;
+    label?: string;
+    labelZh?: string;
+    /** Where to get the value (a URL), or one sentence. */
+    help?: string;
+}
+/** A plugin's MCP server as the library lists it: identity and target only — no header, env or oauth value. */
+interface PluginMcpServerItem {
+    name: string;
+    transport: McpTransport;
+    /** The URL (http/sse), or `command args…` (stdio), as written: `${PLUGIN_ROOT}` and `${KEY}` references unresolved. */
+    target: string;
+    /** Every vault key the server's config references, declared ones first. */
+    setup: PluginSetupKeyItem[];
+    /** The server offers OAuth sign-in (`config.oauth`). */
+    oauth: boolean;
+    /** It needs that sign-in — OAuth and no `Authorization` header of its own — which this version cannot do: an Agent skips it. */
+    signIn: boolean;
+}
+/** A quick start: a prompt pre-filled into a new-chat draft — never sent by the page. */
+interface QuickStartItem {
+    prompt: string;
+    promptZh?: string;
+    /** Skills to pre-select (a library plugin's own). */
+    skills?: string[];
+    /** Open the draft in goal mode. */
+    goal?: boolean;
 }
 interface PluginGroupItem {
     id: string;
@@ -3243,8 +4382,35 @@ interface PluginInstallRequest {
     names: string[];
 }
 interface AgentPluginsInstallResponse {
+    workbenches?: Array<{
+        name: string;
+        plugin: string;
+        version: string;
+    }>;
     skills: SkillMetadataItem[];
     hooks: HookItem[];
+    /** The Agent's MCP servers after the install (a plugin's servers join its `tools.mcpServers`). A server name the Agent already has from someone else is 409 `mcp_server_name_taken`, nothing installed. */
+    mcpServers: AgentMcpServerItem[];
+}
+/**
+ * One `tools.mcpServers` entry of an Agent, as the Plugins page and the Agent settings read it:
+ * identity, target and what keeps it from connecting — never a header, env or oauth value.
+ */
+interface AgentMcpServerItem {
+    name: string;
+    transport: McpTransport;
+    /** The URL (http/sse), or `command args…` (stdio): `${PLUGIN_ROOT}` already resolved at install, `${KEY}` references left as written. */
+    target: string;
+    /** The plugin that installed it; absent for an entry the user added. */
+    plugin?: string;
+    /** `${KEY}` references of its config that the Agent's vault does not hold (names only); empty = nothing to set up. */
+    missingKeys: string[];
+    /** It needs an OAuth sign-in, which this version cannot do: skipped at connect time. */
+    signIn: boolean;
+}
+/** GET /api/projects/:p/agents/:a/mcp-servers: the Agent's MCP servers in config order; DELETE …/mcp-servers/:name removes one (204, 404 `unknown_mcp_server`). */
+interface AgentMcpServersResponse {
+    servers: AgentMcpServerItem[];
 }
 /** GET /api/projects/:p/agents/:a/skills: Skills installed on this Agent. */
 interface AgentSkillsResponse {
@@ -3280,6 +4446,95 @@ interface SkillArchiveInstallRequest {
     /** Replace an already-installed Skill of the same name (deletes its directory first). */
     overwrite?: boolean;
 }
+/**
+ * One published version of a plugin — the index entry format every plugin registry
+ * speaks (modeled on the typst/packages `index.json` schema: a flat array of
+ * per-version entries; a plugin published at several versions appears once per
+ * version). Installation is out of scope here: an entry's `name` is the package
+ * specifier a Project's plugin list names.
+ */
+interface PluginIndexEntry {
+    /** Package specifier — the string a Project's plugin list names. */
+    name: string;
+    /** Localized display names; the UI falls back to the package name. */
+    title?: string;
+    titleZh?: string;
+    /** Semantic version of this entry. */
+    version: string;
+    description: string;
+    /** Chinese description (optional; the UI picks per language, English without it). */
+    descriptionZh?: string;
+    /** One-line descriptions for the card (optional; the card falls back to `description`). */
+    shortDescription?: string;
+    shortDescriptionZh?: string;
+    /**
+     * The plugin's raw icon SVG (optional; the card draws the puzzle piece without it). The
+     * listing fills these display fields from the package's own package.json (its `penguin`
+     * block) and icon when the package is on this server, over whatever the index row says.
+     */
+    icon?: string;
+    authors: string[];
+    /** SPDX license identifier. */
+    license: string;
+    /** Source repository URL. */
+    repository?: string;
+    homepage?: string;
+    /** Free-form searchable terms; the Web App renders them as chips (e.g. the target OS). */
+    keywords?: string[];
+    /** Capability floor(s) the plugin provides on (e.g. "sandbox"). */
+    categories?: string[];
+    /** Unix timestamp (seconds) of the entry's last update. */
+    updatedAt?: number;
+}
+/** GET /api/plugins/registry: the merged index of every configured registry (currently the builtin one). */
+interface PluginIndexResponse {
+    plugins: PluginIndexEntry[];
+    /**
+     * Sources that could not be read, by `source` and reason. Present and empty when every
+     * source answered. A remote index that is down shortens the listing rather than emptying
+     * it, so the page needs to be able to say so instead of silently showing less.
+     */
+    failures: {
+        source: string;
+        error: string;
+    }[];
+    /**
+     * Sources the server was still reading when it answered, by `source`. Present and empty when
+     * every source answered. The listing does not wait long for a published index, so one on a slow
+     * or unreachable network is named here and its entries are missing; a later read lists them
+     * once they have arrived, or names the source under `failures` once it has failed.
+     */
+    pending: string[];
+}
+/**
+ * A plugin's long-form docs: the README.md at its package root, as npm ships it.
+ * GET /api/plugins/registry/readme?name= answers for an index entry, with `readme` null when
+ * the package is not on this server or has none; GET /api/plugins/:plugin/readme answers for a
+ * library plugin, 404 when it ships none.
+ */
+interface PluginReadmeResponse {
+    name: string;
+    /** Markdown, rendered by the Web App. Null when this entry has no readme. */
+    readme: string | null;
+}
+/**
+ * One language a plugin contributes, as the listing reports it. The grammar itself is not
+ * here: it is tens to hundreds of kilobytes, and only the languages a conversation actually
+ * shows are worth fetching (`GET /api/languages/:id/grammar`).
+ */
+interface LanguageSummary {
+    /** Canonical id: the fence info string, and the id both endpoints address. */
+    id: string;
+    displayName: string;
+    /** Alternative fence info strings, needed BEFORE the grammar loads (it is what decides to load it). */
+    aliases?: string[];
+    /** File extensions without the dot, for the Workspace file viewer. */
+    extensions?: string[];
+}
+/** GET /api/languages: every language this App's plugins contributed, by id. */
+interface LanguageIndexResponse {
+    languages: LanguageSummary[];
+}
 /**
  * GET /api/version: the running build's identity plus this root's pushed harness, verbatim
  * from `versionReport()` — the same record `penguin version --json` prints, so the two
@@ -3289,6 +4544,17 @@ interface SkillArchiveInstallRequest {
  * predating the stamping — v0.1.2 and earlier — where the UI shows the version alone).
  */
 type VersionResponse = VersionReport;
+
+/** GET /api/version/history: the harness versions this data root has committed, newest first. */
+type VersionHistoryResponse = HarnessHistory;
+/** POST /api/version/history/rollback `{ id }`: the push back has started; the swap follows. */
+interface VersionRollbackResponse {
+    started: true;
+    id: string;
+}
+/** GET /api/version/history/diff?from=&to=: what changed between two stored interface tables. */
+type VersionHistoryDiffResponse = IfacesDiff;
+
 /**
  * GET /api/version/update-check: newest published release vs the running version.
  * Always HTTP 200 (fail-soft): a lookup failure sets `error` and leaves `latestVersion`
@@ -3407,6 +4673,44 @@ interface DesktopTrayCommandMessage {
     showTrayIcon?: boolean;
     locale?: DesktopTrayLocale;
 }
+/** What the shell's read of one folder came to. */
+interface DesktopFolderAccessResult {
+    /** The folder could be read. Always true off macOS, where the shell reads nothing. */
+    granted: boolean;
+    /** The failed read's errno code (`EPERM`, `EACCES`, `ENOENT`, …); `EINVAL` for a path that is not absolute. */
+    code?: string;
+    /**
+     * Whether the app is a packaged build (Electron's `app.isPackaged`). An unpackaged one is a
+     * development instance started from a terminal, and macOS holds that terminal responsible
+     * for its reads rather than the app.
+     */
+    packaged: boolean;
+}
+/** Server → shell request over the utilityProcess message channel (relayed from POST /api/projects/:projectId/dirs/access). */
+interface DesktopFolderAccessMessage {
+    type: "desktop-folder-access";
+    /** Pairs the reply with its request. */
+    id: string;
+    /** The folder to read, as an absolute path. */
+    path: string;
+}
+/** Shell → server reply to one {@link DesktopFolderAccessMessage}, carrying its `id`. */
+interface DesktopFolderAccessResultMessage extends DesktopFolderAccessResult {
+    type: "desktop-folder-access-result";
+    id: string;
+}
+/** POST /api/projects/:projectId/dirs/access: the shell's answer, for the picker to act on. */
+interface DirAccessResponse {
+    granted: boolean;
+    packaged: boolean;
+}
+/** The Privacy & Security panes the page may open: Files and Folders, and Full Disk Access. */
+type DesktopPrivacyPane = "files" | "fullDisk";
+/** Server → shell command over the utilityProcess message channel (relayed from POST /api/desktop/privacy-settings). No reply. */
+interface DesktopOpenPrivacySettingsMessage {
+    type: "desktop-open-privacy-settings";
+    pane: DesktopPrivacyPane;
+}
 /**
  * The outcome of one self-update run (`penguin update --yes` on the server host), carried
  * by {@link UpdateJobStatus.result}. `unsupported` covers both a server not launched via
@@ -3497,6 +4801,16 @@ interface MachineInfo {
         version: string;
         at: string;
     };
+    /** This server signs in to the machine with a password it stores for the alias, not a key. */
+    passwordSaved?: true;
+    /**
+     * In this Project's list: the Machines page shows a card for it. A machine joins the list when
+     * it is added (`POST …/machines/add`, which installs nothing) or when an install or a use for
+     * this Project runs on it, and leaves it with stop-using or release. Absent for a host that is
+     * only in the ssh config, or only in another Project's list; never set on `local`, which is
+     * always shown.
+     */
+    member?: true;
     /**
      * The machine's OWN id — 16 base64url characters minted by the server that runs there,
      * stable across renames, re-aliasing and reinstalls. Null until a server has started on
@@ -3521,6 +4835,19 @@ interface MachineInfo {
     connection: {
         pid: number;
     } | null;
+    /**
+     * Present while this server is bringing a machine it keeps connected back — the connection
+     * dropped, its server stopped or restarted, or this server itself just started — and absent
+     * otherwise. A machine is kept connected from the moment it is enabled until it is stopped
+     * (`POST …/stop`) or deleted (`POST …/stop-using`); see machines/service.ts's supervision.
+     */
+    reconnect?: MachineReconnect;
+    /**
+     * This server keeps a connection to it: it was enabled, or started, and has not been stopped
+     * or deleted since. Absent otherwise — a machine only added, one whose server was stopped
+     * here, one that never got as far as a connection.
+     */
+    keepConnected?: true;
     /**
      * The machine's API as last seen by this server's proxy — stamped by traffic passing
      * through, never by a probe of its own. `answeredAt` when the last forwarded request got
@@ -3536,6 +4863,12 @@ interface MachineInfo {
         failedAt: string;
         detail: string;
     } | null;
+    /**
+     * What the last time this server handed it the Project config came to: at a connect, a Sync
+     * config job, or an automatic sync after a config edit here. Absent until the first one since
+     * this server started; kept in memory only.
+     */
+    configSync?: MachineConfigSync;
     /**
      * What the last probe found over there, or null when none has been taken. Never filled in
      * at list time: a probe costs an ssh round trip per machine, so the list reports the last
@@ -3543,6 +4876,80 @@ interface MachineInfo {
      * since each probe is an ssh round trip while the list is only the config's text.
      */
     status: MachineServerStatus | null;
+    /**
+     * The data root the server there runs on (`PENGUIN_HOME`). This instance's PROFILE decides
+     * it — a dev instance names the machine's dev root and never the release one beside it
+     * (machines/layout.ts) — which is exactly what a reader looking at two instances of this
+     * page needs to tell them apart. Written in that machine's own spelling once its platform
+     * is known, and in the POSIX one before that; for `local` it is this process's own root,
+     * already resolved to an absolute path.
+     */
+    root: string;
+}
+/**
+ * One config sync to a machine: when it ended, whether every part of it reached the machine for
+ * every Project using it, and what did not, in the far side's words.
+ */
+interface MachineConfigSync {
+    /** ISO timestamp the sync ended. */
+    at: string;
+    ok: boolean;
+    /** The parts that did not go through, one per line; absent when `ok`. */
+    detail?: string;
+    /**
+     * The values the Project's models take from this server's environment variables rather than
+     * its config (an API key, or a base URL), which no sync can carry: one row per variable. On
+     * the list answered for a Project, that Project's rows only.
+     */
+    envOnly: MachineEnvOnly[];
+    /**
+     * The model entries the machine refused by name — a hand-added model in a group that takes
+     * only its built-in ones there — left out while the rest of the table went. On the list
+     * answered for a Project, that Project's rows only.
+     */
+    skipped: MachineSkippedModel[];
+}
+/** A model entry a machine would not take: its error code and its own words for why. */
+interface MachineSkippedModel {
+    projectId: string;
+    provider: string;
+    modelId: string;
+    /** The far side's error code (`model_not_addable`, `model_not_routable`). */
+    code: string;
+    reason: string;
+}
+/** A model entry that takes `variable` from this server's environment. */
+interface MachineEnvOnly {
+    projectId: string;
+    provider: string;
+    modelId: string;
+    variable: string;
+}
+/**
+ * A machine this server keeps connected, while it is being brought back. Attempts back off
+ * from 5 s, doubling to a 5-minute cap, so a machine that is down for a day costs a probe every
+ * five minutes; after three failures in a row the connection check runs on its own, and its
+ * answer is what the page shows as the explanation.
+ */
+interface MachineReconnect {
+    /** When this streak began: the moment the machine was found not connected. */
+    since: string;
+    /** Attempts that failed in this streak; 0 while the first is still to run or running. */
+    attempts: number;
+    /** When the next attempt runs; null while one is running. */
+    nextAt: string | null;
+    /** The last attempt's failure in the far side's words; null before the first one fails. */
+    lastError: string | null;
+    /** Why ssh refused, when the last failure was ssh's own — for the page to say in its language. */
+    sshReason?: MachineSshFailure;
+    /** The connection check run after three failures in a row; null until then. */
+    diagnosis: MachineDiagnosis | null;
+    /**
+     * The password stored for the machine was refused, or its host takes none (`sshReason`
+     * says which): no attempt runs until a password is saved for it again or removed, since
+     * retrying could lock the account. `nextAt` is null meanwhile.
+     */
+    waitsForPassword?: true;
 }
 /**
  * One machine's server state. There is deliberately no separate "ssh" status: ssh is the
@@ -3565,11 +4972,38 @@ interface MachineServerStatus {
  * refused key or an unusable Node than a paraphrase would.
  */
 interface MachineJob {
-    kind: "install" | "connect" | "restart";
+    /**
+     * `use` is the whole pipeline — install if needed, hand over, connect, sync — as one job;
+     * `connect` is what the page calls Start service; `stop` stops the machine's server and stops
+     * keeping it connected; `uninstall` stops it and removes the program, and the data directory
+     * when asked; `sync` hands a connected machine the Project config.
+     */
+    kind: "install" | "connect" | "restart" | "use" | "stop" | "uninstall" | "sync";
     machineId: string;
     alias: string;
+    /** Waiting its turn: a few machines are worked on at once, and a batch queues the rest. */
+    queued: boolean;
     running: boolean;
+    /**
+     * The steps this job goes through, in order — what the page draws as its stepper. Fixed when
+     * the job is queued; a step the job turns out not to need is passed over, never revisited.
+     */
+    steps: MachinePhase[];
+    /**
+     * Which of `steps` the job is on. Only moves forward. Null until the first step is named; a
+     * finished job keeps its last phase.
+     */
+    phase: MachinePhase | null;
     log: string[];
+    /**
+     * The connection check run after the job failed at a step it can explain — checking,
+     * installing, connecting: running, then its answer. Absent for every other job.
+     */
+    diagnosis?: {
+        state: "running";
+    } | ({
+        state: "done";
+    } & MachineDiagnosis);
     result: null | {
         ok: true;
         installed: "installed" | "already-installed";
@@ -3577,66 +5011,305 @@ interface MachineJob {
     } | {
         ok: true;
         connected: true;
+    }
+    /** The machine's server is stopped and stays so until it is started again. */
+     | {
+        ok: true;
+        stopped: true;
+    }
+    /** The program is gone from the machine; `dataRemoved` says whether its data root went too. */
+     | {
+        ok: true;
+        uninstalled: true;
+        dataRemoved: boolean;
+    }
+    /** Every part of the Project config reached the machine (its `configSync` says the same). */
+     | {
+        ok: true;
+        synced: true;
     } | {
         ok: false;
         step: string;
         message: string;
         /**
          * The failure has a next step this side can take, and it needs saying yes to:
-         * installing the PROGRAM over there and restarting it. Set when a hot update could
-         * not be handed over — the machine's store holds no CLI this server can talk to, and
-         * installing is what replicates one. Offered rather than done, because it restarts a
-         * server this Project does not own alone.
+         * installing the PROGRAM over there and restarting it. Every failed install or
+         * connect offers it — a failure that leaves no next step leaves a person stuck —
+         * except a run that was itself that install, and one this server could not act on
+         * (no build of its own to send), which says `false`. Offered rather than done,
+         * because it restarts a server this Project does not own alone.
          */
-        canReplaceProgram?: true;
+        canReplaceProgram?: boolean;
+        /**
+         * Why ssh refused, when the failure is ssh's own (a host key, a key, a host name, a
+         * route), for the page to say in its language; `message` says it in English, with
+         * ssh's own words after `(ssh: …)`.
+         */
+        sshReason?: MachineSshFailure;
     };
 }
+/**
+ * A source checkout's install image (machines/checkout-image.ts), built from the checkout
+ * again at each install or use: not built yet, building, built, or failed with the build's
+ * own last words.
+ */
+type MachinesCheckoutImage = {
+    state: "unbuilt";
+} | {
+    state: "building";
+} | {
+    state: "built";
+} | {
+    state: "failed";
+    detail: string;
+};
 /** GET /api/machines, and the 202 body of POST /api/machines/:machineId/install. */
 interface MachinesResponse {
     machines: MachineInfo[];
     /**
      * The version an install would leave on the remote — the base release, plus a `+hmr.<sha>`
-     * suffix when this server carries a pushed version to replicate. Null for a development
-     * checkout, which stands on no release the remote could download.
+     * suffix when this server carries a pushed version to replicate. A source checkout answers
+     * with the image it last built, and null before its first build (see `checkoutImage`).
+     * Null otherwise only for a server that carries no image and builds none.
      */
     imageVersion: string | null;
+    /**
+     * Present only when this server runs from a source checkout: it builds its install image
+     * from the checkout at each install or use, so no image yet is not a reason to refuse one.
+     */
+    checkoutImage?: MachinesCheckoutImage;
+    /** The most recently started job, running or finished. */
     job: MachineJob | null;
+    /**
+     * Every job worth showing this generation: the queued ones, the running one, and the last
+     * finished one per machine — so a batch reads as a list of rows each saying where it is.
+     */
+    jobs: MachineJob[];
 }
 /**
- * Organization status: `paused` stops every automatic trigger; humans can still talk to any
- * desk. These two values are the whole lifecycle — no route deletes an organization, so a
- * paused one keeps its conversations, employees, desks and tickets.
+ * Every step a job may name, in the order they can occur. A job lists its own subset as
+ * `MachineJob.steps`: a source checkout's enable starts by building its install image
+ * (`build`); a stop is `check`, `stop`; an uninstall `check`, `stop`, `remove`; a config sync
+ * `check`, `sync`.
  */
-type OrgStatus = "active" | "paused";
-/** Approval mode for desk and ticket sessions; unattended runs never get always-ask. */
-type OrgApprovalMode = "allow-all" | "read-only" | "deny-all";
-/** The five kanban columns, each a directory under `tickets/<yyyy-mm>/`. */
-type OrgTicketStatus = "proposed" | "in_progress" | "review" | "done" | "rejected";
-type OrgTicketPriority = "P0" | "P1" | "P2";
-/** Live employee state: running when the desk or any ticket session has a Task in progress; paused when budget-paused. */
-type OrgEmployeeState = "running" | "idle" | "paused";
+declare const MACHINE_PHASES: readonly ["build", "check", "install", "handover", "restart", "connect", "sync", "stop", "remove"];
+type MachinePhase = (typeof MACHINE_PHASES)[number];
+/** `POST /api/projects/:projectId/machines/:machineId/uninstall`. */
+interface MachineUninstallRequest {
+    /** Remove the machine's data root too — its Sessions, Agents and config there. Default false. */
+    removeData?: boolean;
+}
 /**
- * The trigger kinds an `[org_trigger]` block carries. `ticket_notice` is read-only: a ticket
- * change starts no run of its own, so nothing writes that kind any more, and it stays in the
- * union because Traces recorded while it did still carry it.
+ * `POST /api/projects/:projectId/machines/ssh-hosts`: append a host block to this server's
+ * `~/.ssh/config`. Answers the machines list (201), or 400 `ssh_host_invalid` naming the
+ * field, or 409 `ssh_host_exists`.
  */
-type OrgTriggerKind = "init" | "event" | "mention" | "ticket_notice" | "ticket_work";
-/** The ticket changes an employee is told about, listed in the body of its next calendar sweep. */
-type OrgTicketChange = "assigned" | "blocked" | "blocker_closed" | "done" | "rejected";
-/** What the last evaluation of a calendar event did. */
-type OrgCalendarOutcome = "fired" | "queued" | "paused" | "missed" | "error";
+interface SshHostRequest {
+    /** The alias — what `ssh <alias>` will take, and the machine's name everywhere here. */
+    alias: string;
+    hostName: string;
+    user?: string;
+    port?: number;
+    identityFile?: string;
+    /**
+     * Sign in with this password instead of a key: stored on this server in a 0600 file under its
+     * data root, never in the ssh config, and never sent back. On a PUT, `null` deletes the stored
+     * one (back to key sign-in) and leaving it out keeps it. A PUT on a block written by hand may
+     * set it when the other fields are the block as it stands. 400 `ssh_password_invalid` for an
+     * empty or multi-line one; 409 `ssh_password_unsupported` (`details.ssh`: what `ssh -V` said)
+     * when this computer's ssh cannot be handed a password.
+     */
+    password?: string | null;
+}
 /**
- * The organization's working language: the language its handbook, its CEO's initialization
- * run, every employee brief and every desk and ticket run are written in. Detected from the
- * mission at creation (CJK text → `zh`, anything else → `en`) unless the request names one.
+ * `GET /api/projects/:projectId/machines/ssh-hosts/:alias`: a host's block read back, and
+ * whether this app wrote it. Only a block this app wrote may be rewritten
+ * (`PUT …/ssh-hosts/:alias`, the same fields less the alias): a hand-written one may carry
+ * options this app does not know, and rewriting it would drop them.
  */
-type OrgLanguage = "zh" | "en";
-/** The organization's settings as `org_config.toml` records them. */
-interface OrganizationSettings {
-    name: string;
-    mission: string;
-    status: OrgStatus;
-    /** IANA timezone: budget periods (natural months) and chat day files follow it. */
+interface SshHostResponse extends Omit<SshHostRequest, "password"> {
+    editable: boolean;
+    /** A password is stored for this host, which then signs in with it rather than with a key. */
+    passwordSaved?: true;
+}
+/**
+ * `GET /api/projects/:projectId/machines/ssh-hosts`: every host this server's ssh config declares,
+ * its included files' too, with what each one's own block says about reaching it — the literal
+ * lines, not what ssh resolves (no `ssh -G`): a `Host *` default or a `Match` block is not
+ * applied. For the add dialog's rows; an option the block leaves out is absent.
+ */
+interface SshHostSummary {
+    alias: string;
+    hostName?: string;
+    user?: string;
+    port?: number;
+}
+interface SshHostsResponse {
+    hosts: SshHostSummary[];
+}
+/**
+ * `POST /api/projects/:projectId/machines/add`: put these machines in this Project's list without
+ * installing anything there — each then has a card whose one thing to do is enabling it. Answers
+ * like `…/use`, refusals by id (`unknown-machine`, `self`).
+ */
+interface MachinesAddRequest {
+    machines: string[];
+}
+/** `POST /api/projects/:projectId/machines/use`: bring these machines into use, as one queued batch. */
+interface MachinesUseRequest {
+    /** Machine ids (`ssh:<alias>`). Every one is queued; refusals come back by id. */
+    machines: string[];
+    /** Install the program even where its version matches, and restart there — the answer to a job that asked for it. */
+    replaceProgram?: boolean;
+}
+/** Why one machine of a batch was not queued; the rest were. */
+type MachineUseRefusal = "unknown-machine" | "self" | "no-image";
+/**
+ * Why ssh could not get a session to a machine, read from its own diagnostic
+ * (machines/ssh-failure.ts); `other` when it printed none of the ones with a fixed meaning.
+ */
+type MachineSshFailure = "host-key-unknown" | "host-key-changed" | "key-file" | "auth" | "password-rejected" | "password-not-offered" | "host-not-found" | "refused" | "timeout" | "closed" | "ssh-config" | "other";
+/** Whether a machine reaches one release source: the package is there, the source answered without it, or no answer. */
+type MachineSourceReach = "ok" | "missing" | "unreachable";
+/**
+ * One check of a machine (machines/diagnose.ts), as facts for the page to word. `pass` is
+ * fine, `warn` works with a caveat, `fail` stops an install or a connect, `skip` could not be
+ * asked (an earlier check failed, or it does not apply).
+ */
+type MachineCheck = 
+/** A session came up (keys, or the stored password), as this account on that host. */
+{
+    id: "ssh";
+    state: "pass";
+    user: string;
+    host: string;
+}
+/** It did not; `said` is ssh's own words, led by what they mean. */
+ | {
+    id: "ssh";
+    state: "fail";
+    reason: MachineSshFailure;
+    said: string;
+}
+/**
+ * `warn` for Windows (installable, not connectable yet), and for a Linux whose glibc runs the
+ * release but is older than `terminalsNeed`, the one its terminal binding loads on.
+ */
+ | {
+    id: "platform";
+    state: "pass" | "warn";
+    os: string;
+    arch: string;
+    glibc?: string;
+    terminalsNeed?: string;
+}
+/**
+ * What the release's Node cannot run on: an OS or architecture no release is published for
+ * (`unsupported`, `said` what the machine answered), a glibc older than `need` (`glibc`), or
+ * a musl libc such as Alpine's (`musl`).
+ */
+ | {
+    id: "platform";
+    state: "fail";
+    reason: "unsupported" | "glibc" | "musl";
+    os?: string;
+    arch?: string;
+    glibc?: string;
+    need?: string;
+    said?: string;
+}
+/**
+ * What the release installer needs and the machine lacks. `warn` when curl alone is missing:
+ * the release is then sent over ssh rather than downloaded there.
+ */
+ | {
+    id: "tools";
+    state: "pass" | "warn" | "fail";
+    missing: string[];
+}
+/**
+ * Whether the machine itself reaches release `version` for its platform. `warn`: out of
+ * reach, so an install cannot download it there; `fail`: both sources answered and neither
+ * has it (not published).
+ */
+ | {
+    id: "download";
+    state: "pass" | "warn" | "fail";
+    version: string;
+    github: MachineSourceReach;
+    oss: MachineSourceReach;
+}
+/** Free space in the machine's home against what an install needs, in MB. */
+ | {
+    id: "disk";
+    state: "pass" | "warn" | "fail";
+    freeMb: number;
+    needMb: number;
+}
+/** The port its server would start on: free, already its PenguinHarness server's, or taken by something else. */
+ | {
+    id: "port";
+    state: "pass" | "fail";
+    port: number;
+    holder: "free" | "penguin" | "other";
+} | {
+    id: "platform" | "tools" | "download" | "disk" | "port";
+    state: "skip";
+};
+/**
+ * `POST /api/projects/:projectId/machines/:machineId/diagnose`: the checks, in order. Nothing
+ * is written on the machine; 409 `job_running` while a job works on it.
+ */
+interface MachineDiagnosis {
+    machineId: string;
+    checkedAt: string;
+    checks: MachineCheck[];
+}
+interface MachinesUseResponse extends MachinesResponse {
+    refused: {
+        machineId: string;
+        why: MachineUseRefusal;
+    }[];
+}
+/** `POST /api/projects/:projectId/machines/stop-using`: let go of these machines — connection dropped, Project membership released; the install stays. */
+interface MachinesStopUsingRequest {
+    machines: string[];
+}
+/**
+ * Organization status: `paused` stops every automatic trigger; humans can still talk to any
+ * desk. These two values are the whole lifecycle — no route deletes an organization, so a
+ * paused one keeps its conversations, employees, desks and tickets.
+ */
+type OrgStatus = "active" | "paused";
+/** Approval mode for desk and ticket sessions; unattended runs never get always-ask. */
+type OrgApprovalMode = "allow-all" | "read-only" | "deny-all";
+/** The five kanban columns, each a directory under `tickets/<yyyy-mm>/`. */
+type OrgTicketStatus = "proposed" | "in_progress" | "review" | "done" | "rejected";
+type OrgTicketPriority = "P0" | "P1" | "P2";
+/** Live employee state: running when the desk or any ticket session has a Task in progress; paused when budget-paused. */
+type OrgEmployeeState = "running" | "idle" | "paused";
+/**
+ * The trigger kinds an `[org_trigger]` block carries. `ticket_notice` is read-only: a ticket
+ * change starts no run of its own, so nothing writes that kind any more, and it stays in the
+ * union because Traces recorded while it did still carry it.
+ */
+type OrgTriggerKind = "init" | "event" | "mention" | "ticket_notice" | "ticket_work";
+/** The ticket changes an employee is told about, listed in the body of its next calendar sweep. */
+type OrgTicketChange = "assigned" | "blocked" | "blocker_closed" | "done" | "rejected";
+/** What the last evaluation of a calendar event did. */
+type OrgCalendarOutcome = "fired" | "queued" | "paused" | "missed" | "error";
+/**
+ * The organization's working language: the language its handbook, its CEO's initialization
+ * run, every employee brief and every desk and ticket run are written in. Detected from the
+ * mission at creation (CJK text → `zh`, anything else → `en`) unless the request names one.
+ */
+type OrgLanguage = "zh" | "en";
+/** The organization's settings as `org_config.toml` records them. */
+interface OrganizationSettings {
+    name: string;
+    mission: string;
+    status: OrgStatus;
+    /** IANA timezone: budget periods (natural months) and chat day files follow it. */
     timezone: string;
     approvalMode: OrgApprovalMode;
     /** Chat @-chain limit: a message whose hop reaches it records its mentions without triggering anyone. */
@@ -3685,8 +5358,20 @@ interface OrganizationsResponse {
 }
 interface OrgEmployeeItem {
     agentId: string;
-    /** Agent display name (system_config.yaml); falls back to the id. */
+    /**
+     * What this employee goes by in the organization, unique across it: the chart's `name`, else
+     * the Agent's display name, else the id — with the id noted (`name (id)`) when the name is
+     * not this employee's alone. It is what every surface shows and what works after `@`.
+     */
     name: string;
+    /** The `name` as written in the chart, for editing; absent when the entry has none. */
+    givenName?: string;
+    /**
+     * Present when the employee has an avatar: the content revision of the image served at
+     * `GET …/employees/:agentId/avatar` (append it as `?rev=` — the image is cached for good).
+     * Absent, surfaces draw the letter tile.
+     */
+    avatarRev?: string;
     title: string;
     /** null for the CEO (the root). */
     reportsTo: string | null;
@@ -3702,6 +5387,11 @@ interface OrgEmployeeItem {
         modelId: string;
     };
     state: OrgEmployeeState;
+    /**
+     * The employee's current desk. Absent while the ledger names none, and while the Session
+     * it names no longer exists (deleted by hand, or with its Agent): a desk is listed only
+     * once it can be opened, and the reconcile pass re-opens a missing one when it can.
+     */
     desk?: {
         sessionId: string;
         workspace: string;
@@ -3715,6 +5405,12 @@ interface OrgEmployeeItem {
     };
     /** Why the entry cannot be triggered (missing Agent, missing workspace directory). */
     invalid?: string;
+    /**
+     * The entry's Agent no longer exists (`invalid` carries the sentence). Its desk cannot be
+     * opened; the entry stays until a person makes the employee leave, or until an Agent with
+     * the same id is created again (which is how a deleted CEO is restored).
+     */
+    agentMissing?: true;
 }
 interface OrgChartResponse {
     ceoAgentId: string;
@@ -3977,8 +5673,15 @@ interface OrgDeskItem {
     status: SessionStatus;
     workspace: string;
     lastActiveAt?: string;
+    /**
+     * Present when the desk session has an ENABLED messaging binding: its channel, read as
+     * `SessionInfo.messagingChannel` is (the company sidebar's desk row draws the same mark as a
+     * development row, and the development list never holds a desk).
+     */
+    messagingChannel?: MessagingChannel;
 }
 interface OrgSessionsResponse {
+    /** One per employee whose current desk Session exists; a desk the ledger names but the server no longer has is left out. */
     desks: OrgDeskItem[];
     tickets: Array<{
         ticketId: string;
@@ -4069,19 +5772,30 @@ interface OrganizationPatchRequest {
     language?: OrgLanguage;
 }
 /**
- * A semantic id proposed for a display name — the organization and channel dialogs let the
- * user name the thing first and derive the id from that name. The server asks the Project's
- * default model for a short English snake_case id (a Chinese name has no mechanical
+ * What a proposed semantic id names. Each kind has its own shape — organization and channel
+ * ids carry a `co_` / `ch_` prefix, a non-admin's Project id its owner's `<username>-`, a
+ * Benchmark id is kebab-case — and its own set of ids to avoid.
+ */
+type SemanticIdKind = "org" | "channel" | "project" | "agent" | "benchmark";
+/**
+ * A semantic id proposed for a display name — every create dialog that names an object with a
+ * semantic id (a Project, an Agent, a Benchmark, an organization, a channel) lets the user name
+ * the thing first and derive the id from that name. The server asks the Project's default
+ * model for a short English id in the kind's spelling (a Chinese name has no mechanical
  * transliteration), falling back to an ASCII slug of the name when the model is unavailable,
  * and to a dated placeholder when neither can name it. The request never fails for a name it
  * cannot translate: a dialog that asked for an id always gets one back.
  */
 interface SemanticIdSuggestRequest {
-    /** The display name typed so far (or the mission, when nothing else names the thing). */
+    /** The display name typed so far (or the mission / description, when nothing else names the thing). */
     name: string;
-    /** What the id is for: decides the prompt's examples and the fallback's prefix. */
-    kind: "org" | "channel";
-    /** Ids already in use in the target scope; the proposal avoids them. */
+    /** What the id is for: decides the id's shape, the prompt's examples and the ids avoided. */
+    kind: SemanticIdKind;
+    /**
+     * Ids already in use in the target scope; the proposal avoids them. For a Project, an Agent or
+     * a Benchmark, the server also avoids, on its own, every id that kind's create route refuses
+     * as taken, a leftover folder no list shows included.
+     */
     taken?: string[];
 }
 /**
@@ -4093,7 +5807,10 @@ interface SemanticIdSuggestRequest {
  */
 type SemanticIdSuggestReason = "no_default_model" | "model_failed" | "unusable_answer" | "no_ascii";
 interface SemanticIdSuggestResponse {
-    /** A valid semantic id (`^[a-z][a-z0-9_]{1,63}$`), not in `taken`. */
+    /**
+     * An id the kind's create route accepts, not in `taken`: `^[a-z][a-z0-9_]{1,63}$` for most
+     * kinds, `<username>-<suffix>` for a non-admin's Project, kebab-case for a Benchmark.
+     */
     id: string;
     /** Who produced it: the model, the ASCII fallback, or the dated placeholder that names nothing. */
     source: "model" | "fallback" | "placeholder";
@@ -4110,6 +5827,11 @@ interface OrgHireRequest {
         description?: string;
         plugins?: string[];
     };
+    /**
+     * What the organization calls the employee (any script, one line, no `@`, ≤ 64 characters).
+     * Omitted, a new Agent's `name` is used; with neither, the Agent's display name stands in.
+     */
+    name?: string;
     title: string;
     reportsTo: string;
     workspace?: string;
@@ -4121,6 +5843,8 @@ interface OrgHireRequest {
     };
 }
 interface OrgEmployeePatchRequest {
+    /** null (or an empty string) clears the name: back to the Agent's display name. */
+    name?: string | null;
     title?: string;
     reportsTo?: string;
     workspace?: string;
@@ -4321,5 +6045,890 @@ interface ContributionsResponse {
     agentTabs: WebContribution[];
     sessionTabs: WebContribution[];
 }
+/**
+ * One field of a settings group a module declares (its `PluginConfigProvider.groups`
+ * contribution's `properties.<name>`): what the Settings dialog draws for it. `secret` is
+ * drawn as a password field and masked on the way out; `enum` is a choice among `options`;
+ * `list` is a list of strings, drawn one per line; `table` is a fixed set of `rows`, each a
+ * value per one of its `columns`, drawn as a table.
+ */
+interface PluginConfigField {
+    type: "string" | "secret" | "boolean" | "number" | "enum" | "list" | "table";
+    title: string;
+    titleZh?: string;
+    /** What the field means: disclosed behind a "?" beside its title. */
+    description?: string;
+    descriptionZh?: string;
+    /**
+     * The shape a value must take ("one absolute path per line"): shown under the field at all
+     * times, since it is read while typing.
+     */
+    hint?: string;
+    hintZh?: string;
+    placeholder?: string;
+    /** The value a package with nothing stored reads; also what an empty field falls back to. */
+    default?: string | number | boolean | string[];
+    /**
+     * Drawn in the card's Advanced fold, collapsed by default, rather than among the basic
+     * fields. Presentation only: it is stored, validated and read like any other field.
+     */
+    advanced?: boolean;
+    /** A save that would leave this field empty is refused. */
+    required?: boolean;
+    /** `enum` only: the values it may take, in display order. */
+    options?: PluginConfigOption[];
+    /** `list` only: the most entries a save may leave (after trimming and de-duplicating). */
+    maxItems?: number;
+    /** `number` only: the smallest and largest value a save may store. */
+    minimum?: number;
+    maximum?: number;
+    /** `string` / `list` only: a regular expression every value (every line) must match. */
+    pattern?: string;
+    /** What a save refused by `pattern` says, after the field's name (e.g. "must be an absolute path"). */
+    patternErrorMessage?: string;
+    /**
+     * `table` only: its columns, in display order, and its rows, in display order. The table
+     * has no `default`: the rows' declared cells are its defaults, and what is stored is only
+     * the cells that differ from them — `{ [row id]: { [column]: value } }`.
+     */
+    columns?: PluginConfigTableColumn[];
+    rows?: PluginConfigTableRow[];
+    /**
+     * `table` only: a single choice of one row — the sandbox's default preset. The choice is
+     * stored in `field`, an `enum` field of the same group whose options are the row ids (plus,
+     * in an `extensible` table, the ids of the rows added to it); the page draws that field only
+     * as its title in brackets after the chosen row's name ("(Default)"), and picks it from a
+     * row's "…" menu.
+     */
+    rowChoice?: PluginConfigRowChoice;
+    /**
+     * `table` only: rows may be added (and only those deleted, from the row's "…" menu) and every
+     * row reordered. A new row
+     * starts from these values. What is stored, beside the declared rows' changed cells, is the
+     * added rows under `"$added"` (`{ [row id]: { [column]: value } }`, every column present) and
+     * the row order under `"$order"` (row ids); neither key can be a row id. A save sends either
+     * key whole; a document without them reads as the declared rows in declared order.
+     */
+    extensible?: PluginConfigNewRow;
+    /**
+     * `table` only: a header drawn over adjacent columns that belong together (the sandbox's
+     * Pin, under "Action"). `columns` names them. When the group ends the columns, the row's drag
+     * handle and "…" menu join it.
+     */
+    columnGroup?: PluginConfigColumnGroup;
+    /**
+     * `table` only: a `boolean` column drawn as a pin toggle rather than a switch — a row pinned
+     * to a list (the sandbox presets in the composer's menu). The texts are its tooltip in each
+     * state. Declared on the table, not the column, so every column keeps one shape.
+     */
+    pin?: PluginConfigPinColumn;
+}
+/** A table's pin column: which boolean column, and its tooltip pinned and not. */
+interface PluginConfigPinColumn {
+    column: string;
+    on: string;
+    onZh?: string;
+    off: string;
+    offZh?: string;
+}
+/**
+ * A table's single choice of a row: the `enum` field it stores into, and its title, drawn in
+ * brackets after the chosen row's name. The choice may name no row (nothing stored, and the
+ * group's `derive` gives none): no row is marked and a save is not refused for it. A save that
+ * leaves it naming a row the table no longer has is refused.
+ */
+interface PluginConfigRowChoice {
+    field: string;
+    title: string;
+    titleZh?: string;
+}
+/** One column of a `table` field: a scalar field type (`string`, `boolean`, or an `enum` with `options`). */
+interface PluginConfigTableColumn {
+    name: string;
+    type: "string" | "boolean" | "enum";
+    title: string;
+    titleZh?: string;
+    /** What the column means: disclosed behind a "?" beside its header. */
+    description?: string;
+    descriptionZh?: string;
+    options?: PluginConfigOption[];
+}
+/** One row of a `table` field: its id and its declared cells. */
+interface PluginConfigTableRow {
+    id: string;
+    /** Every column's declared value. */
+    values: Record<string, string | boolean>;
+    /** A string cell's declared value in Chinese, shown until a save changes the cell. */
+    valuesZh?: Record<string, string>;
+    /** Columns whose cell in this row a save may not change. */
+    locked?: string[];
+    /** A row added to an `extensible` table (not declared): the only kind that may be deleted. */
+    added?: boolean;
+    /**
+     * What the row is for, disclosed behind a "?" beside its name while its `enum` cells hold
+     * their declared values. A row without one, or whose choices changed, gets a "?" listing its
+     * `enum` cells' values and what each does (the options' `description`s).
+     */
+    description?: string;
+    descriptionZh?: string;
+}
+/** A header over adjacent table columns, with its own "?". */
+interface PluginConfigColumnGroup {
+    title: string;
+    titleZh?: string;
+    description?: string;
+    descriptionZh?: string;
+    columns: string[];
+}
+/** The values a row added to an `extensible` table starts from. */
+interface PluginConfigNewRow {
+    /** The add button's text ("Add preset"). */
+    add?: string;
+    addZh?: string;
+    values: Record<string, string | boolean>;
+    /** A string column's starting text in Chinese. */
+    valuesZh?: Record<string, string>;
+}
+/** One choice of an `enum` field. */
+interface PluginConfigOption {
+    value: string;
+    title: string;
+    titleZh?: string;
+    /** What picking it does: listed, for a table column's option, in a row's "?" (see the row's `description`). */
+    description?: string;
+    descriptionZh?: string;
+}
+/** A declared configuration: a titled group of fields, in declaration order. */
+interface PluginConfiguration {
+    title?: string;
+    titleZh?: string;
+    description?: string;
+    descriptionZh?: string;
+    /**
+     * A `boolean` field that turns the group on (the sandbox's `enabled`). While it is off, as
+     * drafted, the card draws that field alone: no other field, notice or action, and none of the
+     * groups drawn inside it. Turning it on in a group that reports a `backend` it lacks offers
+     * to install one.
+     */
+    switch?: string;
+    properties: Record<string, PluginConfigField>;
+}
+/** A line of live status a contributed group reports beside its fields (e.g. that nothing can enforce it). */
+interface PluginConfigNotice {
+    /**
+     * `progress` = work the group started is still running (an install, a download): the page
+     * reads the groups again every few seconds while any notice says so, and the text is the
+     * step it is on.
+     */
+    tone: "attention" | "muted" | "progress";
+    text: string;
+    textZh?: string;
+    /** More about the notice, disclosed under it on request; lines separated by `\n`. */
+    details?: string;
+    detailsZh?: string;
+}
+/** One settings group (GET /api/admin/plugin-config): its schema and its values, secrets masked. */
+interface PluginConfigEntry {
+    /** The group's name — the id of the contribution that declared it; also the store key. */
+    name: string;
+    configuration: PluginConfiguration;
+    /** Stored values merged onto the defaults; a secret arrives masked (`first4…last4` or `***`), never in the clear. */
+    values: Record<string, unknown>;
+    /** Drawn inside that entry's card and saved with it (a sandbox backend's options inside the sandbox's). */
+    parent?: string;
+    /** Live status beside the fields; absent when there is none. */
+    notices?: PluginConfigNotice[];
+    /** What this group can DO once, on the machine, drawn as buttons beneath its notices. */
+    actions?: PluginConfigActionDecl[];
+    /** Enum options this machine cannot honour now: drawn greyed out with the reason; a save choosing one is refused. */
+    unavailable?: PluginConfigUnavailableDecl[];
+    /**
+     * For a group whose settings a backend plugin enforces (the sandbox): whether one that
+     * applies to this machine's OS is installed, and which packages this OS defaults to. The card
+     * offers to install `recommended` when the group's switch is turned on and none is installed.
+     * Asked per read, like the notices; the client never guesses the OS.
+     */
+    backend?: PluginConfigBackend;
+}
+/** Whether a backend that applies to this machine is installed, and this OS's default ones. */
+interface PluginConfigBackend {
+    /** A backend for this OS is installed: loaded, or installed and failing its check. */
+    installed: boolean;
+    /**
+     * The npm packages this OS defaults to, installed together; absent on an OS with no default
+     * backend. Linux names two: bubblewrap, and sandbox-dsh, which confines files through
+     * Landlock where bubblewrap is refused.
+     */
+    recommended?: string[];
+}
+/** One enum option (or boolean position) a settings group cannot honour on this machine, and why. */
+interface PluginConfigUnavailableDecl {
+    field: string;
+    /** A `table` field's column: the option is unavailable in every cell of that column. */
+    column?: string;
+    /** An enum option, or a boolean field's position: "true" or "false". */
+    value: string;
+    reason: string;
+    reasonZh?: string;
+}
+/** One button under a settings group: what it is called, and what pressing it will do. */
+interface PluginConfigActionDecl {
+    id: string;
+    title: string;
+    titleZh?: string;
+    description?: string;
+    descriptionZh?: string;
+}
+/** POST /api/admin/plugin-config/action — what running one reported. */
+interface PluginConfigActionResponse {
+    ok: boolean;
+    message: string;
+    messageZh?: string;
+    /** The groups as they stand after it ran: a setup that worked changes what the page says. */
+    plugins: PluginConfigEntry[];
+}
+interface PluginConfigResponse {
+    plugins: PluginConfigEntry[];
+}
+/**
+ * PUT /api/admin/plugin-config — one group's update. Every named field is validated
+ * against its type; an omitted field keeps its stored value; a secret sent as the masked
+ * value keeps the stored one, and `null` or `""` clears any field. 400 `plugin_config_invalid`
+ * (with `field`) on a value that does not fit or a required field left empty; 404
+ * `plugin_config_unknown` for a name no group answers to.
+ */
+interface PluginConfigUpdateRequest {
+    name: string;
+    values: Record<string, unknown>;
+}
+/**
+ * An installed plugin the running build cannot fully run (plugin/unsatisfied.ts): it
+ * contributes to a slot, or wires to a module or interface, that this build does not have.
+ * Also what a refused push names (`plugins_unsatisfied`) and a confirmed one reports.
+ */
+interface UnsatisfiedPlugin {
+    /** The package specifier, as the installed-plugins list spells it. */
+    specifier: string;
+    /** True when the whole plugin is left out of this generation; false when only the contributions this build has no slot for were dropped and the rest of it runs. */
+    disabled: boolean;
+    /** What this build lacks, in the platform's own words. */
+    reason: string;
+}
+/** One plugin a Project lists (GET /api/projects/:projectId/plugins/installed). */
+interface InstalledPlugin {
+    /** The package specifier as written in the file. */
+    specifier: string;
+    /** Whether the running process holds this package — its modules are in the tree. */
+    active: boolean;
+    /**
+     * Where the package came from: shipped with the build (a hot push's assets, or the
+     * installation's own `plugins/`) rather than fetched from npm. A tag on an installed
+     * plugin — being shipped is not being installed.
+     */
+    builtin: boolean;
+    /** Module names the package declares it adds. */
+    modules: string[];
+    /** Node names the package declares it stands in for. */
+    replaces: string[];
+    /**
+     * Why the package is not running: unresolvable, or a load that
+     * failed (an import that threw, a module name another plugin already took). Only ever
+     * reported for a plugin this server is asked to run (`here`).
+     */
+    error?: string;
+    /**
+     * Present when this build cannot fully run the package (see {@link UnsatisfiedPlugin}).
+     * With `disabled`, `active` is false and a restart would not load it; without, the package
+     * runs minus the contributions this build has no slot for. Only reported for a plugin this
+     * server is asked to run (`here`).
+     */
+    unsatisfied?: Pick<UnsatisfiedPlugin, "disabled" | "reason">;
+    /** Listed in the shared `[plugins]` table: every machine runs it. */
+    everywhere: boolean;
+    /** The machines whose own `[plugins.<machineId>]` table lists it, by machine id. */
+    machines: string[];
+    /**
+     * Whether THIS server is asked to run it — shared, or listed for this server's own id. A
+     * plugin listed only for other machines is neither installed nor loaded here, so `active`
+     * is false and no `error` is reported for it.
+     */
+    here: boolean;
+}
+/** What an install put on this server (POST …/plugins/installed and …/installed/archive). */
+interface PluginInstallOutcome {
+    /** The package name npm installed — for a link, the name its package.json carries. */
+    name: string;
+    version: string | null;
+    /** It carries skills, a hook package or MCP servers: the library lists it, and nothing loads it. */
+    library: boolean;
+    /** It carries server modules: the Project's list loads it. */
+    modules: boolean;
+    /** The zip held the version already installed: nothing was installed. */
+    unchanged?: boolean;
+}
+/** POST /api/projects/:projectId/plugins/installed/archive (admin): a plugin package zip, base64. */
+interface PluginArchiveImportRequest {
+    dataBase64: string;
+    /** Replace another installed version of the package (the 409 `plugin_exists` question). */
+    overwrite?: boolean;
+}
+interface InstalledPluginsResponse {
+    plugins: InstalledPlugin[];
+    /** After an install: what landed on this server. */
+    installed?: PluginInstallOutcome;
+    /**
+     * Specifiers this build SHIPS (the hot push's assets, or the installation's own
+     * `plugins/`): installable without a download, and not installed until listed.
+     */
+    shipped: string[];
+    /** The file the list lives in, named for the page that explains where to edit it by hand. */
+    file: string;
+    /** This server's own machine id — the key of its `[plugins.<machineId>]` table. */
+    machineId: string;
+    /** A listed plugin neither runs, nor failed to load, nor is one this build cannot run: the App could not be re-assembled around it (the previous one was restored), so a restart is what applies it. */
+    restartPending: boolean;
+}
+/** The browser an agent drives: the desktop's built-in one, or the user's own Chrome. */
+type BrowserBackend = "builtin" | "chrome";
+/**
+ * What a backend's link can do. The shell cannot create tabs (the Web App's <webview> does) and
+ * throttles and measures its guests; the extension creates, closes and focuses tabs itself and
+ * has no cookie store the server may touch.
+ */
+interface BrowserLinkCapabilities {
+    /** `open-tab`, `close-tab` and `activate-tab` are answered (chrome). */
+    createsTabs: boolean;
+    /** `throttle` and the `metrics` events (builtin). */
+    throttles: boolean;
+    /** `set-cookies` and `clear-data` (builtin). */
+    cookieStore: boolean;
+}
+/**
+ * One tab of the agent browser. Built-in: a guest page, `id` its webContents id. Chrome: a tab
+ * the extension drives (one it created in the Penguin tab group, or one the user added), `id`
+ * Chrome's tab id; `canGoBack`/`canGoForward` are always false there (the tabs API cannot read
+ * them).
+ */
+interface BuiltinBrowserTab {
+    id: number;
+    /** The built-in tab belongs to this conversation; absent for pages opened outside a conversation. */
+    sessionId?: string;
+    /** Electron storage partition, shared only within this tab's Project. */
+    partition?: string;
+    url: string;
+    title: string;
+    loading: boolean;
+    canGoBack: boolean;
+    canGoForward: boolean;
+    favicon?: string;
+    /**
+     * Present while the page's renderer is gone, with Electron's reason (`crashed`, `oom`,
+     * `killed`, …): the panel shows the crash until the page is reloaded, and an agent action on
+     * the tab answers 409 `tab_crashed`.
+     */
+    crashed?: string;
+}
+/**
+ * Why the agent browser cannot be driven. Built-in: not under the desktop shell, a shell too old
+ * to host it, or no app window to host a new tab. Chrome: this user has no paired extension, it
+ * is paired but not connected now, or an admin switched Chrome connections off server-wide.
+ */
+type BuiltinBrowserUnavailableReason = "not_desktop" | "shell_unsupported" | "no_window" | "extension_not_paired" | "extension_disconnected" | "extension_disabled";
+/** One backend as GET /status lists it for the caller. */
+interface BrowserBackendInfo {
+    backend: BrowserBackend;
+    available: boolean;
+    reason?: BuiltinBrowserUnavailableReason;
+    /** chrome: the caller's connected extension, else the one seen most recently; absent when none is paired. */
+    extension?: {
+        id: string;
+        name: string;
+        version: string;
+        connected: boolean;
+        lastSeenAt: string | null;
+    };
+}
+/**
+ * GET /api/builtin-browser/status: the caller's effective backend (`backend`) — whether it can
+ * be driven now, its tabs — and every backend this server offers the caller (`backends`).
+ */
+interface BuiltinBrowserStatus {
+    /** Whether the effective backend can be driven now. */
+    available: boolean;
+    reason?: BuiltinBrowserUnavailableReason;
+    backend: BrowserBackend;
+    backends: BrowserBackendInfo[];
+    tabs: BuiltinBrowserTab[];
+    activeTabId: number | null;
+    /** The shell's latest measurement of the built-in browser's load; absent before its first one, and on chrome. */
+    metrics?: BuiltinBrowserMetrics;
+}
+/** GET / PUT /api/builtin-browser/backend: the caller's backend and the ones they may choose. */
+interface BrowserBackendResponse {
+    backend: BrowserBackend;
+    choices: BrowserBackend[];
+}
+/** One Chrome paired to the caller's account (a row of `browser_extensions`). */
+interface BrowserExtensionRecord {
+    id: string;
+    /** As the extension names itself, e.g. "Chrome 130 on macOS". */
+    name: string;
+    version: string;
+    createdAt: string;
+    lastSeenAt: string | null;
+    /** Whether this one holds the caller's connection now (one at a time per user). */
+    connected: boolean;
+}
+/** GET /api/builtin-browser/extension. */
+interface BrowserExtensionsResponse {
+    paired: BrowserExtensionRecord[];
+    /** The id of the connected one, when one is. */
+    connected?: string;
+    /** The admin's server-wide switch (`ServerSettings.browserExtensionsEnabled`). */
+    enabled: boolean;
+}
+/**
+ * POST /api/builtin-browser/extension/pairings: a one-time code for the signed-in user, valid
+ * for ten minutes, used once; the dialog shows it beside the server address.
+ */
+interface BrowserExtensionPairingResponse {
+    /** 43 base64url characters. */
+    code: string;
+    /** ISO time the code stops working. */
+    expiresAt: string;
+    /** The request's Origin, when it carried one: the address the browser reaches this server at. */
+    origin: string | null;
+}
+/** POST /api/builtin-browser/extension/pair (no cookie: the extension's own request). */
+interface BrowserExtensionPairRequest {
+    code: string;
+    /** How the extension names this Chrome, e.g. "Chrome 130 on macOS" (1–80 characters). */
+    name: string;
+    /** The extension's own version (manifest.version). */
+    version: string;
+}
+/** What /extension/pair answers: the long-lived token, shown once and stored only hashed here. */
+interface BrowserExtensionPairResponse {
+    extensionId: string;
+    /** Rides the WebSocket's subprotocol list as `token.<token>`; never a URL. */
+    token: string;
+    /** This server's install id (a stable name for the data root); null when it is unknown. */
+    installId: string | null;
+    user: {
+        userId: string;
+        displayName: string | null;
+    };
+    serverVersion: string;
+}
+/**
+ * The extension WebSocket's close codes (`/api/builtin-browser/extension/ws`). Besides these the
+ * server closes with 1012 when it restarts or hot-swaps (reconnect with the usual backoff).
+ *
+ * - 4001 replaced: another extension of the same user connected (last connected wins); do not
+ *   auto-retry.
+ * - 4003 revoked: the pairing was revoked (or the token was); forget this server.
+ * - 4005 protocol_mismatch: no `penguin-browser.1` subprotocol, or a hello the server does not
+ *   speak; the extension needs updating.
+ * - 4008 ping_timeout: two pings (or the hello) went unanswered.
+ * - 4009 disabled: an admin switched Chrome connections off; retry hourly.
+ */
+type BrowserExtensionCloseCode = 4001 | 4003 | 4005 | 4008 | 4009;
+/** One tab's share of the built-in browser's load, as the shell last measured it. */
+interface BuiltinBrowserTabMetrics {
+    tabId: number;
+    /** The memory held by the processes behind the page (its own and its cross-site frames'), KB. */
+    memoryKB: number;
+    /** Their CPU use since the previous measurement, in percent of one core. */
+    cpuPercent: number;
+}
+/** Why the built-in browser should be lighter. */
+type BuiltinBrowserLoadWarning = 
+/** Its pages together hold more memory than they should. */
+"memory"
+/** This computer is running out of memory. */
+ | "low_system_memory"
+/** More tabs are open than the browser should hold. */
+ | "many_tabs";
+/**
+ * The built-in browser's load: GET /status's `metrics`, and the `builtin_browser_metrics` event
+ * after each of the shell's measurements (every ~10 s while tabs are open, and soon after one
+ * closes). The thresholds are the server's; the UI and the CLI only word what it concluded.
+ */
+interface BuiltinBrowserMetrics {
+    /** When the server received the measurement (epoch ms). */
+    at: number;
+    tabs: BuiltinBrowserTabMetrics[];
+    /** All the pages' memory, a process two tabs share counted once, KB. */
+    totalKB: number;
+    /**
+     * This computer's memory, KB. Absent on macOS, whose free count leaves out the memory it would
+     * readily hand back, so that "free" there reads as nearly none on a healthy machine.
+     */
+    system?: {
+        freeKB: number;
+        totalKB: number;
+    };
+    /** What to warn about now; empty when all is well. */
+    warnings: BuiltinBrowserLoadWarning[];
+    /** While a memory warning stands: the tabs holding the most memory, heaviest first. */
+    heavyTabIds: number[];
+}
+/** GET /api/builtin-browser/tabs. */
+interface BuiltinBrowserTabsResponse {
+    tabs: BuiltinBrowserTab[];
+    activeTabId: number | null;
+}
+/** POST /api/builtin-browser/tabs/:tab/scan — GenericAgent's web_scan. */
+interface BuiltinBrowserScanResult {
+    tab: BuiltinBrowserTab;
+    tabs: BuiltinBrowserTab[];
+    activeTabId: number | null;
+    /** Simplified HTML, or plain text with `textOnly`. */
+    content?: string;
+    truncated?: boolean;
+}
+/** POST /api/builtin-browser/tabs/:tab/exec (and click / type) — GenericAgent's web_execute_js. */
+interface BuiltinBrowserExecResult {
+    status: "success" | "failed";
+    tabId: number;
+    /** The script's JSON-safe return value. */
+    value?: unknown;
+    error?: string;
+    /** The page navigated or reloaded while the script ran. */
+    reloaded?: boolean;
+    /** Tabs opened while the call ran (popups, target=_blank). */
+    newTabs?: {
+        id: number;
+        url: string;
+    }[];
+    /** Text that appeared during the call and may be gone again (toasts, flashes). */
+    transients?: string[];
+    diff?: {
+        changed: number;
+        topChange?: string;
+    };
+    suggestion?: string;
+    /** click only: where the trusted click landed. */
+    clicked?: {
+        x: number;
+        y: number;
+        tag?: string;
+        text?: string;
+    };
+    /** The page's dialogs the call answered, in order (see BuiltinBrowserDialog). */
+    dialogs?: BuiltinBrowserDialog[];
+}
+/**
+ * A dialog the page opened during an exec, click or type, which the call answered so the page
+ * would not block: an alert is accepted, and a confirm, prompt or leave-page dialog dismissed
+ * unless the request said `acceptDialogs`.
+ */
+interface BuiltinBrowserDialog {
+    type: "alert" | "confirm" | "prompt" | "beforeunload";
+    message: string;
+    accepted: boolean;
+}
+/** POST /api/builtin-browser/tabs/:tab/screenshot. */
+interface BuiltinBrowserScreenshot {
+    mime: "image/png";
+    /** Base64. */
+    data: string;
+}
+type BuiltinBrowserImportBrowser = "chrome" | "edge" | "brave" | "chromium" | "vivaldi" | "opera" | "arc" | "firefox";
+/** One profile of a system browser that can be imported from. */
+interface BuiltinBrowserImportSource {
+    /** `<browser>:<profile dir>`, e.g. `chrome:Default`. */
+    id: string;
+    browser: BuiltinBrowserImportBrowser;
+    browserName: string;
+    /** The profile's directory name. */
+    profile: string;
+    /** The profile's display name. */
+    profileName: string;
+    hasCookies: boolean;
+    hasHistory: boolean;
+}
+interface BuiltinBrowserImportSourcesResponse {
+    sources: BuiltinBrowserImportSource[];
+}
+/** POST /api/builtin-browser/import. */
+interface BuiltinBrowserImportRequest {
+    sessionId?: string;
+    projectId?: string;
+    sourceId: string;
+    cookies?: boolean;
+    history?: boolean;
+    /** Only cookies of these sites (a domain matches itself and its subdomains). */
+    domains?: string[];
+}
+interface BuiltinBrowserImportResult {
+    sourceId: string;
+    cookies?: {
+        found: number;
+        imported: number;
+        skipped: number;
+        failed: number;
+    };
+    history?: {
+        found: number;
+        imported: number;
+    };
+    warnings: string[];
+}
+interface BuiltinBrowserHistoryEntry {
+    url: string;
+    title: string;
+    visitCount: number;
+    /** Epoch ms. */
+    lastVisitAt: number;
+    /** `builtin` for pages visited in the built-in browser, else the browser it was imported from. */
+    source: string;
+}
+interface BuiltinBrowserHistoryResponse {
+    entries: BuiltinBrowserHistoryEntry[];
+}
+/**
+ * GET / PUT /api/builtin-browser/settings: the browser's own settings, a file of the server's
+ * that is read and written without the desktop shell. PUT takes the whole object.
+ */
+interface BuiltinBrowserSettings {
+    /**
+     * The page a new tab opens when it is given no address — the panel's "+", an agent's new tab
+     * — and the toolbar's Home button goes to: an http(s) address, or null for none (a new tab is
+     * then blank). PUT takes a bare host too and answers the address as stored.
+     */
+    homepage: string | null;
+}
+type BuiltinBrowserAction = "navigate" | "scan" | "exec" | "click" | "type" | "screenshot" | "cdp";
+/**
+ * User-channel events of the agent browser. The built-in backend's go to every admin; a chrome
+ * backend's go to the user whose Chrome it is, as do `builtin_browser_backend` and
+ * `builtin_browser_extension`.
+ */
+type BuiltinBrowserServerEvent = 
+/**
+ * A backend's whole tab list. `backend` names whose: a desktop admin hears both the built-in
+ * browser's and their own Chrome's, and the two lists must not overwrite each other.
+ */
+{
+    type: "builtin_browser_tabs";
+    tabs: BuiltinBrowserTab[];
+    activeTabId: number | null;
+    backend: BrowserBackend;
+}
+/** Create a guest for `url`, then POST /tabs/claim with `requestId` once it has a webContents id. */
+ | {
+    type: "builtin_browser_open";
+    partition?: string;
+    requestId: string;
+    url: string;
+    activate: boolean;
+    openerTabId?: number;
+    sessionId?: string;
+} | {
+    type: "builtin_browser_close";
+    tabId: number;
+}
+/** A draft or healed conversation acquired its permanent id. */
+ | {
+    type: "builtin_browser_session";
+    fromSessionId: string;
+    sessionId: string;
+} | {
+    type: "builtin_browser_activity";
+    tabId: number;
+    busy: boolean;
+    action: BuiltinBrowserAction;
+    sessionId?: string;
+}
+/** The shell measured the browser's load (see BuiltinBrowserMetrics). */
+ | {
+    type: "builtin_browser_metrics";
+    metrics: BuiltinBrowserMetrics;
+}
+/** The user switched backend (PUT /backend); every window of theirs follows. */
+ | {
+    type: "builtin_browser_backend";
+    backend: BrowserBackend;
+}
+/** The user's Chrome connected, went away, was replaced by another Chrome of theirs, or was revoked. */
+ | {
+    type: "builtin_browser_extension";
+    state: "connected" | "disconnected" | "replaced" | "revoked";
+    extension?: BrowserExtensionRecord;
+};
+/** A cookie as the shell writes it (Electron's CookiesSetDetails). */
+interface DesktopBrowserCookie {
+    url: string;
+    name: string;
+    value: string;
+    domain?: string;
+    path?: string;
+    secure?: boolean;
+    httpOnly?: boolean;
+    /** Unix seconds; absent = session cookie. */
+    expirationDate?: number;
+    sameSite?: "unspecified" | "no_restriction" | "lax" | "strict";
+}
+/**
+ * Server → browser link: what the shell (built-in) or the extension (chrome) does with its tabs.
+ * Mechanism only — the product logic stays on the server. The names are historical: the same
+ * envelopes travel the extension's WebSocket as JSON text frames.
+ */
+type DesktopBrowserCommand = 
+/** Reply: a BrowserHello. An older shell never answers. */
+{
+    op: "hello";
+}
+/** Reply: `{ tabs: BuiltinBrowserTab[] }`. */
+ | {
+    op: "tabs";
+}
+/**
+ * Reply: the CDP method's result object. `events` names the tab's CDP events the shell relays
+ * from then on, as `cdp-event`s: it replaces the list before (empty relays none), and is set
+ * before the command runs, so an event the command itself causes is not missed. Without it
+ * the list stays as it is.
+ */
+ | {
+    op: "cdp";
+    tabId: number;
+    method: string;
+    params?: Record<string, unknown>;
+    events?: string[];
+}
+/** Reply: `{ set: number; failed: number; errors: string[] }` (at most 10 errors). */
+ | {
+    op: "set-cookies";
+    cookies: DesktopBrowserCookie[];
+    partition?: string;
+}
+/** Reply: `{}`. */
+ | {
+    op: "clear-data";
+    storages: ("cookies" | "cache" | "storage")[];
+    partition?: string;
+}
+/**
+ * Reply: `{}`. The tabs whose pages may be throttled while out of sight (Electron's background
+ * throttling, applied at once); every other tab runs at full speed. It replaces the list
+ * before. A tab is unthrottled until a command lists it, so a server that never sends one
+ * changes nothing. A shell older than this command answers `unknown_op`.
+ */
+ | {
+    op: "throttle";
+    tabIds: number[];
+}
+/**
+ * Chrome only (the shell answers `unknown_op`). Reply: `{ tab: BuiltinBrowserTab }`. A tab at
+ * `url` (http(s) or about:blank, checked by the server) in the extension's Penguin tab group;
+ * `activate` asks for it to be the selected tab of its window.
+ */
+ | {
+    op: "open-tab";
+    url: string;
+    activate: boolean;
+}
+/** Chrome only. Reply: `{}`. Closes a tab the extension drives. */
+ | {
+    op: "close-tab";
+    tabId: number;
+}
+/** Chrome only. Reply: `{}`. Shows the tab in the user's Chrome (selects it, focuses its window). */
+ | {
+    op: "activate-tab";
+    tabId: number;
+}
+/** Chrome only. Reply: `{}`. Sent every 20 s; the traffic keeps the MV3 service worker alive. */
+ | {
+    op: "ping";
+};
+/**
+ * The `hello` reply. Built-in: `{ version: 1, partition }` (an older shell sends no `backend`).
+ * Chrome: `{ version: 1, backend: "chrome", extension }`; any other version is closed 4005.
+ */
+interface BrowserHello {
+    version: 1;
+    backend?: BrowserBackend;
+    partition?: string;
+    extension?: {
+        version: string;
+        chrome: string;
+        name: string;
+    };
+}
+interface DesktopBrowserCommandMessage {
+    type: "desktop-browser-command";
+    id: string;
+    command: DesktopBrowserCommand;
+}
+interface DesktopBrowserReplyMessage {
+    type: "desktop-browser-reply";
+    id: string;
+    ok: boolean;
+    result?: unknown;
+    error?: string;
+}
+type DesktopBrowserEvent = {
+    kind: "tab";
+    tab: BuiltinBrowserTab;
+} | {
+    kind: "tab-closed";
+    tabId: number;
+}
+/**
+ * window.open / target=_blank inside a guest (the shell denied it and asks for a tab instead),
+ * or the context menu's "Open link in new tab". `background`: the tab should open behind the
+ * current one, as a middle-click or that menu entry does in Chrome.
+ */
+ | {
+    kind: "open-request";
+    url: string;
+    openerTabId: number;
+    background?: boolean;
+}
+/** One of the tab's CDP events a `cdp` command's `events` asked for. */
+ | {
+    kind: "cdp-event";
+    tabId: number;
+    method: string;
+    params: Record<string, unknown>;
+}
+/**
+ * The tab's renderer went away (Electron's render-process-gone reason and exit code). The tab
+ * stays; its `tab` events carry `crashed` until the page is reloaded, and the shell refuses
+ * CDP commands for it meanwhile (`tab_crashed`).
+ */
+ | {
+    kind: "tab-crashed";
+    tabId: number;
+    reason: string;
+    exitCode: number;
+}
+/**
+ * The shell's measurement of its guests (every ~10 s while there are any, and once more
+ * shortly after one closes, empty after the last): each tab's memory and CPU, and the pages'
+ * memory together, a process shared by two tabs counted once.
+ */
+ | {
+    kind: "metrics";
+    tabs: BuiltinBrowserTabMetrics[];
+    totalKB: number;
+}
+/**
+ * Chrome only: the tab still exists in Chrome but the agent may no longer drive it — the user
+ * pressed Cancel on Chrome's debugging bar (`user`), the debugger went away otherwise
+ * (`detached`), or the page is one Chrome lets no extension attach to (`restricted`). The
+ * extension fails that tab's pending commands with the error `tab_released`.
+ */
+ | {
+    kind: "tab-released";
+    tabId: number;
+    reason: "user" | "detached" | "restricted";
+};
+interface DesktopBrowserEventMessage {
+    type: "desktop-browser-event";
+    event: DesktopBrowserEvent;
+}
 
-export { type AdminPasswordResetRequest, type AdminUserCreateRequest, type AdminUserCreateResponse, type AdminUsersResponse, type AgentCompactionConfigDto, type AgentConfigDto, type AgentConfigResponse, type AgentConfigUpdateRequest, type AgentCreateRequest, type AgentCreateResponse, type AgentHooksConfigDto, type AgentHooksResponse, type AgentImportRequest, type AgentImportResponse, type AgentKernelUpdateResponse, type AgentMemoryConfigDto, type AgentModelConfigDto, type AgentPluginsInstallResponse, type AgentSchedulesConfigDto, type AgentSkillsConfigDto, type AgentSkillsResponse, type AgentSummary, type AgentTraceDateGroup, type AgentTraceFileRef, type AgentTraceSessionEntry, type AgentTraceSessionFile, type AgentTraceSessionGroup, type AgentTracesResponse, type AgentVaultConfigDto, type AgentsResponse, type ApprovalDecisionRequest, type ApprovalMode, type AuthLoginRequest, type AuthResponse, type BenchmarkCaseScore, type BenchmarkCaseSummary, type BenchmarkCasesResponse, type BenchmarkCreateCase, type BenchmarkCreateRequest, type BenchmarkCreateResponse, type BenchmarkEvaluation, type BenchmarkRunScore, type BenchmarkStatus, type BenchmarkSummary, type BenchmarksResponse, type CaseMaterial, type ChatDefaultsDto, type CommandPolicyDto, type CommandPolicyRuleDto, type CompanyServerEvent, type ContextFileShare, type ContextToolShare, type ContributionsResponse, type CredentialInfo, type DefaultModelResponse, type DefaultModelUpdateRequest, type DesktopTrayCommandMessage, type DesktopTrayLocale, type DesktopTrayPatch, type DesktopTrayStatus, type DesktopTrayStatusMessage, type DesktopTrayStatusResponse, type DesktopUpdateStatus, type DesktopUpdateStatusResponse, type DesktopUpdaterCommandMessage, type DesktopUpdaterStatusMessage, type DirEntryInfo, type DirListResponse, type DirectorySkillItem, type DirectorySkillsResponse, type DraftShortcut, type EndpointModelListRequest, type EndpointModelListResponse, type ErrorBody, type FeishuBindingInfo, type FeishuBindingPutRequest, type FeishuBindingResponse, type FeishuTestRequest, type FeishuTestResponse, type FilesMoveRequest, type FilesStatRequest, type FilesStatResponse, type FilesWriteRequest, type GoalResponse, type GoalServerEvent, type GoalStateView, type HistoryMessage, type HookArchiveInstallRequest, type HookItem, type InstallResponse, type MachineInfo, type MachineJob, type MachineServerStatus, type MachinesResponse, type McpServerTestResponse, type MeResponse, type MemberAddRequest, type MemberAddResponse, type MemberInfo, type MembersResponse, type MemoryFileInfo, type MemoryFileResponse, type MemoryFilesResponse, type MemoryImportMode, type MemoryImportRequest, type MemoryImportResponse, type MemoryOverviewResponse, type MemoryScopeExport, type MemoryScopeInfo, type MemoryTransferFile, type MessagesLiveTail, type MessagesPageInfo, type MessagesResponse, type MessagingBindingCommon, type MessagingBindingInfo, type MessagingBindingStateRequest, type MessagingBindingsResponse, type MessagingChannel, type MessagingChannelState, type MessagingDeliveryError, type MessagingDeliveryPatch, type MessagingRuntimeState, type MessagingRuntimeStatus, type MessagingTestMessageResponse, type ModelInfo, type ModelOAuthCodeRequest, type ModelOAuthCodeResponse, type ModelOAuthErrorCode, type ModelOAuthMode, type ModelOAuthStartRequest, type ModelOAuthStartResponse, type ModelOAuthStatusResponse, type ModelPricingDto, type ModelProtocolDetectRequest, type ModelProtocolDetectResponse, type ModelProtocolProbeDto, type ModelRefDto, type ModelTestRequest, type ModelTestResponse, type ModelUpdateEntry, type ModelVisionDetectRequest, type ModelVisionDetectResponse, type ModelVisionOutcome, type ModelsResponse, type ModelsUpdateRequest, type OrgApprovalMode, type OrgBudgetAlert, type OrgCalendarItem, type OrgCalendarOutcome, type OrgCalendarResponse, type OrgCalendarUpsertRequest, type OrgCalendarWriteResponse, type OrgChannelCreateRequest, type OrgChannelDetail, type OrgChannelItem, type OrgChannelMember, type OrgChannelMemberRequest, type OrgChannelMessage, type OrgChannelMessageSendRequest, type OrgChannelMessagesResponse, type OrgChannelNotice, type OrgChannelNoticeKind, type OrgChannelPatchRequest, type OrgChannelReadRequest, type OrgChannelsResponse, type OrgChartResponse, type OrgDeskItem, type OrgDeskResponse, type OrgEmployeeItem, type OrgEmployeePatchRequest, type OrgEmployeeState, type OrgFinanceEmployee, type OrgFinanceResponse, type OrgFinanceTicket, type OrgHandbookFile, type OrgHandbookFileResponse, type OrgHandbookFileWriteRequest, type OrgHandbookFilesResponse, type OrgHandbookResponse, type OrgHireRequest, type OrgInbox, type OrgLanguage, type OrgSessionsResponse, type OrgSpendSummary, type OrgStatus, type OrgTicketAttachRequest, type OrgTicketBlockRequest, type OrgTicketChange, type OrgTicketCreateRequest, type OrgTicketDetail, type OrgTicketHistoryAction, type OrgTicketHistoryEntry, type OrgTicketItem, type OrgTicketMoveRequest, type OrgTicketPriority, type OrgTicketProgressRequest, type OrgTicketSessionItem, type OrgTicketStartRequest, type OrgTicketStartResponse, type OrgTicketStatus, type OrgTicketUpdateRequest, type OrgTicketsResponse, type OrgTriggerKind, type OrganizationCreateRequest, type OrganizationDetail, type OrganizationPatchRequest, type OrganizationSettings, type OrganizationSummary, type OrganizationsResponse, type PasswordChangeRequest, type PendingFollowUpInfo, type PendingSteeringInfo, type PluginFilesResponse, type PluginGroupItem, type PluginInstallRequest, type PluginItem, type PluginLibraryResponse, type PluginUpdateRef, type PrefsResponse, type ProjectCreateRequest, type ProjectCreateResponse, type ProjectRole, type ProjectSummary, type ProjectUpdateRequest, type ProjectUpdateResponse, type ProjectsResponse, type ProtocolProbeOutcome, type ProxyProbeDto, type ProxyProbeOutcome, type ProxyProbeProvider, type ProxyProbeResponse, type ProxyProbeTargetDto, type ProxyProbeTargetsResponse, type QQBindingInfo, type QQBindingPutRequest, type QQBindingResponse, type QQScanPollResponse, type QQScanStartResponse, type QQTestRequest, type QQTestResponse, type RecalledMessageResponse, type RendererRef, type RequestSpan, type RestartResponse, type RetryNowResponse, type ScheduleItem, type ScheduleServerEvent, type ScheduleStatus, type ScheduleUpsertRequest, type SchedulesResponse, type SemanticIdSuggestReason, type SemanticIdSuggestRequest, type SemanticIdSuggestResponse, type ServerEvent, type ServerSettings, type ServerSettingsResponse, type ServerSettingsUpdateRequest, type SessionBackgroundTasks, type SessionCategory, type SessionCategoryCounts, type SessionContextParts, type SessionContextResponse, type SessionCreateRequest, type SessionCreateResponse, type SessionForkRequest, type SessionForkResponse, type SessionInfo, type SessionPatchRequest, type SessionProcessInfo, type SessionProcessesResponse, type SessionResponse, type SessionSource, type SessionStatus, type SessionTracesResponse, type SessionsResponse, type SkillArchiveInstallRequest, type SkillMetadataItem, type SteerRequest, type SubagentMessageResponse, type SubagentRuntimeInfo, TICKET_SLUG_PATTERN, type TaskCreateRequest, type TaskCreateResponse, type TaskInputPart, type TelegramBindingInfo, type TelegramBindingPutRequest, type TelegramBindingResponse, type TelegramTestRequest, type TelegramTestResponse, type ToolCallSpan, type TraceAnalysisResponse, type TraceEventsResponse, type TraceFileInfo, type TraceImportRequest, type TraceImportResponse, type TraceModelSegment, type TraceOtherSpan, type TracePosition, type TraceTaskStats, type TraceToolSpan, type UiPrefs, type UpdateCheckResponse, type UpdateJobPhase, type UpdateJobStatus, type UpdateProfileRequest, type UpdateProfileResponse, type UpdateRunResponse, type UploadLimits, type UsageAgentSeries, type UsageBucket, type UsageEntitySeriesCounts, type UsageErrorCount, type UsageErrorItem, type UsageErrorKind, type UsageErrors, type UsageErrorsClearResponse, type UsageErrorsPage, type UsageGranularity, type UsageGroupBy, type UsageGroupRow, type UsageModelSeries, type UsageModelTotal, type UsageModelTotals, type UsageResponse, type UsageSeriesPoint, type UsageTrendPointInTrace, type UserInfo, type VaultEntryInfo, type VaultEntryUpdate, type VaultResponse, type VaultUpdateRequest, type VersionResponse, type WeChatBindingInfo, type WeChatBindingPutRequest, type WeChatBindingResponse, type WeChatScanPollResponse, type WeChatScanStartResponse, type WeChatScanStatus, type WeChatScanVerifyRequest, type WeChatTestResponse, type WebContribution, type WorkspaceFileEntry, type WorkspaceFilesResponse, type WorkspaceSearchHit, type WorkspaceSearchResponse };
+export { type AdminPasswordResetRequest, type AdminUserCreateRequest, type AdminUserCreateResponse, type AdminUsersResponse, type AgentApiKeyCreateRequest, type AgentApiKeyCreateResponse, type AgentApiKeyInfo, type AgentApiResponse, type AgentApiSettings, type AgentApiUpdateRequest, type AgentCompactionConfigDto, type AgentConfigDto, type AgentConfigResponse, type AgentConfigUpdateRequest, type AgentCreateRequest, type AgentCreateResponse, type AgentHooksConfigDto, type AgentHooksResponse, type AgentImportRequest, type AgentImportResponse, type AgentKernelUpdateResponse, type AgentMcpServerItem, type AgentMcpServersResponse, type AgentMemoryConfigDto, type AgentModelConfigDto, type AgentPluginsInstallResponse, type AgentSchedulesConfigDto, type AgentSkillsConfigDto, type AgentSkillsResponse, type AgentSummary, type AgentTraceDateGroup, type AgentTraceFileRef, type AgentTraceSessionEntry, type AgentTraceSessionFile, type AgentTraceSessionGroup, type AgentTracesResponse, type AgentVaultConfigDto, type AgentsResponse, type ApprovalDecisionRequest, type ApprovalMode, type ArchivedSessionGroup, type ArchivedSessionGroupsResponse, type ArchivedSessionSource, type ArchivedSessionsBatch, type ArchivedSessionsBatchFilter, type ArchivedSessionsBatchResponse, type ArchivedSessionsQuery, type ArchivedSessionsResponse, type ArchivedSessionsRowsQuery, type AuthLoginRequest, type AuthResponse, type BenchmarkArchiveGitOrigin, type BenchmarkArchiveImportRequest, type BenchmarkArchiveImportResponse, type BenchmarkCaseScore, type BenchmarkCaseSummary, type BenchmarkCasesResponse, type BenchmarkCreateCase, type BenchmarkCreateRequest, type BenchmarkCreateResponse, type BenchmarkEvaluation, type BenchmarkManifestProblem, type BenchmarkOrigin, type BenchmarkOriginKind, type BenchmarkRunScore, type BenchmarkStatus, type BenchmarkSummary, type BenchmarksResponse, type BrowserBackend, type BrowserBackendInfo, type BrowserBackendResponse, type BrowserExtensionCloseCode, type BrowserExtensionPairRequest, type BrowserExtensionPairResponse, type BrowserExtensionPairingResponse, type BrowserExtensionRecord, type BrowserExtensionsResponse, type BrowserHello, type BrowserLinkCapabilities, type BuiltinBrowserAction, type BuiltinBrowserDialog, type BuiltinBrowserExecResult, type BuiltinBrowserHistoryEntry, type BuiltinBrowserHistoryResponse, type BuiltinBrowserImportBrowser, type BuiltinBrowserImportRequest, type BuiltinBrowserImportResult, type BuiltinBrowserImportSource, type BuiltinBrowserImportSourcesResponse, type BuiltinBrowserLoadWarning, type BuiltinBrowserMetrics, type BuiltinBrowserScanResult, type BuiltinBrowserScreenshot, type BuiltinBrowserServerEvent, type BuiltinBrowserSettings, type BuiltinBrowserStatus, type BuiltinBrowserTab, type BuiltinBrowserTabMetrics, type BuiltinBrowserTabsResponse, type BuiltinBrowserUnavailableReason, type CaseMaterial, type ChatDefaultsDto, type CommandPolicyDto, type CommandPolicyRuleDto, type CompanyServerEvent, type ConnectionSourceDto, type ContextFileShare, type ContextToolShare, type ContributionsResponse, type CostParts, type CredentialInfo, type DefaultModelResponse, type DefaultModelUpdateRequest, type DesktopBrowserCommand, type DesktopBrowserCommandMessage, type DesktopBrowserCookie, type DesktopBrowserEvent, type DesktopBrowserEventMessage, type DesktopBrowserReplyMessage, type DesktopFolderAccessMessage, type DesktopFolderAccessResult, type DesktopFolderAccessResultMessage, type DesktopOpenPrivacySettingsMessage, type DesktopPrivacyPane, type DesktopTrayCommandMessage, type DesktopTrayLocale, type DesktopTrayPatch, type DesktopTrayStatus, type DesktopTrayStatusMessage, type DesktopTrayStatusResponse, type DesktopUpdateStatus, type DesktopUpdateStatusResponse, type DesktopUpdaterCommandMessage, type DesktopUpdaterStatusMessage, type DirAccessResponse, type DirEntryInfo, type DirListResponse, type DirLocation, type DirStandardFolders, type DirectorySkillItem, type DirectorySkillsResponse, type DraftShortcut, type Employment, type EndpointModelListRequest, type EndpointModelListResponse, type ErrorBody, type ErrorDetails, type FeishuBindingInfo, type FeishuBindingPutRequest, type FeishuBindingResponse, type FeishuTestRequest, type FeishuTestResponse, type FilesCreateRequest, type FilesMoveRequest, type FilesStatRequest, type FilesStatResponse, type FilesWriteRequest, type GoalResponse, type GoalServerEvent, type GoalStateView, type HistoryMessage, type HookArchiveInstallRequest, type HookItem, type InstallResponse, type InstalledPlugin, type InstalledPluginsResponse, type LanguageIndexResponse, type LanguageSummary, MACHINE_PHASES, type MachineCheck, type MachineConfigSync, type MachineDiagnosis, type MachineEnvOnly, type MachineInfo, type MachineJob, type MachinePhase, type MachineReconnect, type MachineServerEvent, type MachineServerStatus, type MachineSkippedModel, type MachineSourceReach, type MachineSshFailure, type MachineUninstallRequest, type MachineUseRefusal, type MachinesAddRequest, type MachinesCheckoutImage, type MachinesResponse, type MachinesStopUsingRequest, type MachinesUseRequest, type MachinesUseResponse, type McpServerTestResponse, type McpTransport, type MeResponse, type MemberAddRequest, type MemberAddResponse, type MemberInfo, type MembersResponse, type MemoryFileInfo, type MemoryFileResponse, type MemoryFilesResponse, type MemoryImportMode, type MemoryImportRequest, type MemoryImportResponse, type MemoryOverviewResponse, type MemoryScopeExport, type MemoryScopeInfo, type MemoryTransferFile, type MessagesLiveTail, type MessagesPageInfo, type MessagesResponse, type MessagingBindingCommon, type MessagingBindingInfo, type MessagingBindingStateRequest, type MessagingBindingsResponse, type MessagingChannel, type MessagingChannelState, type MessagingDeliveryError, type MessagingDeliveryPatch, type MessagingRuntimeState, type MessagingRuntimeStatus, type MessagingTestMessageResponse, type ModelBalanceAmount, type ModelBalanceErrorCode, type ModelBalanceFailure, type ModelBalanceReading, type ModelBalanceResponse, type ModelEffectiveConnection, type ModelInfo, type ModelOAuthCodeRequest, type ModelOAuthCodeResponse, type ModelOAuthErrorCode, type ModelOAuthMode, type ModelOAuthStartRequest, type ModelOAuthStartResponse, type ModelOAuthStatusResponse, type ModelPricingDto, type ModelProtocolDetectRequest, type ModelProtocolDetectResponse, type ModelProtocolProbeDto, type ModelRefDto, type ModelScopeAuthFlowErrorCode, type ModelScopeAuthFlowStatusResponse, type ModelScopeAuthStartResponse, type ModelTestRequest, type ModelTestResponse, type ModelUpdateEntry, type ModelVisionDetectRequest, type ModelVisionDetectResponse, type ModelVisionOutcome, type ModelsResponse, type ModelsUpdateRequest, type OrgApprovalMode, type OrgBudgetAlert, type OrgCalendarItem, type OrgCalendarOutcome, type OrgCalendarResponse, type OrgCalendarUpsertRequest, type OrgCalendarWriteResponse, type OrgChannelCreateRequest, type OrgChannelDetail, type OrgChannelItem, type OrgChannelMember, type OrgChannelMemberRequest, type OrgChannelMessage, type OrgChannelMessageSendRequest, type OrgChannelMessagesResponse, type OrgChannelNotice, type OrgChannelNoticeKind, type OrgChannelPatchRequest, type OrgChannelReadRequest, type OrgChannelsResponse, type OrgChartResponse, type OrgDeskItem, type OrgDeskResponse, type OrgEmployeeItem, type OrgEmployeePatchRequest, type OrgEmployeeState, type OrgFinanceEmployee, type OrgFinanceResponse, type OrgFinanceTicket, type OrgHandbookFile, type OrgHandbookFileResponse, type OrgHandbookFileWriteRequest, type OrgHandbookFilesResponse, type OrgHandbookResponse, type OrgHireRequest, type OrgInbox, type OrgLanguage, type OrgSessionsResponse, type OrgSpendSummary, type OrgStatus, type OrgTicketAttachRequest, type OrgTicketBlockRequest, type OrgTicketChange, type OrgTicketCreateRequest, type OrgTicketDetail, type OrgTicketHistoryAction, type OrgTicketHistoryEntry, type OrgTicketItem, type OrgTicketMoveRequest, type OrgTicketPriority, type OrgTicketProgressRequest, type OrgTicketSessionItem, type OrgTicketStartRequest, type OrgTicketStartResponse, type OrgTicketStatus, type OrgTicketUpdateRequest, type OrgTicketsResponse, type OrgTriggerKind, type OrganizationCreateRequest, type OrganizationDetail, type OrganizationPatchRequest, type OrganizationSettings, type OrganizationSummary, type OrganizationsResponse, type PasswordChangeRequest, type PendingFollowUpInfo, type PendingSteeringInfo, type PinnedBalance, type PlatformAuthFlowErrorCode, type PlatformAuthFlowStatusResponse, type PlatformAuthStartResponse, type PlatformModelSyncResponse, type PluginArchiveImportRequest, type PluginConfigActionDecl, type PluginConfigActionResponse, type PluginConfigBackend, type PluginConfigColumnGroup, type PluginConfigEntry, type PluginConfigField, type PluginConfigNewRow, type PluginConfigNotice, type PluginConfigOption, type PluginConfigPinColumn, type PluginConfigResponse, type PluginConfigRowChoice, type PluginConfigTableColumn, type PluginConfigTableRow, type PluginConfigUnavailableDecl, type PluginConfigUpdateRequest, type PluginConfiguration, type PluginFilesResponse, type PluginGroupItem, type PluginIndexEntry, type PluginIndexResponse, type PluginInstallOutcome, type PluginInstallRequest, type PluginItem, type PluginLibraryResponse, type PluginMcpServerItem, type PluginReadmeResponse, type PluginSetupKeyItem, type PluginUpdateRef, type PrefsResponse, type PresetSyncMode, type PresetSyncRequest, type PresetSyncResponse, type ProjectCreateRequest, type ProjectCreateResponse, type ProjectRole, type ProjectScheduleItem, type ProjectSchedulesResponse, type ProjectSummary, type ProjectUpdateRequest, type ProjectUpdateResponse, type ProjectsResponse, type ProtocolProbeOutcome, type ProviderConnectionDto, type ProviderConnectionUpdate, type ProxyProbeDto, type ProxyProbeOutcome, type ProxyProbeProvider, type ProxyProbeResponse, type ProxyProbeTargetDto, type ProxyProbeTargetsResponse, type QQBindingInfo, type QQBindingPutRequest, type QQBindingResponse, type QQScanPollResponse, type QQScanStartResponse, type QQTestRequest, type QQTestResponse, type QuickStartItem, type RecalledMessageResponse, type RendererRef, type RequestSpan, type RestartResponse, type RetryNowResponse, type ScheduleItem, type ScheduleServerEvent, type ScheduleStatus, type ScheduleUpsertRequest, type SchedulesResponse, type SemanticIdKind, type SemanticIdSuggestReason, type SemanticIdSuggestRequest, type SemanticIdSuggestResponse, type ServerEvent, type ServerSettings, type ServerSettingsResponse, type ServerSettingsUpdateRequest, type SessionBackgroundTasks, type SessionBatchPageRequest, type SessionBatchResult, type SessionCategory, type SessionCategoryCounts, type SessionContextParts, type SessionContextResponse, type SessionCreateRequest, type SessionCreateResponse, type SessionForkRequest, type SessionForkResponse, type SessionInfo, type SessionPatchRequest, type SessionProcessInfo, type SessionProcessesResponse, type SessionResponse, type SessionSandbox, type SessionSandboxMode, type SessionSandboxNetwork, type SessionSandboxPreset, type SessionStatus, type SessionSwitchModelRequest, type SessionTracesResponse, type SessionsBatchRequest, type SessionsBatchResponse, type SessionsResponse, type SkillArchiveInstallRequest, type SkillMetadataItem, type SshHostRequest, type SshHostResponse, type SshHostSummary, type SshHostsResponse, type SteerRequest, type StoredKeybindings, type SubagentMessageResponse, type SubagentRuntimeInfo, TICKET_SLUG_PATTERN, type TaskCreateRequest, type TaskCreateResponse, type TaskInputPart, type TelegramBindingInfo, type TelegramBindingPutRequest, type TelegramBindingResponse, type TelegramTestRequest, type TelegramTestResponse, type ToolCallSpan, type TraceAnalysisResponse, type TraceEventsResponse, type TraceFileInfo, type TraceImportRequest, type TraceImportResponse, type TraceModelSegment, type TraceOtherSpan, type TracePosition, type TraceTaskStats, type TraceToolSpan, type UiPrefs, type UnavailableSandboxBackend, type UnsatisfiedPlugin, type UpdateCheckResponse, type UpdateJobPhase, type UpdateJobStatus, type UpdateProfileRequest, type UpdateProfileResponse, type UpdateRunResponse, type UploadLimits, type UsageAgentSeries, type UsageBucket, type UsageEntitySeriesCounts, type UsageErrorCount, type UsageErrorItem, type UsageErrorKind, type UsageErrors, type UsageErrorsClearResponse, type UsageErrorsPage, type UsageGranularity, type UsageGroupBy, type UsageGroupRow, type UsageModelSeries, type UsageModelTotal, type UsageModelTotals, type UsageResponse, type UsageSeriesPoint, type UsageTrendPointInTrace, type UserInfo, type VaultEntryInfo, type VaultEntryUpdate, type VaultResponse, type VaultUpdateRequest, type VersionHistoryDiffResponse, type VersionHistoryResponse, type VersionResponse, type VersionRollbackResponse, type WeChatBindingInfo, type WeChatBindingPutRequest, type WeChatBindingResponse, type WeChatScanPollResponse, type WeChatScanStartResponse, type WeChatScanStatus, type WeChatScanVerifyRequest, type WeChatTestResponse, type WebContribution, type WorkbenchInfo, type WorkbenchRequest, type WorkbenchResponse, type WorkbenchVersion, type WorkspaceFileEntry, type WorkspaceFilesResponse, type WorkspaceSearchHit, type WorkspaceSearchResponse };