@prismshadow/penguin-server 0.2.11 → 0.2.15

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 workflow's handler receives (the HTTP shape, minus the transport). */
+interface WorkflowRequest {
+    method: string;
+    /** Path below the workflow'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 WorkflowResponse {
+    /** 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 workflow 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 workflow, or a renderer it carries. */
+type WorkflowTabRenderer = {
+    iframe: {
+        src: string;
+    };
+} | {
+    builtin: string;
+};
+/**
+ * One tab beside Chat, as the workflow contributed it (`WebModule.sessionTabs`). In a
+ * manifest `renderer.iframe.src` is a path inside the workflow folder, under `ui/`; in a
+ * `WorkflowInfo` it is the URL that file is served from.
+ */
+interface WorkflowTab {
+    id: string;
+    /** Unique within the workflow; the tab's stable name (it appears in the full-page URL). */
+    key: string;
+    title: string;
+    titleZh?: string;
+    renderer: WorkflowTabRenderer;
+}
+interface WorkflowInfo {
+    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 workflow'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: WorkflowTab[];
+    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 WorkflowVersion {
+    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. */
-type SessionSource = "schedule" | "subagent";
+
 interface UserInfo {
     /** Semantic id, i.e. login name: `^[a-z][a-z0-9_-]{1,31}$`, immutable after creation. */
     userId: string;
@@ -38,8 +135,31 @@ interface UserInfo {
     isAdmin: boolean;
     /** Still using the initial password (seeded/set by admin): frontend prompts the user to change it soon. */
     passwordIsInitial: boolean;
+    /**
+     * Nickname the account chose (1-32 characters), shown wherever the id would otherwise be.
+     * Omitted when unset — every account that predates the Profile page starts without one, and
+     * a surface with no value falls back to `userId`.
+     */
+    displayName?: string;
+    /**
+     * Avatar as a `data:image/...;base64,` URL, at most 131072 characters. Omitted when unset,
+     * and a surface with no value draws the letter placeholder instead.
+     */
+    avatar?: string;
     createdAt: string;
 }
+/**
+ * PUT /api/me/profile — a patch, not a replacement: an absent field keeps what is stored,
+ * `null` clears it, a string sets it. A body naming neither field is a 400, since it can only
+ * be a mistake.
+ */
+interface UpdateProfileRequest {
+    displayName?: string | null;
+    avatar?: string | null;
+}
+interface UpdateProfileResponse {
+    user: UserInfo;
+}
 interface AuthLoginRequest {
     userId: string;
     password: string;
@@ -95,6 +215,12 @@ interface MeResponse {
      * just an admin's.
      */
     uploadLimits: UploadLimits;
+    /**
+     * Whether company mode is enabled server-wide (the admin switch in server settings, default
+     * on). Off hides the mode switch in every client and 404s every organization route; the
+     * user's own preference (`UiPrefs.companyMode`) only hides the switch for that user.
+     */
+    companyMode: boolean;
 }
 /**
  * Upload limits as the web app sees them: whole MB, the same unit the admin form uses, so the
@@ -184,6 +310,26 @@ interface ServerSettings {
      * image and the JSON framing), which is why raising it needs no separate setting.
      */
     attachmentTotalMb: number;
+    /**
+     * Company mode master switch (default on). Off stops the organization scheduler (no
+     * calendar event or chat mention fires, nothing is backfilled when it is turned on again),
+     * every `/api/projects/:projectId/organizations` route answers 404, and `GET /api/me`
+     * 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;
@@ -192,6 +338,12 @@ interface ServerSettingsResponse {
 interface ServerSettingsUpdateRequest {
     proxyForApp?: boolean;
     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
@@ -214,6 +366,53 @@ interface ServerSettingsUpdateRequest {
      */
     attachmentTotalMb?: number;
 }
+/**
+ * The endpoints the proxy reachability probe covers. A fixed list: the route takes a provider
+ * id from this set and never a URL, so nothing a caller sends decides what the server fetches.
+ *
+ * GLM is two entries rather than one because it is two hosts: Z.AI serves the global endpoint
+ * and BigModel the mainland one, they are reached over different routes, and a proxy can carry
+ * one and not the other.
+ */
+type ProxyProbeProvider = "openai" | "anthropic" | "gemini" | "deepseek" | "zai" | "bigmodel";
+/**
+ * One probe's verdict. `reachable` means an HTTP answer arrived, whatever its status — a
+ * rejected credential still proves the whole path works. The rest are transport failures,
+ * named so a proxy that swallows connections can be told apart from one whose address does
+ * not resolve: `timeout` (no answer within the probe's window), `dns` (the name never
+ * became an address), `refused` (the connection was refused at the TCP level), `tls` (the
+ * handshake or the certificate failed) and `network` (anything else).
+ */
+type ProxyProbeOutcome = "reachable" | "timeout" | "dns" | "refused" | "tls" | "network";
+/**
+ * One probe target. Served before any probe runs so the page can list what it is about to
+ * request — the URLs are the concrete answer to "what does no API key mean here".
+ */
+interface ProxyProbeTargetDto {
+    provider: ProxyProbeProvider;
+    /** The exact URL a probe requests, unauthenticated. */
+    url: string;
+}
+/** What the probe endpoint would request, without requesting it. */
+interface ProxyProbeTargetsResponse {
+    targets: ProxyProbeTargetDto[];
+}
+/** One provider's probe result. */
+interface ProxyProbeDto extends ProxyProbeTargetDto {
+    outcome: ProxyProbeOutcome;
+    /** Wall time in milliseconds until the answer's headers arrived, or until the attempt failed. */
+    ms: number;
+    /** The HTTP status, present only when `outcome` is `reachable`. */
+    status?: number;
+}
+/**
+ * One probe's answer. The route measures a single target per call: the page asks for all of
+ * them at once and fills each row the moment its own answer lands, so one black-holed host
+ * cannot hold every other result behind its timeout.
+ */
+interface ProxyProbeResponse {
+    probe: ProxyProbeDto;
+}
 /**
  * One draft-screen shortcut: a prompt the user wrote, filed under a name they chose. Clicking it
  * fills the composer exactly like a built-in example does, and sends nothing. Deliberately holds
@@ -226,6 +425,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";
@@ -249,8 +461,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;
 }
@@ -304,7 +537,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 {
@@ -317,6 +550,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;
@@ -326,17 +590,25 @@ 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; falls back to unset (frontend shows modelId). */
+    /**
+     * Display name: explicit TOML field (user-edited) takes priority, then the built-in catalog;
+     * falls back to unset (frontend shows modelId). The empty string is reported as such and
+     * means the user cleared the name on a model the catalog does name — render it as modelId,
+     * and send it back unchanged, since absent would ask for the catalog's name instead.
+     */
     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;
     /**
@@ -349,22 +621,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 {
@@ -379,15 +665,38 @@ 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 the config file clean). */
+    /**
+     * Display name; the server does not persist it when it matches the built-in catalog (keeps
+     * the config file clean). Absent and empty are different requests: absent inherits whatever
+     * the catalog calls the model, the empty string records that the user cleared the name.
+     */
     displayName?: string;
     /**
      * The pair reference this entry was renamed from (provided when either the group or the
@@ -397,7 +706,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;
@@ -406,6 +718,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. */
@@ -418,8 +736,29 @@ 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` puts every built-in row and
+ * built-in group table back to the catalog (facts reset, base URLs and protocols set on models
+ * or groups return to the catalog's, keys and the user's own rows and groups kept, promotions
+ * reset, deleted presets added back).
+ */
+type PresetSyncMode = "add" | "restore";
+interface PresetSyncRequest {
+    mode: PresetSyncMode;
+}
+interface PresetSyncResponse extends ModelsResponse {
+    /** Preset rows added (both modes). */
+    added: number;
+    /** Built-in rows reset to the catalog (`restore`; 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
@@ -429,7 +768,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;
@@ -443,7 +782,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
@@ -506,7 +845,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).
@@ -518,7 +857,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;
 }
@@ -532,7 +876,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;
@@ -540,22 +884,34 @@ interface ModelProtocolProbeDto {
     /** HTTP status, when a response arrived at all. */
     status?: number;
 }
-/** Detection result: probes run sequentially and stop at the first served protocol, so `probes` lists only the ones actually run, in order. */
+/**
+ * Detection result: probes run sequentially over the candidate base URLs derived from the
+ * one that was typed and stop at the first served protocol, so `probes` lists only the
+ * ones actually run, in order.
+ */
 interface ModelProtocolDetectResponse {
-    /** The first protocol the endpoint serves (an AgentHub client type); absent when none of the three matched. */
+    /** 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
+     * path stripped, repeated `/v1` collapsed) and possibly with a trailing `/v1` added or
+     * removed, so `https://host/v1/chat/completions` comes back as `https://host/v1`.
+     * Present only alongside `detected`; callers write it back into their base URL field,
+     * since that is where the protocol is served.
+     */
+    baseUrl?: string;
     probes: ModelProtocolProbeDto[];
 }
 /**
  * Endpoint model listing (POST /api/projects/:p/models/list, owner): given a base URL and
- * the protocol `/detect` reported, returns every model id the endpoint serves (AgentHub's
+ * 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;
@@ -565,7 +921,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;
 }
@@ -583,6 +939,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
@@ -637,6 +1041,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,
@@ -658,6 +1089,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
@@ -708,11 +1144,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 {
@@ -744,15 +1184,35 @@ interface AgentSummary {
     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[];
@@ -900,13 +1360,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;
 }
@@ -942,6 +1409,61 @@ 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;
+    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;
+}
+/** 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. */
@@ -1051,16 +1573,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
@@ -1073,7 +1698,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` or `cli` 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;
     /**
@@ -1099,7 +1735,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` or `cli`) 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
@@ -1111,6 +1753,26 @@ interface SessionInfo {
     tracePath?: string;
     /** Present when the Session has an ENABLED messaging binding: its channel (the sidebar row's per-channel indicator). */
     messagingChannel?: MessagingChannel;
+    /**
+     * 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 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, 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" | "api";
     /**
      * 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
@@ -1130,45 +1792,241 @@ interface SessionBackgroundTasks {
     subagents: number;
 }
 /**
- * Session list category, the sidebar's four-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` or `cli`) 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";
+/** 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;
 }
-/** Server directory browsing (advanced new-Workspace picker): starts from the home directory by default, can navigate up to the root. */
+/**
+ * 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 (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 {
@@ -1194,12 +2052,29 @@ 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; defaults to "web". Informational provenance only — lists
-     * serve every row regardless of client.
+     * Session through the API, "org" when the organization runtime opened it (a desk or a
+     * ticket session — company mode's own, kept out of development mode's lists whether or
+     * 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 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";
+    /**
+     * 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.
      */
-    client?: "web" | "cli";
+    source?: "cli";
 }
 interface SessionCreateResponse {
     session: SessionInfo;
@@ -1227,6 +2102,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
@@ -1235,7 +2115,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;
@@ -1271,7 +2155,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 {
     /**
@@ -1307,9 +2194,26 @@ 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;
 }
 /** 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
@@ -1392,6 +2296,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;
@@ -1593,6 +2523,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
@@ -2086,11 +3030,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;
@@ -2108,6 +3058,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";
@@ -2131,14 +3094,67 @@ 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;
+}
+/**
+ * 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). */
@@ -2181,6 +3197,20 @@ type ScheduleServerEvent =
     agentId: string;
     name: string;
     sessionId: string;
+}
+/** A workflow of the Agent was (re)loaded — its folder changed, a reload was requested, or a version was restored. */
+ | {
+    type: "workflow_updated";
+    projectId: string;
+    agentId: string;
+    workflow: WorkflowInfo;
+}
+/** A workflow's folder is gone — removed from the Web App or deleted on disk. */
+ | {
+    type: "workflow_removed";
+    projectId: string;
+    agentId: string;
+    workflowId: string;
 };
 interface TraceFileInfo {
     /** Trace file index (one file corresponds to one complete model context). */
@@ -2263,7 +3293,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). */
@@ -2415,7 +3448,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;
@@ -2430,6 +3467,58 @@ interface FilesWriteRequest {
      */
     ifVersion?: string;
 }
+/** 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;
+    /** Destination path, relative to the Workspace root. Its parent directory is created when missing. */
+    to: string;
+    /**
+     * Move precondition, read exactly like {@link FilesWriteRequest.ifVersion}: the marker the
+     * caller got from this file's `ETag` on `GET files/content`, which the file must still
+     * carry. It differs on only one point — the marker guards the **source**. The destination
+     * 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` 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
+ * entry, and it can only render identically if it carries the same fields.
+ */
+interface WorkspaceSearchHit {
+    /** Workspace-relative, "/"-separated, with no leading "./" (a tree entry's `name` is only its last segment). */
+    path: string;
+    kind: "dir" | "file";
+    sizeBytes: number;
+    mtime: string;
+}
+interface WorkspaceSearchResponse {
+    /** Shallowest first, then directories before files, then by name — the order the breadth-first walk produced. */
+    hits: WorkspaceSearchHit[];
+    /**
+     * A cap stopped the walk (200 hits, or 20000 directory entries visited), so this is a
+     * partial list. Breadth-first is what makes that degrade well: the hits that survive
+     * truncation are the shallowest ones, not the ones that happened to be enumerated first.
+     */
+    truncated: boolean;
+}
 /** Batch file existence check (message file cards only list files that actually exist). */
 interface FilesStatRequest {
     /** Paths relative to the Workspace root (≤100 items, each ≤512 characters). */
@@ -2518,6 +3607,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[];
@@ -2610,6 +3712,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;
@@ -2629,6 +3742,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. */
@@ -2703,13 +3822,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
@@ -2720,14 +3848,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
@@ -2737,12 +3867,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
@@ -2833,6 +3966,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;
@@ -2882,6 +4032,11 @@ interface BenchmarkCaseScore {
 interface BenchmarkEvaluation {
     /** Evaluation timestamp (ISO 8601). */
     time: string;
+    /**
+     * Agent under test in this round (the `agent_id` field), part of the record's label; `null`
+     * when the record carries none, as a Benchmark evaluates whichever Agents it is pointed at.
+     */
+    agentId: string | null;
     /** Evaluation summary title (a one-line conclusion; shown separately from the body summary; required when generating, tolerated as unset when displaying). */
     summaryTitle?: string;
     /** Evaluation summary body: how the score was derived, what optimizations were made to the Agent this round (required when generating, tolerated as unset when displaying). */
@@ -2902,18 +4057,88 @@ interface BenchmarkEvaluation {
     durationMs: number;
     cases: BenchmarkCaseScore[];
 }
+/**
+ * Whether the Skill that builds a Benchmark is done with it, and how it ended; see
+ * `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
+     * calibrating their difficulty — the Web App masks such a Benchmark; `published` once the
+     * 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 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). */
     evaluations: BenchmarkEvaluation[];
+    /**
+     * Agents this Benchmark has evaluated: the distinct non-null `agentId`s of `evaluations`, in
+     * first-seen order. Empty while nothing has been evaluated — a Benchmark names no Agent of its
+     * own.
+     */
+    agentIds: string[];
 }
 interface BenchmarksResponse {
     benchmarks: BenchmarkSummary[];
@@ -2928,6 +4153,80 @@ interface BenchmarkCaseSummary {
 interface BenchmarkCasesResponse {
     cases: BenchmarkCaseSummary[];
 }
+/**
+ * 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`
+ * (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. */
+    id: string;
+    title: string;
+    description?: string;
+    /** Runs per case for the optimization loop (integer ≥ 1; default 1). */
+    runs?: number;
+    /** At least one case; ids must be unique within the request. */
+    cases: BenchmarkCreateCase[];
+}
+interface BenchmarkCreateCase {
+    /** Case directory name: `CASE-` followed by letters, digits, `_` and `-` (for example `CASE-001-excel-task`). */
+    id: string;
+    /** Written as the statement README's first heading, which the case list reads back as the case title. */
+    title: string;
+    /** Statement body (Markdown), written after that heading; the Target Agent sees only this side. */
+    statement: string;
+    /** Scoring rubric (Markdown, items totalling 100 points), written verbatim as `rubric/README.md`. */
+    rubric: string;
+}
+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, at one commit: what
+     * `penguin benchmark import --origin-url … --origin-ref … --origin-path …` sends for an Agent's
+     * import of a folder link. The copy's origin is then `git` with these fields and the time of the
+     * import, 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;
@@ -2942,7 +4241,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. */
@@ -2958,21 +4257,77 @@ 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[];
     /** 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;
@@ -3006,6 +4361,28 @@ interface PluginInstallRequest {
 interface AgentPluginsInstallResponse {
     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 {
@@ -3041,6 +4418,92 @@ 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;
+    /** 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
@@ -3050,6 +4513,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`
@@ -3124,6 +4598,88 @@ interface DesktopUpdaterCommandMessage {
     type: "desktop-updater-command";
     action: "check" | "download" | "install";
 }
+/** The two languages the Web App has; the shell's tray menu follows whichever is in use. */
+type DesktopTrayLocale = "zh" | "en";
+/** What the shell is currently doing about its tray icon. */
+interface DesktopTrayStatus {
+    /** Whether an icon is shown in the system tray while the app runs. */
+    showTrayIcon: boolean;
+    /**
+     * The language the tray menu is drawn in. Until a page reports one the shell uses the
+     * device language, so this can differ from the Web App's until the first report lands.
+     */
+    locale: DesktopTrayLocale;
+}
+/**
+ * What one PUT asks the shell to change. Every field is optional and a request must carry at
+ * least one: the switch and the language reach this route from different parts of the page.
+ */
+interface DesktopTrayPatch {
+    showTrayIcon?: boolean;
+    locale?: DesktopTrayLocale;
+}
+/**
+ * GET / PUT /api/desktop/tray (desktop-shell sessions only): the tray preference.
+ * `status` is null until the shell's first push lands (a beat after server start); a
+ * client that finds null reads it as on, which is the shell's own default.
+ */
+interface DesktopTrayStatusResponse {
+    status: DesktopTrayStatus | null;
+}
+/** Shell → server push over the utilityProcess message channel. */
+interface DesktopTrayStatusMessage {
+    type: "desktop-tray-status";
+    status: DesktopTrayStatus;
+}
+/**
+ * Server → shell command over the utilityProcess message channel (relayed from PUT
+ * /api/desktop/tray). A patch, not a snapshot: the switch and the language are written by
+ * different parts of the page at different moments, and neither should have to restate the
+ * other's value to change its own.
+ */
+interface DesktopTrayCommandMessage {
+    type: "desktop-tray-command";
+    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
@@ -3214,6 +4770,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
@@ -3238,6 +4804,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
@@ -3253,6 +4832,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
@@ -3260,6 +4845,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
@@ -3282,11 +4941,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";
@@ -3294,30 +4980,1909 @@ 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[];
+}
+/**
+ * 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`.
+ */
+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;
+}
+/**
+ * `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`.
+ */
+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;
+}
+/**
+ * `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.
+ */
+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. */
+    mentionChainLimit: number;
+    budgetWarnRatio: number;
+    budgetPauseRatio: number;
+    createdBy: string;
+    /** The shared workspace root when it is not the organization's own `workspace/` (absolute path). */
+    workspace?: string;
+    /** The model desks and ticket sessions run on when the employee names none; absent = the Project default. */
+    model?: {
+        provider: string;
+        modelId: string;
+    };
+    /** The working language (`language` in `org_config.toml`); absent on an organization written before the field existed, which reads as `en`. */
+    language?: OrgLanguage;
+}
+/** Period spend against the CEO's budget (= the whole organization). */
+interface OrgSpendSummary {
+    /** `yyyy-mm` in the organization's timezone. */
+    period: string;
+    cost: number;
+    budget?: number;
+    /** cost / budget; absent without a budget. */
+    ratio?: number;
+}
+interface OrganizationSummary {
+    projectId: string;
+    orgId: string;
+    name: string;
+    mission: string;
+    status: OrgStatus;
+    employeeCount: number;
+    runningCount: number;
+    pausedCount: number;
+    /** proposed + in_progress + review. */
+    openTickets: number;
+    blockedTickets: number;
+    createdBy: string;
+    spend: OrgSpendSummary;
+    /** Present when `org_config.toml` / `org_chart.yaml` fail validation: the organization is listed but every automatic trigger is held until it is fixed. */
+    invalid?: string;
+}
+interface OrganizationsResponse {
+    organizations: OrganizationSummary[];
+}
+interface OrgEmployeeItem {
+    agentId: string;
+    /**
+     * 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;
+    duties?: string;
+    /** As written in the chart: a sub-directory of the shared workspace (`.` = all of it) or an absolute path. */
+    workspace: string;
+    /** Where that resolves to; absent when the directory does not exist (the entry is then invalid). */
+    resolvedWorkspace?: string;
+    /** Monthly budget in USD for this employee plus all subordinates; absent = unbounded. */
+    budget?: number;
+    model?: {
+        provider: string;
+        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;
+        openedAt: string;
+    };
+    /** Period spend: own sessions, and cumulative (own + every subordinate). */
+    spend: {
+        own: number;
+        cumulative: number;
+        ratio?: number;
+    };
+    /** 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;
+    employees: OrgEmployeeItem[];
+}
+interface OrgCalendarItem {
+    agentId: string;
+    name: string;
+    title?: string;
+    prompt: string;
+    enabled: boolean;
+    startAt: string;
+    period?: string;
+    endAt?: string;
+    status: ScheduleStatus;
+    invalidReason?: string;
+    nextFireAt?: string;
+    lastFiredAt?: string;
+    /** What the most recent evaluation did (absent until the event has been evaluated once). */
+    lastOutcome?: OrgCalendarOutcome;
+    /** The organization or this employee is paused, so due slots are skipped, not fired. */
+    paused: boolean;
+}
+interface OrgCalendarResponse {
+    events: OrgCalendarItem[];
+    invalidFiles: Array<{
+        agentId: string;
+        name: string;
+        error: string;
+    }>;
+}
+/**
+ * One line of a ticket's operation history, kept in the file's frontmatter apart from the
+ * progress prose: what was done, by whom (`agent:<id>` / `user:<id>` — an employee is recognised
+ * from the Agent id its command subprocesses carry, a person otherwise), and when.
+ */
+type OrgTicketHistoryAction = "created" | "assigned" | "moved" | "blocked" | "unblocked" | "progress" | "session_started" | "session_attached" | "edited";
+interface OrgTicketHistoryEntry {
+    at: string;
+    by: string;
+    action: OrgTicketHistoryAction;
+    /** The action's detail: the column moved to, the new owner, the block reason, the session id. */
+    note?: string;
+}
+/**
+ * The ticket id's slug: lowercase letters in hyphen-joined words, no digits (the date prefix
+ * already carries the numbers), chosen for meaning — derived from an ASCII title, proposed by
+ * the Project's model for a title in another language, or passed explicitly.
+ */
+declare const TICKET_SLUG_PATTERN: RegExp;
+interface OrgTicketItem {
+    ticketId: string;
+    title: string;
+    status: OrgTicketStatus;
+    /** The ONE responsible principal (`agent:<id>` / `user:<id>`); who filed it is the history's `created` entry. */
+    owner: string;
+    parent?: string;
+    notify: string[];
+    priority: OrgTicketPriority;
+    due?: string;
+    /** Non-empty = blocked; the ticket stays in its column. */
+    blocked?: string;
+    blockedBy?: string;
+    /** Contributing session ids, in the order they were attached. */
+    sessions: string[];
+    /** Any contributing session has a Task in progress. */
+    running: boolean;
+    /** Period cost of the contributing sessions (a session attached to n tickets counts 1/n here). */
+    cost: number;
+    /** Header/column disagreement or a duplicate id: shown with a danger mark, left where it is. */
+    invalid?: string;
+}
+interface OrgTicketSessionItem {
+    sessionId: string;
+    agentId: string;
+    title?: string;
+    status: SessionStatus;
+    lastActiveAt?: string;
+}
+interface OrgTicketDetail extends OrgTicketItem {
+    goal: string;
+    acceptanceCriteria: string;
+    /** `## Progress` as plain sentences; who wrote one and when is the matching history entry. */
+    progress: string[];
+    result: string;
+    /** The operation history from the frontmatter, oldest first. */
+    history: OrgTicketHistoryEntry[];
+    /** The whole file, for the Markdown view and for clients that prefer to edit it as text. */
+    body: string;
+    children: string[];
+    /** Own cost plus every descendant's along `Parent`. */
+    rolledUpCost: number;
+    sessionItems: OrgTicketSessionItem[];
+}
+interface OrgTicketsResponse {
+    columns: Record<OrgTicketStatus, OrgTicketItem[]>;
+    /** Files that failed to parse (skipped; also recorded as errors). */
+    invalidFiles: Array<{
+        path: string;
+        error: string;
+    }>;
+}
+/**
+ * What a `system` line records, structured: the kind of event and its parameters, so a client
+ * renders the sentence in the reader's language and with the principals' display names instead
+ * of showing the English `text` verbatim. `text` stays the English sentence (the CLI, older
+ * clients and the file itself read it); `notice` is the same fact for a client that can do better.
+ */
+type OrgChannelNoticeKind = "employee_joined" | "employee_left" | "channel_created" | "channel_archived" | "channel_unarchived" | "channel_joined" | "channel_invited" | "channel_left" | "channel_removed" | "budget_warned" | "budget_paused"
+/**
+ * Legacy, read-only: ticket changes no longer write into a channel — the board is read from
+ * the board and the overview's inbox. These three kinds stay so the lines already in an
+ * organization's message files keep rendering; nothing writes them any more.
+ */
+ | "ticket_blocked" | "ticket_done" | "ticket_rejected";
+/**
+ * The parameters each kind carries, all strings: principals as `agent:<id>` / `user:<id>`
+ * (`agent`, `principal`, `by`, `reportsTo`), a ticket as `ticket` + `title`, a budget event as
+ * `agent`, `period`, `percent`, `cost`, `budget`.
+ */
+interface OrgChannelNotice {
+    kind: OrgChannelNoticeKind;
+    params: Record<string, string>;
+}
+interface OrgChannelMessage {
+    id: string;
+    /** ISO 8601 UTC. */
+    time: string;
+    /** `agent:<id>` / `user:<id>` / `system`. */
+    sender: string;
+    hop: number;
+    text: string;
+    /** Principals mentioned, `all` included. */
+    mentions: string[];
+    refs?: {
+        ticket?: string;
+        session?: string;
+        replyTo?: string;
+    };
+    /** Present on `system` lines the server wrote with a structured notice; absent on lines from before the field existed. */
+    notice?: OrgChannelNotice;
+}
+/**
+ * One channel as the API reports it. The all-hands channel (`default_channel`,
+ * `everyone: true`) exists for as long as the organization does and every employee and
+ * Project member is in it; every other channel carries the membership its members edit.
+ */
+interface OrgChannelItem {
+    channelId: string;
+    /** As stored; the UI renders the all-hands channel's label itself. */
+    name: string;
+    /** "" when unset. */
+    purpose: string;
+    /** True only for `default_channel`: membership is implicit. */
+    everyone: boolean;
+    /** An archived channel is read-only and folded away. */
+    archived: boolean;
+    /** `user:<id>` / `agent:<id>` / `system`. */
+    createdBy: string;
+    /** ISO 8601 UTC. */
+    createdAt: string;
+    /** Implicit membership counted for the all-hands channel. */
+    memberCount: number;
+    /** Whether the caller (person or employee) is a member. */
+    isMember: boolean;
+    /** People only; 0 for an employee caller. */
+    unread: number;
+    /** People only; 0 for an employee caller. */
+    mentionsMe: number;
+    lastMessageAt: string | null;
+}
+interface OrgChannelMember {
+    /** `agent:<id>` or `user:<id>`. */
+    principal: string;
+    name: string;
+    kind: "agent" | "user";
+}
+interface OrgChannelDetail extends OrgChannelItem {
+    /** The all-hands channel resolves to every employee plus every Project member. */
+    members: OrgChannelMember[];
+}
+interface OrgChannelsResponse {
+    /** `default_channel` first, then by name. */
+    channels: OrgChannelItem[];
+}
+interface OrgChannelCreateRequest {
+    channelId: string;
+    name?: string;
+    purpose?: string;
+}
+interface OrgChannelPatchRequest {
+    name?: string;
+    purpose?: string;
+    archived?: boolean;
+}
+interface OrgChannelMemberRequest {
+    /** `agent:<id>` (an employee) or `user:<id>` (a Project member). */
+    principal: string;
+}
+interface OrgChannelMessagesResponse {
+    /** The channel served. */
+    channelId: string;
+    /** The day file served (`yyyy-mm-dd` in the organization's timezone). */
+    date: string;
+    /** The days this channel has a file for, newest first, for paging back. */
+    days: string[];
+    messages: OrgChannelMessage[];
+    /** Messages of this channel after the caller's read cursor in it, across the recent days. */
+    unread: number;
+    /** Of those, the ones that mention the caller (or all). */
+    mentionsMe: number;
+    lastReadId?: string;
+}
+interface OrgBudgetAlert {
+    agentId: string;
+    period: string;
+    warnedAt?: string;
+    pausedAt?: string;
+}
+interface OrgFinanceEmployee {
+    agentId: string;
+    name: string;
+    title: string;
+    reportsTo: string | null;
+    own: number;
+    cumulative: number;
+    budget?: number;
+    ratio?: number;
+    warned: boolean;
+    paused: boolean;
+}
+interface OrgFinanceTicket {
+    ticketId: string;
+    title: string;
+    status: OrgTicketStatus;
+    parent?: string;
+    cost: number;
+    rolledUp: number;
+}
+interface OrgFinanceResponse {
+    period: string;
+    currency: "USD";
+    employees: OrgFinanceEmployee[];
+    tickets: OrgFinanceTicket[];
+    /** Daily cost of the organization's sessions over the period. */
+    daily: Array<{
+        date: string;
+        cost: number;
+    }>;
+    alerts: OrgBudgetAlert[];
+    total: number;
+    /** Some usage ran on a model without pricing: tokens were counted, cost is a lower bound. */
+    unpriced: boolean;
+}
+interface OrgDeskItem {
+    agentId: string;
+    name: string;
+    sessionId: string;
+    title?: string;
+    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;
+        title: string;
+        status: OrgTicketStatus;
+        sessions: OrgTicketSessionItem[];
+    }>;
+}
+interface OrgDeskResponse {
+    agentId: string;
+    sessionId: string;
+    workspace: string;
+    openedAt: string;
+    /** True when this call created the desk session. */
+    created: boolean;
+}
+interface OrganizationDetail extends OrganizationSummary {
+    settings: OrganizationSettings;
+    board: Record<OrgTicketStatus, number>;
+    /** Today's calendar events (organization timezone) with their outcomes. */
+    today: OrgCalendarItem[];
+    pending: {
+        /** Unread messages mentioning the caller (or all). */
+        mentions: number;
+        reviewTickets: OrgTicketItem[];
+        blockedByMe: OrgTicketItem[];
+    };
+    /** The last messages of the all-hands channel. */
+    recentMessages: OrgChannelMessage[];
+    alerts: OrgBudgetAlert[];
+    /** What the overview's inbox lists; absent only from a server older than the field. */
+    inbox?: OrgInbox;
+    /** The CEO's desk session once opened (creation opens it). */
+    ceoDeskSessionId?: string;
+}
+/**
+ * The overview's inbox: the three things a person is waited on or told about — messages
+ * that name them (or `@all`) in the all-hands channel, the tickets that are blocked (all of
+ * them, whoever they wait on), and the tickets closed as done this period. Newest first in
+ * each list; each capped at a page.
+ */
+interface OrgInbox {
+    mentions: OrgChannelMessage[];
+    blockedTickets: OrgTicketItem[];
+    doneTickets: Array<OrgTicketItem & {
+        closedAt?: string;
+    }>;
+}
+interface OrganizationCreateRequest {
+    /** Semantic id, unique within the Project; also the directory name. */
+    orgId: string;
+    name?: string;
+    mission: string;
+    timezone?: string;
+    /** An existing absolute directory to use as the shared workspace; default = the organization's own `workspace/`. */
+    workspace?: string;
+    /** The model for desks and ticket sessions (a configured pair); default = the Project default. */
+    model?: {
+        provider: string;
+        modelId: string;
+    };
+    /**
+     * The CEO's monthly budget in USD, written as the `budget` of its `org_chart.yaml` entry.
+     * Budgets are compared on the cumulative line, so the CEO's is the whole company's.
+     * Omitted = 100; 0 is a real (zero) budget, not "unbounded" — only clearing the field
+     * later (`PATCH …/employees/:agentId` with `budget: null`) leaves the CEO unbounded.
+     */
+    ceoBudget?: number;
+    /** The working language; omitted = detected from the mission. */
+    language?: OrgLanguage;
+}
+interface OrganizationPatchRequest {
+    name?: string;
+    mission?: string;
+    status?: OrgStatus;
+    approvalMode?: OrgApprovalMode;
+    timezone?: string;
+    mentionChainLimit?: number;
+    budgetWarnRatio?: number;
+    budgetPauseRatio?: number;
+    /** null returns to the organization's own `workspace/`. */
+    workspace?: string | null;
+    /** null returns to the Project default. */
+    model?: {
+        provider: string;
+        modelId: string;
+    } | null;
+    language?: OrgLanguage;
+}
+/**
+ * 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 / description, when nothing else names the thing). */
+    name: string;
+    /** 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[];
+}
+/**
+ * Why a proposal fell all the way through to a placeholder — what the client tells the user to
+ * explain the id it was just handed. `no_default_model`: the Project has no default model to
+ * ask. `model_failed`: it was asked and the request failed (no credential, a rejection, a
+ * timeout). `unusable_answer`: it answered twice and neither answer yielded an id.
+ * `no_ascii`: no model was consulted at all and the name carries no ASCII to transliterate.
+ */
+type SemanticIdSuggestReason = "no_default_model" | "model_failed" | "unusable_answer" | "no_ascii";
+interface SemanticIdSuggestResponse {
+    /**
+     * 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";
+    /** Present only with `source: "placeholder"`: why the two real paths produced nothing. */
+    reason?: SemanticIdSuggestReason;
+}
+interface OrgHireRequest {
+    /** Employ an existing Agent … */
+    agentId?: string;
+    /** … or create one (the two are exclusive). Plugins default to agent-company + agent-development. */
+    newAgent?: {
+        agentId: string;
+        name?: string;
+        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;
+    budget?: number;
+    duties?: string;
+    model?: {
+        provider: string;
+        modelId: string;
+    };
+}
+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;
+    /** null clears the budget. */
+    budget?: number | null;
+    duties?: string;
+    /** null clears the model (back to the Project default). */
+    model?: {
+        provider: string;
+        modelId: string;
+    } | null;
+}
+interface OrgCalendarUpsertRequest {
+    /** POST only: the employee the event belongs to. */
+    agentId?: string;
+    /** POST only: the file name. */
+    name?: string;
+    title?: string;
+    prompt: string;
+    enabled: boolean;
+    startAt: string;
+    period?: string;
+    endAt?: string;
+}
+/**
+ * What a calendar write answers: the stored event, plus advisory `warnings` — one line each —
+ * about the rota: another employee's recurring event on the same start minute, or the same
+ * employee already holding a recurring event (desks that fire together compete for the same
+ * budget minute and the same tickets). The write succeeds regardless; the CLI prints the
+ * lines so the scheduling employee can stagger.
+ */
+interface OrgCalendarWriteResponse extends OrgCalendarItem {
+    warnings?: string[];
+}
+interface OrgTicketCreateRequest {
+    title: string;
+    /** Overrides the slug derived from the title; lowercase English words joined by hyphens. */
+    slug?: string;
+    goal?: string;
+    acceptanceCriteria?: string;
+    /** The whole Markdown body instead of goal + acceptanceCriteria (the frontmatter is still generated). */
+    body?: string;
+    /**
+     * The responsible principal: an employee's `agent:<id>` (or bare Agent id) or a member's
+     * `user:<id>`. Default = the caller — the session's employee inside a desk or ticket
+     * session, else the token's or cookie's user.
+     */
+    owner?: string;
+    parent?: string;
+    notify?: string[];
+    priority?: OrgTicketPriority;
+    due?: string;
+}
+interface OrgTicketUpdateRequest {
+    title?: string;
+    /** The new responsible principal; never null — a ticket always has an owner. */
+    owner?: string;
+    parent?: string | null;
+    notify?: string[];
+    priority?: OrgTicketPriority;
+    due?: string | null;
+    goal?: string;
+    acceptanceCriteria?: string;
+    result?: string;
+}
+interface OrgTicketMoveRequest {
+    status: OrgTicketStatus;
+    /** Required when moving into rejected; recorded under Result. */
+    reason?: string;
+}
+interface OrgTicketBlockRequest {
+    reason: string;
+    /** A ticket id or a principal. */
+    by?: string;
+}
+interface OrgTicketProgressRequest {
+    text: string;
+    /**
+     * The calling session (CLI: PENGUIN_SESSION_ID); the session is booked as a contributing
+     * session and the history entry is attributed to its employee. Honoured only for a request
+     * carrying the local API token — the control environment's credential; a signed-in user's
+     * write is attributed to the user.
+     */
+    sessionId?: string;
+    /**
+     * The calling employee's Agent id (CLI: PENGUIN_AGENT_ID from the control environment), the
+     * identity a write is recorded under; it wins over the session's employee, is honoured only
+     * with the local API token, like sessionId, and is ignored — the write falls back to the
+     * session's employee, then to the person — when it names no employee.
+     */
+    agentId?: string;
+}
+interface OrgTicketStartRequest {
+    /** The employee the ticket session runs as (CLI: PENGUIN_AGENT_ID); defaults to the ticket owner. */
+    agentId?: string;
+    message?: string;
+    /** Another directory inside the shared workspace; defaults to the employee's desk workspace. */
+    workspace?: string;
+}
+interface OrgTicketStartResponse {
+    sessionId: string;
+}
+interface OrgTicketAttachRequest {
+    sessionId: string;
+}
+interface OrgChannelMessageSendRequest {
+    text: string;
+    refs?: {
+        ticket?: string;
+        session?: string;
+        replyTo?: string;
+    };
+    /**
+     * The calling session (CLI: PENGUIN_SESSION_ID): the message is sent as its Agent and
+     * inherits its hop. Honoured only for a request carrying the local API token — the control
+     * environment's credential; a signed-in user's message is sent as the user, at hop 0.
+     */
+    sessionId?: string;
+}
+interface OrgChannelReadRequest {
+    /** Mark everything up to this message id as read. */
+    upTo: string;
+}
+/** The handbook index (`handbook/README.md`), the file every work run reads first. */
+interface OrgHandbookResponse {
+    content: string;
+}
+/** One file of the organization handbook (`handbook/`, the company's knowledge base); `path` is relative to that directory. */
+interface OrgHandbookFile {
+    path: string;
+    size: number;
+    updatedAt: string;
+}
+interface OrgHandbookFilesResponse {
+    /** The index first, then the other documents by path. */
+    files: OrgHandbookFile[];
+}
+interface OrgHandbookFileResponse {
+    path: string;
+    content: string;
+}
+interface OrgHandbookFileWriteRequest {
+    content: string;
+}
+/** Company-mode notifications on the user-level event stream (best effort; the query routes carry the durable state). */
+type CompanyServerEvent = 
+/** A work run (desk session) or ticket session was started by the organization scheduler or a ticket start. */
+{
+    type: "org_run";
+    projectId: string;
+    orgId: string;
+    agentId: string;
+    sessionId: string;
+    kind: OrgTriggerKind;
+}
+/** A new channel message (mentions included, so the client can tell whether it is addressed). */
+ | {
+    type: "org_channel";
+    projectId: string;
+    orgId: string;
+    channelId: string;
+    message: OrgChannelMessage;
+}
+/** A ticket's status, owner, blocked state or contributing sessions changed. */
+ | {
+    type: "org_ticket";
+    projectId: string;
+    orgId: string;
+    ticketId: string;
+    change: string;
+}
+/** Budget warning, pause or resume for an employee. */
+ | {
+    type: "org_budget";
+    projectId: string;
+    orgId: string;
+    agentId: string;
+    state: "warned" | "paused" | "resumed";
+    ratio: number;
+};
+/** How the web app renders a contributed surface: a name from its own registry, or an iframe. */
+type RendererRef = {
+    builtin: string;
+} | {
+    iframe: {
+        src: string;
+        namespace: string;
+    };
+};
+/** One contribution to a web slot: its id, the contributing module, and the slot's data. */
+interface WebContribution {
+    id: string;
+    from: string;
+    [key: string]: unknown;
+}
+interface ContributionsResponse {
+    pages: WebContribution[];
+    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;
+    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 {
+    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";
+    requestId: string;
+    url: string;
+    activate: boolean;
+    openerTabId?: number;
+    sessionId?: string;
+} | {
+    type: "builtin_browser_close";
+    tabId: number;
+} | {
+    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[];
+}
+/** Reply: `{}`. */
+ | {
+    op: "clear-data";
+    storages: ("cookies" | "cache" | "storage")[];
+}
+/**
+ * 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, AdminUserCreateRequest, AdminUserCreateResponse, AdminUsersResponse, AgentCompactionConfigDto, AgentConfigDto, AgentConfigResponse, AgentConfigUpdateRequest, AgentCreateRequest, AgentCreateResponse, AgentHooksConfigDto, AgentHooksResponse, AgentImportRequest, AgentImportResponse, AgentKernelUpdateResponse, AgentMemoryConfigDto, AgentModelConfigDto, AgentPluginsInstallResponse, AgentSchedulesConfigDto, AgentSkillsConfigDto, AgentSkillsResponse, AgentSummary, AgentTraceDateGroup, AgentTraceFileRef, AgentTraceSessionEntry, AgentTraceSessionFile, AgentTraceSessionGroup, AgentTracesResponse, AgentVaultConfigDto, AgentsResponse, ApprovalDecisionRequest, ApprovalMode, AuthLoginRequest, AuthResponse, BenchmarkCaseScore, BenchmarkCaseSummary, BenchmarkCasesResponse, BenchmarkEvaluation, BenchmarkRunScore, BenchmarkSummary, BenchmarksResponse, CaseMaterial, ChatDefaultsDto, CommandPolicyDto, CommandPolicyRuleDto, ContextFileShare, ContextToolShare, CredentialInfo, DefaultModelResponse, DefaultModelUpdateRequest, DesktopUpdateStatus, DesktopUpdateStatusResponse, DesktopUpdaterCommandMessage, DesktopUpdaterStatusMessage, DirEntryInfo, DirListResponse, DirectorySkillItem, DirectorySkillsResponse, DraftShortcut, EndpointModelListRequest, EndpointModelListResponse, ErrorBody, FeishuBindingInfo, FeishuBindingPutRequest, FeishuBindingResponse, FeishuTestRequest, FeishuTestResponse, FilesStatRequest, FilesStatResponse, FilesWriteRequest, GoalResponse, GoalServerEvent, GoalStateView, HistoryMessage, HookArchiveInstallRequest, HookItem, InstallResponse, MachineInfo, MachineJob, MachineServerStatus, MachinesResponse, McpServerTestResponse, MeResponse, MemberAddRequest, MemberAddResponse, MemberInfo, MembersResponse, MemoryFileInfo, MemoryFileResponse, MemoryFilesResponse, MemoryImportMode, MemoryImportRequest, MemoryImportResponse, MemoryOverviewResponse, MemoryScopeExport, MemoryScopeInfo, MemoryTransferFile, MessagesLiveTail, MessagesPageInfo, MessagesResponse, MessagingBindingCommon, MessagingBindingInfo, MessagingBindingStateRequest, MessagingBindingsResponse, MessagingChannel, MessagingChannelState, MessagingDeliveryError, MessagingDeliveryPatch, MessagingRuntimeState, MessagingRuntimeStatus, MessagingTestMessageResponse, ModelInfo, ModelOAuthCodeRequest, ModelOAuthCodeResponse, ModelOAuthErrorCode, ModelOAuthMode, ModelOAuthStartRequest, ModelOAuthStartResponse, ModelOAuthStatusResponse, ModelPricingDto, ModelProtocolDetectRequest, ModelProtocolDetectResponse, ModelProtocolProbeDto, ModelRefDto, ModelTestRequest, ModelTestResponse, ModelUpdateEntry, ModelVisionDetectRequest, ModelVisionDetectResponse, ModelVisionOutcome, ModelsResponse, ModelsUpdateRequest, PasswordChangeRequest, PendingFollowUpInfo, PendingSteeringInfo, PluginFilesResponse, PluginGroupItem, PluginInstallRequest, PluginItem, PluginLibraryResponse, PluginUpdateRef, PrefsResponse, ProjectCreateRequest, ProjectCreateResponse, ProjectRole, ProjectSummary, ProjectUpdateRequest, ProjectUpdateResponse, ProjectsResponse, ProtocolProbeOutcome, QQBindingInfo, QQBindingPutRequest, QQBindingResponse, QQScanPollResponse, QQScanStartResponse, QQTestRequest, QQTestResponse, RecalledMessageResponse, RequestSpan, RestartResponse, RetryNowResponse, ScheduleItem, ScheduleServerEvent, ScheduleStatus, ScheduleUpsertRequest, SchedulesResponse, ServerEvent, ServerSettings, ServerSettingsResponse, ServerSettingsUpdateRequest, SessionBackgroundTasks, SessionCategory, SessionCategoryCounts, SessionContextParts, SessionContextResponse, SessionCreateRequest, SessionCreateResponse, SessionForkRequest, SessionForkResponse, SessionInfo, SessionPatchRequest, SessionProcessInfo, SessionProcessesResponse, SessionResponse, SessionSource, SessionStatus, SessionTracesResponse, SessionsResponse, SkillArchiveInstallRequest, SkillMetadataItem, SteerRequest, SubagentMessageResponse, SubagentRuntimeInfo, TaskCreateRequest, TaskCreateResponse, TaskInputPart, TelegramBindingInfo, TelegramBindingPutRequest, TelegramBindingResponse, TelegramTestRequest, TelegramTestResponse, ToolCallSpan, TraceAnalysisResponse, TraceEventsResponse, TraceFileInfo, TraceImportRequest, TraceImportResponse, TraceModelSegment, TraceOtherSpan, TracePosition, TraceTaskStats, TraceToolSpan, UiPrefs, UpdateCheckResponse, UpdateJobPhase, UpdateJobStatus, UpdateRunResponse, UploadLimits, UsageAgentSeries, UsageBucket, UsageEntitySeriesCounts, UsageErrorCount, UsageErrorItem, UsageErrorKind, UsageErrors, UsageErrorsClearResponse, UsageErrorsPage, UsageGranularity, UsageGroupBy, UsageGroupRow, UsageModelSeries, UsageModelTotal, UsageModelTotals, UsageResponse, UsageSeriesPoint, UsageTrendPointInTrace, UserInfo, VaultEntryInfo, VaultEntryUpdate, VaultResponse, VaultUpdateRequest, VersionResponse, WeChatBindingInfo, WeChatBindingPutRequest, WeChatBindingResponse, WeChatScanPollResponse, WeChatScanStartResponse, WeChatScanStatus, WeChatScanVerifyRequest, WeChatTestResponse, WorkspaceFileEntry, WorkspaceFilesResponse };
+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 WorkflowInfo, type WorkflowRequest, type WorkflowResponse, type WorkflowVersion, type WorkspaceFileEntry, type WorkspaceFilesResponse, type WorkspaceSearchHit, type WorkspaceSearchResponse };