@prismshadow/penguin-server 0.2.8 → 0.2.10

package/dist/api/types.d.ts

@@ -370,7 +370,7 @@ interface ModelInfo {
 interface ModelsResponse {
     /** Paired reference to the default Model. */
     defaultModel?: ModelRefDto;
-    /** Vision model used as a proxy reader for read_image (describes images when the session model has vision=false). */
+    /** Vision model used as a proxy reader for read_file (describes images when the session model has vision=false). */
     visionModel?: ModelRefDto;
     /**
      * When the Project's model/credential config last changed (ISO; the config file's mtime,
@@ -416,7 +416,7 @@ interface ModelUpdateEntry {
 interface ModelsUpdateRequest {
     /** Must be included in models (matched by paired reference). */
     defaultModel?: ModelRefDto;
-    /** Vision model used as a proxy reader for read_image: must be included in models and not annotated vision=false; omitted keeps the existing value. */
+    /** 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;
     models: ModelUpdateEntry[];
 }
@@ -615,6 +615,13 @@ interface ModelOAuthStatusResponse {
     status: "pending" | "done" | "error";
     /** The provider group the flow mints a key for. */
     provider: string;
+    /**
+     * How many models the minted key was written to — set on the `done` answer, the way
+     * {@link ModelOAuthCodeResponse} sets it on a redemption. The dialog reports this number, so
+     * it has to be the server's own: the caller's model table can outlive a rejected save and
+     * would otherwise name a count the server never wrote.
+     */
+    applied?: number;
     error?: ModelOAuthErrorCode;
 }
 /**
@@ -701,12 +708,12 @@ interface VaultEntryUpdate {
 interface VaultUpdateRequest {
     entries: VaultEntryUpdate[];
 }
-/** One installed Skill the library carries a higher version of (see {@link AgentSummary.skillUpdates}). */
-interface SkillUpdateRef {
-    /** Skill directory name — the identity install / uninstall address it by. */
+/** One installed plugin (a skill or a hook package) the library carries a higher version of (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, i.e. what installing again would bring, not what is on disk. */
-    version: number;
+    /** The LIBRARY's version (`YYYY.MM.DD.N`), i.e. what installing again would bring, not what is on disk. */
+    version: string;
 }
 interface AgentSummary {
     agentId: string;
@@ -733,14 +740,17 @@ interface AgentSummary {
     scheduleCount: number;
     /** Installed Skill count (number of agent_state/skills/<name>/ directories with a SKILL.md). */
     skillCount: number;
-    /**
-     * Installed Skills the built-in library has moved past, each with the library version on
-     * offer — the Skill-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 that are not
-     * in the library (installed from a zip or a picked directory) are never listed: there is no
+    /** Installed hook-package count (number of agent_state/hooks/<name>/ directories with a hooks.json). */
+    hookCount: number;
+    /**
+     * Installed plugins the built-in library has moved past — a skill or a hook package whose
+     * on-disk version is behind the library plugin that ships it — each with the library version
+     * on offer: the plugin-library update gate, riding along on the Agent list so a badge over
+     * that page costs no request of its own. Empty when nothing is behind. Skills the library
+     * does not carry (installed from a zip or a picked directory) are never listed: there is no
      * library version for them to be behind.
      */
-    skillUpdates: SkillUpdateRef[];
+    pluginUpdates: PluginUpdateRef[];
     /** Memory count (topic files summed over the scope directories under agent_state/memory/, independent of the memory switch). */
     memoryCount: number;
 }
@@ -754,11 +764,12 @@ interface AgentCreateRequest {
     name?: string;
     description?: string;
     /**
-     * Library Skill names installed into the new Agent, seeding it at creation. Every name must
-     * exist in the library (404 `unknown_skill` otherwise, before anything is created); omitted or
-     * empty leaves the Agent with no Skills, which is what a plain Agent gets by default.
+     * Library plugin names installed into the new Agent, seeding it at creation — each plugin's
+     * skills and hook package. Every name must exist in the library (404 `unknown_plugin`
+     * otherwise, before anything is created); omitted or empty leaves the Agent with nothing
+     * installed, which is what a plain Agent gets by default.
      */
-    skills?: string[];
+    plugins?: string[];
     /**
      * Skills imported from a directory on disk instead of the library. `skillsDirectory` is the
      * absolute path the user picked and `directorySkills` are the names to install from it, read
@@ -771,7 +782,7 @@ interface AgentCreateRequest {
     /**
      * Base64 of an exported Agent State snapshot package (`.tar.gz`): the new Agent is
      * initialized from the package instead of the default template. Mutually exclusive with
-     * skill seeding (`skills` / `skillsDirectory`) — the package carries its own skills.
+     * seeding (`plugins` / `skillsDirectory`) — the package carries its own skills and hooks.
      * Explicit `name` / `description` override the package's values; absent ones keep them.
      */
     dataBase64?: string;
@@ -833,6 +844,16 @@ interface AgentSchedulesConfigDto {
     /** Whether the stored template carries `{{SCHEDULES}}`; POST …/schedules/template-placeholder inserts it explicitly. */
     templateHasPlaceholder: boolean;
 }
+/**
+ * Hook config, edited on the Hooks tab. One Agent-level switch and no prompt: hook packages
+ * are scripts run at the loop's hook points, not text injected into the context. `enabled`
+ * reports the effective value (a config with no `hooks` section reads as enabled, matching
+ * core).
+ */
+interface AgentHooksConfigDto {
+    /** Whether a Session created from now on runs the installed hook packages (they stay installed either way). */
+    enabled: boolean;
+}
 /** Structured view of system_config.yaml (for the edit form). */
 interface AgentConfigDto {
     name?: string;
@@ -853,6 +874,7 @@ interface AgentConfigDto {
     vault: AgentVaultConfigDto;
     skills: AgentSkillsConfigDto;
     schedules: AgentSchedulesConfigDto;
+    hooks: AgentHooksConfigDto;
     toolsBuiltin: ToolDefinitionConfig[];
     mcpServers: MCPServerConfig[];
 }
@@ -912,6 +934,10 @@ interface AgentConfigUpdateRequest {
             enabled?: boolean;
             prompt?: string;
         };
+        /** The Agent-level hook switch; it has no prompt half. */
+        hooks?: {
+            enabled?: boolean;
+        };
         toolsBuiltin?: ToolDefinitionConfig[];
         mcpServers?: MCPServerConfig[];
     };
@@ -1037,10 +1063,12 @@ interface SessionInfo {
     approvalMode: ApprovalMode;
     /**
      * Thinking level pinned for this Session (set via PATCH; the Web App's in-chat picker).
-     * Unset = never pinned: runs that carry no level of their own fall back to the Agent
-     * config's `model.thinking_level`, so config edits keep taking effect. Once pinned it
-     * survives reloads and applies to every later run of this Session, and an Agent-config
-     * change no longer moves it.
+     * Unset = never pinned: each model context the Session opens reads the Agent config's
+     * `model.thinking_level`, so config edits keep taking effect. Once pinned it survives
+     * reloads and applies from the Session's very next LLM request — the thinking level is
+     * the soft-limited runtime parameter, changeable mid-context at the cost of the
+     * provider's cached context (the picker advises compacting first) — and every later
+     * context opens at it; an Agent-config change no longer moves it.
      */
     thinkingLevel?: ThinkingLevelName;
     /** Short title auto-generated by the model after the first turn; unset until generated (frontend shows "New Chat"). */
@@ -1083,6 +1111,23 @@ interface SessionInfo {
     tracePath?: string;
     /** Present when the Session has an ENABLED messaging binding: its channel (the sidebar row's per-channel indicator). */
     messagingChannel?: MessagingChannel;
+    /**
+     * 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
+     * background subagent sessions mid-round. Read from the runtime's in-memory registries —
+     * no Trace is consulted — and present only while at least one count is non-zero, so a
+     * Session that is not loaded (a resumed entry starts with empty registries) and one with
+     * nothing running both omit it. Changes are pushed as `session_background` on the user
+     * channel; list rows and the single-session GET carry the same field.
+     */
+    backgroundTasks?: SessionBackgroundTasks;
+}
+/** The background-task counts of one Session (see SessionInfo.backgroundTasks). */
+interface SessionBackgroundTasks {
+    /** Background command sessions whose process is still running. */
+    processes: number;
+    /** Background subagent sessions (promoted to a `subagent_id`) currently mid-round. */
+    subagents: number;
 }
 /**
  * Session list category, the sidebar's four-way split applied server-side: archived wins
@@ -1103,6 +1148,13 @@ interface SessionsResponse {
      * 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.
+     */
+    workspaceLatest?: Record<string, string>;
 }
 /** Server directory browsing (advanced new-Workspace picker): starts from the home directory by default, can navigate up to the root. */
 interface DirEntryInfo {
@@ -1177,9 +1229,10 @@ interface SessionPatchRequest {
     approvalMode?: ApprovalMode;
     /**
      * Pin this Session's thinking level (`none | low | medium | high | xhigh | max`, anything else
-     * is a 400). It applies to every later run of the Session that doesn't carry its own
-     * level, and replaces the Agent-config fallback for this Session. There is no unpin:
-     * the picker only offers concrete levels.
+     * is a 400). It replaces the Agent-config fallback for this Session and applies from the
+     * very next LLM request — soft-limited: a mid-context change is allowed, at the cost of
+     * the provider's cached context, which is why the picker advises compacting first. There
+     * is no unpin: the picker only offers concrete levels.
      */
     thinkingLevel?: ThinkingLevelName;
     /** Archive / unarchive (default list hides archived). */
@@ -1243,6 +1296,14 @@ interface MessagesPageInfo {
     prior: {
         subagentTokens: number;
         elapsedMs: number;
+        /**
+         * Model-API time and tool wall time accrued before this window, the breakdown of
+         * `elapsedMs` the chat header shows under it. Seeded together with their total: seeding
+         * one alone would put a full elapsed time beside components covering only the window.
+         * The two may overlap and do not partition `elapsedMs` (see `TraceTaskStats.toolMs`).
+         */
+        apiMs: number;
+        toolMs: number;
         sessionTokens: number;
         contextTokens: number;
     };
@@ -1300,14 +1361,6 @@ type TaskInputPart = {
 };
 interface TaskCreateRequest {
     input: TaskInputPart[];
-    /**
-     * Thinking level for this Task's LLM requests (a per-turn parameter; one of
-     * `none | low | medium | high | xhigh | max`, anything else is a 400). Omitted = falls back to
-     * the Session's pinned level (`SessionInfo.thinkingLevel`) and, when that is unset too,
-     * to the Agent config's `model.thinking_level`. A queued follow-up (`queueIfBusy`) keeps
-     * its level and applies it when it auto-starts.
-     */
-    thinkingLevel?: ThinkingLevelName;
     /**
      * Queue instead of 409 when a Task/compaction is already in progress: the input is held
      * server-side and auto-starts as an ordinary next task once the session returns to idle
@@ -1317,14 +1370,16 @@ interface TaskCreateRequest {
     /**
      * Present = goal mode: the input's text becomes the objective (leading `[use_skills]`
      * blocks and the like are stripped from the recorded objective; the round-1 message keeps
-     * them) and the server loops the Session until the goal reaches a terminal state.
-     * `budget` is the token budget (uncached input + output); omitted or -1 = unlimited.
+     * them) and the Session's installed `goal` hook package drives round after round until the
+     * goal reaches a terminal state. `budget` is the token budget (uncached input + output);
+     * omitted or -1 = unlimited. Requires the goal plugin installed on the Agent — 409
+     * `goal_plugin_not_installed` otherwise.
      */
     goal?: {
         budget?: number;
     };
 }
-/** Goal-mode run state (from goal_state; the chat page's banner restores from the latest row). */
+/** Goal-mode run state, read from the Session's GOAL.json — the goal plugin's file (the chat page's banner restores from it; a live status on an idle Session reads as `aborted`). */
 interface GoalStateView {
     objective: string;
     status: "active" | "complete" | "blocked" | "budget_limited" | "aborted";
@@ -1332,7 +1387,6 @@ interface GoalStateView {
     budget: number;
     used: number;
     rounds: number;
-    updatedAt: string;
 }
 interface GoalResponse {
     /** The Session's most recent goal run; null if it never ran one. */
@@ -1448,8 +1502,6 @@ interface RecalledMessageResponse {
         fileName: string;
         dataUrl: string;
     }[];
-    /** Follow-up recall only: the per-turn thinking level the entry was queued with, when one was. */
-    thinkingLevel?: ThinkingLevelName;
 }
 interface ApprovalDecisionRequest {
     decision: "allow" | "deny";
@@ -1483,7 +1535,7 @@ interface SessionProcessesResponse {
     processes: SessionProcessInfo[];
 }
 /** Messaging channels a Session can bind to. */
-type MessagingChannel = "feishu" | "telegram" | "qq";
+type MessagingChannel = "feishu" | "telegram" | "qq" | "wechat";
 /** Event-connection runtime state of one binding (kept in memory, not persisted). */
 type MessagingRuntimeState = "disconnected" | "connecting" | "connected" | "error";
 /**
@@ -1542,18 +1594,24 @@ interface MessagingRuntimeStatus {
         detail: string;
     };
 }
-/** The stored Feishu config, secret masked (plaintext never leaves the server). */
-interface FeishuBindingInfo {
-    channel: "feishu";
+/**
+ * What a messaging binding carries whatever channel it is: the connection intent, the three
+ * delivery preferences, whether a chat is known, and the row's identity and timestamps.
+ *
+ * Split out because this is the half that grows. Three delivery preferences arrived in one
+ * release, and each would otherwise have been written into three interfaces — the credential
+ * slice is the only thing a channel genuinely differs in, and it is what stays per-channel.
+ *
+ * `channel` is NOT here: a discriminated union discriminates on a literal the member itself
+ * declares, so each interface keeps its own.
+ *
+ * A channel may RE-DECLARE a field below when it has more to say about it — QQ does, for all
+ * three preferences, because the platform's passive-reply budget and its expiring window
+ * change what setting one costs there. The re-declared type must be identical, which the
+ * compiler enforces, so the redeclaration can only add documentation and never a contract.
+ */
+interface MessagingBindingCommon {
     sessionId: string;
-    appId: string;
-    /**
-     * Masked app secret (site-wide mask rule: `***`, or `first4…last4` for long values);
-     * absent when no secret is stored (never entered, or cleared) — the binding cannot be
-     * enabled until one is saved.
-     */
-    appSecretMasked?: string;
-    baseDomain: string;
     /** Connection INTENT (the state toggle's value); new bindings start disabled, and at most one of a Session's channels is enabled. */
     enabled: boolean;
     /**
@@ -1571,23 +1629,35 @@ interface FeishuBindingInfo {
     /**
      * Render a relayed reply's Markdown in this channel's own markup instead of sending its
      * characters as written. ON by default. Each channel shows what it can — Telegram has no
-     * headings, lists or tables, QQ has no code or tables, Feishu has all of them — and a
+     * headings, lists or tables, QQ has no code or tables, Feishu has all of them, and WeChat
+     * reads Markdown itself so the render is a subtraction rather than a translation — and a
      * rendering the channel refuses falls back to the plain source, so this can cost
      * formatting and never a message.
      */
     renderMarkdown: boolean;
     /**
-     * Whether an inbound Feishu chat is known (the bot has been messaged at least once).
-     * Replies and test messages target that chat; until it exists nothing can be sent.
+     * Whether an inbound chat is known (the bot has been messaged at least once). Replies and
+     * test messages target that chat; until it exists nothing can be sent.
      */
     lastChatKnown: boolean;
     createdAt: string;
     updatedAt: string;
 }
+/** The stored Feishu config, secret masked (plaintext never leaves the server). */
+interface FeishuBindingInfo extends MessagingBindingCommon {
+    channel: "feishu";
+    appId: string;
+    /**
+     * Masked app secret (site-wide mask rule: `***`, or `first4…last4` for long values);
+     * absent when no secret is stored (never entered, or cleared) — the binding cannot be
+     * enabled until one is saved.
+     */
+    appSecretMasked?: string;
+    baseDomain: string;
+}
 /** The stored Telegram config, token masked (plaintext never leaves the server). */
-interface TelegramBindingInfo {
+interface TelegramBindingInfo extends MessagingBindingCommon {
     channel: "telegram";
-    sessionId: string;
     /** The numeric bot id (the token's half before the colon) — the channel-scoped account identity, never secret. */
     botId: string;
     /**
@@ -1596,40 +1666,15 @@ interface TelegramBindingInfo {
      * is saved.
      */
     botTokenMasked?: string;
-    /** Connection INTENT (the state toggle's value); new bindings start disabled, and at most one of a Session's channels is enabled. */
-    enabled: boolean;
-    /**
-     * Send each non-blank line of a relayed assistant reply as its own message instead of one
-     * message per reply. Off by default; off is the original one-message-per-reply behaviour.
-     */
-    linePerMessage: boolean;
-    /**
-     * Relay only the LAST completed assistant message of a run, delivered when the run ends,
-     * instead of mirroring each completed message as it completes. Off by default; off is the
-     * original every-message behaviour. Independent of `linePerMessage`, which then applies to
-     * that one final message. The approval notice is not a reply and is unaffected.
-     */
-    finalReplyOnly: boolean;
-    /**
-     * Render a relayed reply's Markdown in this channel's own markup instead of sending its
-     * characters as written. ON by default. Each channel shows what it can — Telegram has no
-     * headings, lists or tables, QQ has no code or tables, Feishu has all of them — and a
-     * rendering the channel refuses falls back to the plain source, so this can cost
-     * formatting and never a message.
-     */
-    renderMarkdown: boolean;
-    /**
-     * Whether an inbound Telegram chat is known (the bot has been messaged at least once).
-     * Replies and test messages target that chat; until it exists nothing can be sent.
-     */
-    lastChatKnown: boolean;
-    createdAt: string;
-    updatedAt: string;
 }
-/** The stored QQ config, secret masked (plaintext never leaves the server). */
-interface QQBindingInfo {
+/**
+ * The stored QQ config, secret masked (plaintext never leaves the server).
+ *
+ * The three preference fields are re-declared unchanged: every one of them costs something
+ * different here, and the platform's reply budget is what a reader setting one needs to know.
+ */
+interface QQBindingInfo extends MessagingBindingCommon {
     channel: "qq";
-    sessionId: string;
     /** The bot's App ID — the channel-scoped account identity, never secret. */
     appId: string;
     /**
@@ -1638,8 +1683,6 @@ interface QQBindingInfo {
      * enabled until one is saved.
      */
     appSecretMasked?: string;
-    /** Connection INTENT (the state toggle's value); new bindings start disabled, and at most one of a Session's channels is enabled. */
-    enabled: boolean;
     /**
      * Send each non-blank line of a relayed assistant reply as its own message instead of one
      * message per reply. Off by default. On QQ the split is additionally capped at the
@@ -1648,10 +1691,8 @@ interface QQBindingInfo {
      */
     linePerMessage: boolean;
     /**
-     * Relay only the LAST completed assistant message of a run, delivered when the run ends,
-     * instead of mirroring each completed message as it completes. Off by default; off is the
-     * original every-message behaviour. Independent of `linePerMessage`, which then applies to
-     * that one final message. The approval notice is not a reply and is unaffected.
+     * Relay only the LAST completed assistant message of a run, delivered when the run ends.
+     * Off by default.
      *
      * On QQ it cuts both ways, which is worth knowing before setting it here. It spends the
      * least of the platform's passive-reply budget a run can spend — one message, where an
@@ -1662,25 +1703,41 @@ interface QQBindingInfo {
      */
     finalReplyOnly: boolean;
     /**
-     * Render a relayed reply's Markdown in this channel's own markup instead of sending its
-     * characters as written. ON by default. QQ's own subset is the widest for prose and the
-     * narrowest for code: headings, lists, blockquotes and rules render, while inline code,
-     * fenced code and tables have no syntax at all here — a code block arrives as plain
-     * escaped lines. A rendering the platform refuses falls back to the plain source, at the
-     * cost of one more slot from the passive-reply budget.
+     * Render a relayed reply's Markdown in this channel's own markup. ON by default. QQ's own
+     * subset is the widest for prose and the narrowest for code: headings, lists, blockquotes
+     * and rules render, while inline code, fenced code and tables have no syntax at all here —
+     * a code block arrives as plain escaped lines. A rendering the platform refuses falls back
+     * to the plain source, at the cost of one more slot from the passive-reply budget.
      */
     renderMarkdown: boolean;
     /**
-     * Whether an inbound QQ chat is known (the bot has been messaged at least once).
-     * Weaker than it looks on this channel: QQ accepts only replies to a recent message, so a
-     * known chat is necessary but not sufficient for anything to be deliverable right now.
+     * Whether an inbound QQ chat is known (the bot has been messaged at least once). Weaker
+     * than it looks on this channel: QQ accepts only replies to a recent message, so a known
+     * chat is necessary but not sufficient for anything to be deliverable right now.
      */
     lastChatKnown: boolean;
-    createdAt: string;
-    updatedAt: string;
+}
+/**
+ * The stored WeChat config, token masked (plaintext never leaves the server).
+ *
+ * No preference field is re-declared. The three delivery preferences cost exactly what they
+ * cost on Feishu and Telegram here — this channel has no reply budget and no expiring reply
+ * window — and re-declaring a field to say nothing new about it would only invite the next
+ * reader to look for the difference.
+ */
+interface WeChatBindingInfo extends MessagingBindingCommon {
+    channel: "wechat";
+    /** The bot id a scan issued — the channel-scoped account identity, never secret. */
+    botId: string;
+    /**
+     * Masked bot token (site-wide mask rule: `***`, or `first4…last4` for long values);
+     * absent when none is stored (cleared, or a scan that never completed) — the binding
+     * cannot be enabled until a scan saves one.
+     */
+    botTokenMasked?: string;
 }
 /** A Session's saved config for one messaging channel (`channel` is the discriminant). */
-type MessagingBindingInfo = FeishuBindingInfo | TelegramBindingInfo | QQBindingInfo;
+type MessagingBindingInfo = FeishuBindingInfo | TelegramBindingInfo | QQBindingInfo | WeChatBindingInfo;
 /** One saved channel config with its event-connection runtime status. */
 interface MessagingChannelState {
     binding: MessagingBindingInfo;
@@ -1710,12 +1767,32 @@ interface QQBindingResponse {
     binding: QQBindingInfo | null;
     status: MessagingRuntimeStatus;
 }
+/** GET / PUT …/messaging/wechat response (the WeChat narrowing of the same envelope). */
+interface WeChatBindingResponse {
+    binding: WeChatBindingInfo | null;
+    status: MessagingRuntimeStatus;
+}
 /**
  * PUT …/messaging/feishu — saves credentials/config ONLY, never flipping the connection
  * (exception: an enabled binding's connector restarts with the new credentials so stored
  * config and live connection never diverge). The connection toggle is POST …/state.
  */
-interface FeishuBindingPutRequest {
+/**
+ * The delivery preferences any channel's PUT may set. Each is optional and each behaves the
+ * same way on every channel: an omitted field keeps the stored value, so a client that knows
+ * about one preference can save it without having to send the others back. Their meanings are
+ * on {@link MessagingBindingCommon}, and where a channel charges differently for one, on that
+ * channel's own `*BindingInfo`.
+ *
+ * The defaults a binding created without them starts from: `linePerMessage` off,
+ * `finalReplyOnly` off, `renderMarkdown` ON.
+ */
+interface MessagingDeliveryPatch {
+    linePerMessage?: boolean;
+    finalReplyOnly?: boolean;
+    renderMarkdown?: boolean;
+}
+interface FeishuBindingPutRequest extends MessagingDeliveryPatch {
     appId: string;
     /** Omitted or blank keeps the stored secret (the masked value never round-trips). */
     appSecret?: string;
@@ -1726,21 +1803,6 @@ interface FeishuBindingPutRequest {
      * it). Refused with 409 `messaging_disable_before_clear` while the binding is enabled.
      */
     clearAppSecret?: boolean;
-    /**
-     * Delivery preference (see `FeishuBindingInfo.linePerMessage`). Omitted keeps the stored
-     * value; a binding created without it starts with it off.
-     */
-    linePerMessage?: boolean;
-    /**
-     * Delivery preference (see `FeishuBindingInfo.finalReplyOnly`). Omitted keeps the stored
-     * value; a binding created without it starts with it off.
-     */
-    finalReplyOnly?: boolean;
-    /**
-     * Delivery preference (see `FeishuBindingInfo.renderMarkdown`). Omitted keeps the stored
-     * value; a binding created without it starts with it ON.
-     */
-    renderMarkdown?: boolean;
 }
 /**
  * PUT …/messaging/telegram — saves the credential ONLY, same contract as the Feishu PUT
@@ -1748,7 +1810,7 @@ interface FeishuBindingPutRequest {
  * POST …/state). Saving never conflicts across Sessions: the same bot may sit saved on
  * several, and only enabling it is exclusive.
  */
-interface TelegramBindingPutRequest {
+interface TelegramBindingPutRequest extends MessagingDeliveryPatch {
     /** Omitted or blank keeps the stored token (the masked value never round-trips). */
     botToken?: string;
     /**
@@ -1757,21 +1819,6 @@ interface TelegramBindingPutRequest {
      * `messaging_disable_before_clear` while the binding is enabled.
      */
     clearBotToken?: boolean;
-    /**
-     * Delivery preference (see `TelegramBindingInfo.linePerMessage`). Omitted keeps the stored
-     * value; a binding created without it starts with it off.
-     */
-    linePerMessage?: boolean;
-    /**
-     * Delivery preference (see `TelegramBindingInfo.finalReplyOnly`). Omitted keeps the stored
-     * value; a binding created without it starts with it off.
-     */
-    finalReplyOnly?: boolean;
-    /**
-     * Delivery preference (see `TelegramBindingInfo.renderMarkdown`). Omitted keeps the stored
-     * value; a binding created without it starts with it ON.
-     */
-    renderMarkdown?: boolean;
 }
 /**
  * PUT …/messaging/qq — saves the credential pair ONLY, same contract as the Feishu PUT
@@ -1779,7 +1826,7 @@ interface TelegramBindingPutRequest {
  * is POST …/state). The App ID is the account identity, so changing it rebinds the row to
  * a different bot and drops the remembered chat.
  */
-interface QQBindingPutRequest {
+interface QQBindingPutRequest extends MessagingDeliveryPatch {
     appId: string;
     /** Omitted or blank keeps the stored secret (the masked value never round-trips). */
     appSecret?: string;
@@ -1788,21 +1835,23 @@ interface QQBindingPutRequest {
      * it). Refused with 409 `messaging_disable_before_clear` while the binding is enabled.
      */
     clearAppSecret?: boolean;
+}
+/**
+ * PUT …/messaging/wechat — the delivery preferences ONLY.
+ *
+ * The one PUT on this router that carries no credential, because there is none to carry: a
+ * WeChat bot token exists only where a scan put it, and there is no console to copy one out
+ * of. Saving therefore presupposes a binding — a PUT before any scan answers 400
+ * `wechat_token_required` rather than creating an empty row — and the connection toggle
+ * stays POST …/state, as on every channel.
+ */
+interface WeChatBindingPutRequest extends MessagingDeliveryPatch {
     /**
-     * Delivery preference (see `QQBindingInfo.linePerMessage`). Omitted keeps the stored
-     * value; a binding created without it starts with it off.
-     */
-    linePerMessage?: boolean;
-    /**
-     * Delivery preference (see `QQBindingInfo.finalReplyOnly`). Omitted keeps the stored
-     * value; a binding created without it starts with it off.
-     */
-    finalReplyOnly?: boolean;
-    /**
-     * Delivery preference (see `QQBindingInfo.renderMarkdown`). Omitted keeps the stored
-     * value; a binding created without it starts with it ON.
+     * Drops the STORED token (the models-page clear idiom). Refused with 409
+     * `messaging_disable_before_clear` while the binding is enabled. The row and its bot
+     * identity stay; only a fresh scan can make it connectable again.
      */
-    renderMarkdown?: boolean;
+    clearBotToken?: boolean;
 }
 /**
  * POST …/messaging/<channel>/state — enable connects with the STORED credentials,
@@ -1895,6 +1944,82 @@ interface QQScanPollResponse {
     /** The saved binding, present on `completed` so the editor refreshes without a second GET. */
     binding?: QQBindingInfo;
 }
+/**
+ * WeChat credential-test outcome. There is no request body and no draft to probe: this
+ * channel's credential exists only where a scan put it, so the test always probes the STORED
+ * binding. It answers 400 `wechat_token_required` when there is none.
+ *
+ * No account label, for the same reason QQ has none: the probe (`getconfig`) reports the
+ * bot's settings and names neither the bot nor the person.
+ */
+interface WeChatTestResponse {
+    ok: boolean;
+    latencyMs?: number;
+    error?: string;
+}
+/**
+ * POST …/messaging/wechat/scan — starts a scan-to-connect flow, which on this channel is the
+ * ONLY way to bind: the bot token has no console to be copied out of.
+ *
+ * The server registers a code and answers with what the browser may know. The platform's own
+ * poll handle is absent from this type on purpose — it is what collects the bot token, so it
+ * never leaves the server, and `taskId` is a handle this server mints in its place.
+ */
+interface WeChatScanStartResponse {
+    /** Opaque scan handle, passed back to the poll, verify and cancel endpoints. */
+    taskId: string;
+    /** The URL to ENCODE into a QR code. It is opened by WeChat, never fetched by the browser. */
+    qrUrl: string;
+    /** How often to poll, in milliseconds. */
+    pollMs: number;
+}
+/**
+ * Where a WeChat scan stands. Richer than QQ's four states because the flow is: WeChat
+ * separates scanning from confirming, and may interpose a pairing code shown on the phone.
+ *
+ * - `pending` — the code is up and nothing has happened; keep polling.
+ * - `scanned` — scanned; the phone is showing the confirmation prompt.
+ * - `need_verify_code` — the phone is showing digits that must be sent to the verify
+ *   endpoint before the bind proceeds.
+ * - `blocked` — too many wrong pairing codes; the code is spent and a new scan is needed.
+ * - `expired` — the code lapsed before it was used; show a new one.
+ * - `already_bound` — this bot is already bound to this server, so no new credentials were
+ *   issued and nothing was saved. Not a failure: the existing binding still works.
+ * - `completed` — the server has already SAVED the binding; `botId` names the bot.
+ */
+type WeChatScanStatus = "pending" | "scanned" | "need_verify_code" | "blocked" | "expired" | "already_bound" | "completed";
+/**
+ * POST …/messaging/wechat/scan/poll — one step of the scan.
+ *
+ * `completed` means the server has decrypted nothing and stored everything: the credentials
+ * went from the platform into storage without passing through the browser. Saving is all it
+ * does — enabling the connection stays the separate, exclusive act it is on every channel. A
+ * task id that is unknown, belongs to another Session, or was already resolved answers 404
+ * `wechat_scan_task_unknown`.
+ *
+ * Unlike QQ's poll, an overlapping request answers `pending` rather than 404: the upstream
+ * call is a LONG poll, so one of them spans several of the client's intervals, and that
+ * overlap is the normal rhythm rather than a replay.
+ */
+interface WeChatScanPollResponse {
+    status: WeChatScanStatus;
+    /** The bound bot's id; present only on `completed`. Never the token. */
+    botId?: string;
+    /** The saved binding, present on `completed` so the editor refreshes without a second GET. */
+    binding?: WeChatBindingInfo;
+}
+/**
+ * POST …/messaging/wechat/scan/verify — the digits WeChat showed on the phone.
+ *
+ * They ride the NEXT poll rather than a request of their own, because the platform takes the
+ * pairing code as a parameter of the status call: this endpoint records them and answers
+ * 204. A wrong code is not reported here — the next poll asks for one again, which is how
+ * the platform reports it.
+ */
+interface WeChatScanVerifyRequest {
+    taskId: string;
+    verifyCode: string;
+}
 /**
  * POST …/messaging/<channel>/test-message — sent to the last known chat (409
  * `feishu_no_chat` / `telegram_no_chat` / `qq_no_chat` before one exists). On QQ this can
@@ -1922,6 +2047,13 @@ type ServerEvent =
     queued?: number;
     /** Steering messages queued but not yet delivered (absent = none): lets the composer's hint and its content survive reloads. */
     pendingSteering?: PendingSteeringInfo[];
+    /**
+     * Steering the run ended without delivering (absent = none) — an interrupt while a tool
+     * was running is the ordinary way to produce one. Handed back rather than discarded: the
+     * composer recalls each by the same handle and restores it into the draft, so the typed
+     * message returns to the input box instead of being lost.
+     */
+    returnedSteering?: PendingSteeringInfo[];
     /** Queued follow-up tasks awaiting auto-start (absent = none): per-entry content + recall handle, alongside the `queued` count. */
     pendingFollowUps?: PendingFollowUpInfo[];
     /**
@@ -1963,6 +2095,19 @@ type ServerEvent =
     lastActiveAt: string;
     hasTrace: boolean;
 }
+/**
+ * A Session's background-task counts changed: a command promoted to the background, a
+ * process that exited or was stopped, a background subagent starting or settling a round,
+ * a released session. The counts are the row's `backgroundTasks` as they stand after the
+ * change — zeros included, so a list can clear its mark without refetching. Published to
+ * the user channels of the Project's owner and members, like `session_state`.
+ */
+ | {
+    type: "session_background";
+    sessionId: string;
+    processes: number;
+    subagents: 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";
@@ -2053,6 +2198,24 @@ interface ContextToolShare {
     name: string;
     tokens: number;
 }
+/**
+ * One file's share of the context: its `read_file` / `edit_file` / `write_file` calls plus their
+ * results, keyed by the file each call named.
+ */
+interface ContextFileShare {
+    /**
+     * Workspace-relative when the file is inside the Session's Workspace; otherwise absolute, with
+     * the home directory shortened to `~`. Spellings that resolve to the same file are one row.
+     */
+    path: string;
+    tokens: number;
+    /** How many calls of each file tool named the file in this context. */
+    ops: {
+        read: number;
+        edit: number;
+        write: number;
+    };
+}
 /**
  * What the Session's current model context is made of — the part derived from its messages.
  *
@@ -2063,7 +2226,8 @@ interface ContextToolShare {
  *
  * The six parts partition the context and sum to `total`; `topTools` is a ranking inside
  * `toolRequests + toolResults` and can sum to less than those two (a result whose call was not
- * recorded in the same Trace shard has no tool to be attributed to).
+ * recorded in the same Trace shard has no tool to be attributed to). `topFiles` is the same
+ * ranking narrowed to the three file tools and keyed by the file each call named.
  */
 interface SessionContextParts {
     systemPrompt: number;
@@ -2076,6 +2240,8 @@ interface SessionContextParts {
     total: number;
     /** Tools ranked by the context their traffic occupies, descending; at most five. */
     topTools: ContextToolShare[];
+    /** Files ranked by the context their file-tool traffic occupies, descending; at most five. */
+    topFiles: ContextFileShare[];
     /**
      * A completed compaction closed the context these figures describe, and the next one has not
      * been written yet: the composition is of what was compacted away, not of what the model now
@@ -2195,6 +2361,16 @@ interface TraceTaskStats {
         cacheWrite: number;
         output: number;
     };
+    /**
+     * This turn's cost in USD: each Request's three buckets at the Project's current rates for
+     * the file's model, at the tier that Request's own timestamp fell in — the rule and the
+     * price lookup the cost center applies to the usage row the same `token_usage` produced,
+     * so this figure, the toolbar's and the cost center's agree on what a request cost. Present
+     * on every turn of a priced file (a turn with no Request reads 0); absent when the model has
+     * no pricing or the file's head names no provider, and then absent from the response's
+     * total as well.
+     */
+    cost?: number;
     /**
      * Total LLM generation duration for this turn (the denominator for output TPS; human
      * approval wait already deducted). The numerator is simply `tokens.output`: since
@@ -2202,6 +2378,21 @@ interface TraceTaskStats {
      * output — there's no second figure to reconcile.
      */
     llmMs: number;
+    /**
+     * Wall-clock time this turn spent executing tools: the **union** of its tool spans'
+     * execution intervals (`approvalTs ?? callTs` to `outputTs`), so tools running in parallel
+     * are counted once instead of summed. Two exclusions, both deliberate: the human approval
+     * wait (`callTs` to `approvalTs`) is not tool work, and the argument-generation segment is
+     * the model streaming arguments, already counted in `llmMs`. A span with no `outputTs` —
+     * still running when the file ended, or interrupted — contributes nothing rather than being
+     * extrapolated to now.
+     *
+     * This and `llmMs` may **overlap**: a tool started in the background keeps running while the
+     * model decodes. They are two measured components of the turn's duration, not a partition of
+     * it, and they need not add up to the turn's span (approval waits and harness overhead belong
+     * to neither). Never derive one by subtracting the other from the duration.
+     */
+    toolMs: number;
 }
 /** Duration span of a single tool call (complete tool_call message → paired tool_call_output). */
 interface ToolCallSpan {
@@ -2224,6 +2415,21 @@ interface WorkspaceFilesResponse {
     path: string;
     entries: WorkspaceFileEntry[];
 }
+/** Write one Workspace file whole (the Upload button, a drop, and the Files panel's editor). */
+interface FilesWriteRequest {
+    /** The entire file, base64-encoded (≤14MB decoded). */
+    dataBase64: string;
+    /**
+     * Write precondition: the version marker the caller read off this file's `ETag` on
+     * `GET files/content`. The server compares it against the file's state immediately
+     * before writing and answers 409 `file_changed` — having written nothing — when they
+     * differ, which is what stops the editor's save from quietly dropping what the Agent
+     * wrote during the turn. Omitted by a caller that read no version (an upload creates or
+     * replaces unconditionally); that absence, not a sentinel value, is what says there was
+     * no prior version to match.
+     */
+    ifVersion?: string;
+}
 /** 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). */
@@ -2295,6 +2501,23 @@ interface TraceAnalysisResponse {
      * frontend's events are paginated, so self-aggregation would undercount.
      */
     elapsedMs: number;
+    /**
+     * The file's model-API time: the sum of the turns' `llmMs` (human approval wait deducted,
+     * compaction requests included, so the scope matches `elapsedMs`).
+     */
+    apiMs: number;
+    /**
+     * The file's tool wall time: the sum of the turns' `toolMs` (parallel tools counted once
+     * within a turn). Summed per turn rather than unioned across the file, so the global figure
+     * stays the sum of the per-turn figures, exactly as `elapsedMs` is. May overlap `apiMs` —
+     * see `TraceTaskStats.toolMs`.
+     */
+    toolMs: number;
+    /**
+     * The file's cost in USD: the sum of the turns' `cost` (compaction turns included, the
+     * scope every total here shares). Absent exactly when the turns carry no `cost`.
+     */
+    cost?: number;
     requests: RequestSpan[];
     /** Token / duration aggregated per Task (used directly by the Trace page's context ring and per-turn TPS). */
     tasks: TraceTaskStats[];
@@ -2450,6 +2673,23 @@ interface UsageModelSeries extends UsageEntitySeriesCounts {
     provider: string;
     modelId: string;
 }
+/**
+ * Lifetime Token total for one Model, keyed by the (provider, modelId) pair. Deliberately
+ * unfiltered — no date range, no Agent: it answers "how much has this model been used", a
+ * question with no window attached, and the models page that shows it carries no filters of its
+ * own to honour. Models never used are absent rather than zero.
+ */
+interface UsageModelTotal {
+    provider: string;
+    modelId: string;
+    /** The three buckets summed (cache read + cache write + output), matching the cost center's Token figure. */
+    tokens: number;
+    requests: number;
+}
+/** Response of `GET /usage/model-totals`. */
+interface UsageModelTotals {
+    totals: UsageModelTotal[];
+}
 /**
  * The two categories an error record is filed under: `unexpected` is a 500 or an unforeseen
  * runtime exception, `expected` an HttpError / business 4xx. The panel separates them by
@@ -2480,6 +2720,7 @@ interface UsageErrorItem {
  * items.
  */
 interface UsageErrors {
+    /** Filtered row 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;
@@ -2492,8 +2733,9 @@ interface UsageErrors {
  * GET /api/projects/:projectId/usage/errors — one page of the error detail table, newest
  * first. The dashboard response above already carries the first page; this exists so
  * "show me earlier ones" does not have to refetch the whole aggregate. It takes the same
- * date/agent filter as the dashboard, so a page never widens what the summary counted, plus
- * an optional `kind` ({@link UsageErrorKind}) narrowing to one of the two categories — which
+ * date/agent filter as the dashboard (`fromTs`/`toTs` narrow it to a trailing window, both
+ * 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.
  */
@@ -2502,6 +2744,22 @@ interface UsageErrorsPage {
     /** Filtered row count, so the caller knows when it has reached the end. */
     total: number;
 }
+/**
+ * DELETE /api/projects/:projectId/usage/errors — empties the error table for the filter the
+ * panel is showing (its date range, the trailing window when one is on, and Agent), Project
+ * owner only.
+ *
+ * Scoped to the filter rather than the Project's whole history, so a clear takes exactly the
+ * rows on screen — for an admin, the unattributed rows an admin's panel shows included; a
+ * member's panel never shows them and a member's clear never takes them.
+ *
+ * `from` and `to` are both required (400 otherwise), where the reads treat them as optional:
+ * an absent bound is unbounded on that side, which is the whole history rather than a filter.
+ */
+interface UsageErrorsClearResponse {
+    /** How many rows were deleted, so the caller can say what went instead of guessing. */
+    deleted: number;
+}
 interface UsageResponse {
     summary: {
         today: UsageBucket;
@@ -2677,31 +2935,99 @@ interface SkillMetadataItem {
     /** Short description for frontend display (frontmatter short_description, optional; falls back to description if missing). */
     shortDescription?: string;
     shortDescriptionZh?: string;
-    /** Custom icon (raw icon.svg text from the skill directory, optional; frontend falls back to a default book icon if missing). */
+    /**
+     * Raw icon.svg text from the installed skill directory: the plugin's icon for a library
+     * install (written beside SKILL.md at install time), a custom one for a user-authored skill.
+     * Only installed lists carry it — the library listing's skills share their plugin's icon,
+     * 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. */
+    version: string;
+}
+/** One installed hook package (`agent_state/hooks/<name>/`): its manifest, without the scripts. */
+interface HookItem {
+    /** Hook package name — the plugin that shipped it (the identity uninstall addresses it by). */
+    name: string;
+    description: string;
+    descriptionZh?: string;
+    /** Version (`YYYY.MM.DD.N`; a copy installed before that spelling still carries `YYYY-MM-DD.N`); an empty string when the manifest carries none. */
+    version: string;
+    /** The hook points the package answers at, e.g. `["stop"]`. */
+    events: string[];
+    /** 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). */
+interface PluginItem {
+    name: string;
+    description: string;
+    descriptionZh?: string;
+    shortDescription?: string;
+    shortDescriptionZh?: string;
+    /** `YYYY.MM.DD.N`. */
+    version: string;
+    /** The plugin's skills (metadata only). */
+    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. */
     icon?: string;
-    /** Version number (natural number, frontmatter version; falls back to 1 if invalid). */
-    version: number;
-    /** Update timestamp (frontmatter updated, ISO 8601 UTC by convention; defaults to an empty string). */
-    updated: string;
 }
-interface SkillGroupItem {
+interface PluginGroupItem {
     id: string;
     title: string;
-    /** Chinese group title (optional; the UI displays it per language). */
+    /** Chinese category title (optional; the UI displays it per language). */
     titleZh?: string;
-    skills: SkillMetadataItem[];
+    plugins: PluginItem[];
+}
+/** GET /api/plugins: the library by category (any logged-in user). */
+interface PluginLibraryResponse {
+    groups: PluginGroupItem[];
+}
+/**
+ * GET /api/plugins/:plugin/files: everything a library plugin ships, for the detail view's file
+ * browser — each skill's installable SKILL.md and auxiliary files under `skills/<name>/`, the
+ * hook package's scripts under `hooks/` — keyed by path relative to the plugin directory. The
+ * manifest and the icon are not among them: the listing already carries both.
+ */
+interface PluginFilesResponse {
+    files: Record<string, string>;
+}
+/**
+ * POST /api/projects/:p/agents/:a/plugins: install library plugins by name — each one's skills
+ * and hook package; already-installed ones are overwritten with library content (i.e. updated).
+ * Every name must be in the library (404 `unknown_plugin`, nothing written). 201 returns the
+ * refreshed installed lists.
+ */
+interface PluginInstallRequest {
+    names: string[];
 }
-/** GET /api/skills: library groups and metadata (excludes body content). */
-interface SkillLibraryResponse {
-    groups: SkillGroupItem[];
+interface AgentPluginsInstallResponse {
+    skills: SkillMetadataItem[];
+    hooks: HookItem[];
 }
-/** GET|POST /api/projects/:p/agents/:a/skills: Skills installed on this Agent. */
+/** GET /api/projects/:p/agents/:a/skills: Skills installed on this Agent. */
 interface AgentSkillsResponse {
     skills: SkillMetadataItem[];
 }
-/** POST install request: all names must exist in the library; already-installed ones are overwritten with library content (i.e. updated). */
-interface SkillInstallRequest {
-    names: string[];
+/** GET /api/projects/:p/agents/:a/hooks: hook packages installed on this Agent; DELETE …/hooks/:name uninstalls one (204). */
+interface AgentHooksResponse {
+    hooks: HookItem[];
+}
+/**
+ * POST /api/projects/:p/agents/:a/hooks/archive: install one hook package from an uploaded zip.
+ * Layout: hooks.json and its scripts at the zip root, or exactly one top-level directory
+ * containing them (the directory name is then the package name). 201 returns the refreshed
+ * installed list (AgentHooksResponse); an already-installed name without `overwrite` is 409
+ * `hook_exists`. GET …/hooks/:name/archive is the matching export: the installed directory as
+ * a zip attachment, which round-trips through this POST.
+ */
+interface HookArchiveInstallRequest {
+    /** Base64-encoded zip archive (decoded size capped at 14MB, like the skill archive). */
+    dataBase64: string;
+    /** Replace an installed package of the same name instead of answering 409. */
+    overwrite?: boolean;
 }
 /**
  * POST /api/projects/:p/agents/:a/skills/archive: install one Skill from an uploaded zip.
@@ -2752,7 +3078,9 @@ interface UpdateCheckResponse {
  * utilityProcess message channel and served at GET /api/desktop/update. `state` is the
  * discriminator; the optional fields belong to the states named on them.
  *
- * A `downloaded` build stays the reported state until it is installed: a later periodic
+ * The shell never downloads on its own: a check ends in `available`, and the download
+ * starts only on the page's (or the native dialog's) say-so — the `download` command. A
+ * `downloaded` build stays the reported state until it is installed: a later periodic
  * check (or its failure) must not hide the actionable "restart to install" step.
  */
 interface DesktopUpdateStatus {
@@ -2765,8 +3093,8 @@ interface DesktopUpdateStatus {
      * carry that signal (a check that ends where it started is byte-identical).
      */
     seq?: number;
-    state: "idle" | "checking" | "up-to-date" | "downloading" | "downloaded" | "error" | "unsupported";
-    /** Newer release being fetched / ready to install (`downloading`, `downloaded`). */
+    state: "idle" | "checking" | "up-to-date" | "available" | "downloading" | "downloaded" | "error" | "unsupported";
+    /** The newer release: offered (`available`), being fetched (`downloading`) or ready to install (`downloaded`). */
     version?: string;
     /** Download progress 0–100 (`downloading`). */
     percent?: number;
@@ -2787,15 +3115,19 @@ interface DesktopUpdaterStatusMessage {
     type: "desktop-updater-status";
     status: DesktopUpdateStatus;
 }
-/** Server → shell command over the utilityProcess message channel (relayed from POST /api/desktop/update/check|install). */
+/**
+ * Server → shell command over the utilityProcess message channel (relayed from
+ * POST /api/desktop/update/check|download|install): look for a release, fetch the one
+ * offered, or restart into the one downloaded.
+ */
 interface DesktopUpdaterCommandMessage {
     type: "desktop-updater-command";
-    action: "check" | "install";
+    action: "check" | "download" | "install";
 }
 /**
- * POST /api/version/update (admin only): runs the CLI self-update (`penguin update --yes`)
- * on the server host. `unsupported` covers both a server not launched via the CLI and the
- * CLI's own refusals (source checkout, unrecognized install layout, Windows).
+ * 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
+ * the CLI and the CLI's own refusals (source checkout, unrecognized install layout, Windows).
  */
 interface UpdateRunResponse {
     status: "updated" | "failed" | "unsupported";
@@ -2806,6 +3138,44 @@ interface UpdateRunResponse {
     /** True when the install changed (or was already current): restart the service to run the new version. */
     needsRestart: boolean;
 }
+/**
+ * Where a running self-update is: resolving the release and fetching the installer,
+ * downloading the bundle (the one phase with a percentage), or verifying and installing it.
+ */
+type UpdateJobPhase = "resolving" | "downloading" | "installing";
+/**
+ * GET / POST /api/version/update (admin only): the self-update job. POST starts a run when
+ * none is in flight — a finished run may be started again, which is how a failed one is
+ * retried — and answers with the status exactly as GET does; the page polls GET while
+ * `state` is `running`. One job per process: two admins clicking at once share the one run,
+ * and the finished status stays readable until the next start.
+ */
+interface UpdateJobStatus {
+    state: "idle" | "running" | "done";
+    /** The release the run targets — the update check's newest version when the run started; null when none was known. */
+    targetVersion: string | null;
+    /** Running only. */
+    phase?: UpdateJobPhase;
+    /** Running, `downloading` only: 0–100 read off the installer's progress bar; null until its first tick. */
+    percent?: number | null;
+    /** Tail of the update command's combined stdout+stderr so far (capped; empty when nothing ran). */
+    output: string;
+    /** Done only. */
+    result?: UpdateRunResponse;
+    startedAt?: string;
+    finishedAt?: string;
+}
+/**
+ * POST /api/version/restart (admin only): asks the process to exit with the supervisor's
+ * restart code after a graceful shutdown, so `penguin server|web` relaunches it on the
+ * installed release. `restarting: false` when nothing supervises this process — it was
+ * started some other way than through the CLI, or it is a dev run — and the page shows the
+ * manual restart hint instead.
+ */
+interface RestartResponse {
+    restarting: boolean;
+    reason?: "no_supervisor";
+}
 /** One `Host` entry of the server's `~/.ssh/config`, as the Machines page lists it. */
 interface MachineInfo {
     /** `ssh:<alias>` — the id the install route is asked for. */
@@ -2817,9 +3187,9 @@ interface MachineInfo {
      */
     alias: string;
     /**
-     * The last install THIS server carried out there, remembered on disk so it survives a
-     * restart, a hot push, and installing on some other machine. Null when this server has
-     * never installed there.
+     * The last install THIS server carried out there FOR THIS PROJECT, remembered in web.db so
+     * it survives a restart, a hot push, and installing on some other machine. Null when this
+     * Project has never installed there — a host another Project did is `elsewhere` below.
      *
      * A record of what was done, not a survey of the far side: a machine wiped by hand still
      * reads as installed until the next install probes it and corrects the record. Asking the
@@ -2830,25 +3200,112 @@ interface MachineInfo {
         version: string;
         at: string;
     } | null;
+    /**
+     * Installed by this server, but not this Project's machine — another Project's, or nobody's
+     * since it was released — and so not a host nobody has touched either. Absent in every
+     * other case, including when it IS this Project's (where `installed` carries the same record).
+     *
+     * Reported rather than folded into `installed` because the two lead to different actions:
+     * one is a machine to use, the other is a machine to adopt, which costs a row and no ssh.
+     * Reported rather than hidden because a row that silently looked uninstalled would send
+     * someone to spend a 30 MB transfer re-doing what is already done.
+     */
+    elsewhere?: {
+        version: string;
+        at: string;
+    };
+    /**
+     * 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
+     * that machine, since nothing has minted one yet.
+     *
+     * This is what anything stored should point at; `id` above is an ADDRESS (`ssh:<alias>`),
+     * and `alias` is what people read. Two aliases for one host share a `machineId`, and an
+     * alias repointed at a different host answers a different one — an id never changes for a
+     * machine, so a change of id is a change of machine.
+     */
+    machineId: string | null;
+    /** The host this server itself runs on. Always present, always installed, never a target. */
+    local: boolean;
+    /**
+     * The connection this server holds to it — the one ssh session everything to the machine
+     * rides (machines/transport/ssh-session.ts): a fact about a process on THIS side, which
+     * outlives the far server. Present means `/server/<id>/api/…` has somewhere to go; whether
+     * a server ANSWERS over there is `status`'s word, from the last probe — and the two must not
+     * be read for each other: taking the connection for the machine's liveness is the mistake
+     * behind the connect loop (#561). Always null for `local`, which needs no connection.
+     */
+    connection: {
+        pid: number;
+    } | null;
+    /**
+     * 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
+     * an HTTP answer (any status: a server that refuses is still answering); `failedAt` and
+     * the transport's own words when the connection had nowhere to deliver. Null until a first
+     * request flows, and only as fresh as the last one — no traffic, no measurement, which is
+     * honest: nothing burns ssh for a page nobody is looking at. Always null for `local`;
+     * this server answering the request that fetched this list is that measurement.
+     */
+    api: {
+        answeredAt: string;
+    } | {
+        failedAt: string;
+        detail: string;
+    } | null;
+    /**
+     * 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
+     * answer and the page asks for a fresh one when it wants one — on a widening schedule,
+     * since each probe is an ssh round trip while the list is only the config's text.
+     */
+    status: MachineServerStatus | null;
+}
+/**
+ * One machine's server state. There is deliberately no separate "ssh" status: ssh is the
+ * transport, so a machine it cannot reach reads as `unreachable` with OpenSSH's own
+ * diagnostic in `detail` rather than as two statuses a reader has to combine.
+ */
+interface MachineServerStatus {
+    state: "running" | "stopped" | "unreachable";
+    /** ISO timestamp of the probe this answer came from. */
+    checkedAt: string;
+    /** The port it is serving on (`running`). */
+    port?: number;
+    /** Why the machine could not be reached (`unreachable`) — ssh's own words. */
+    detail?: string;
 }
 /**
- * The running or last install, polled by GET /api/machines while one runs. `log` carries the
- * far side's own words where there are any: ssh's diagnostics and the remote installer's
- * output say more about a refused key or an unusable Node than a paraphrase would.
+ * The running or last job on a machine — an install, or a connect — polled by GET
+ * /api/machines while one runs. One at a time. `log` carries the far side's own words where
+ * there are any: ssh's diagnostics and the remote installer's output say more about a
+ * refused key or an unusable Node than a paraphrase would.
  */
-interface MachineInstallJob {
+interface MachineJob {
+    kind: "install" | "connect" | "restart";
     machineId: string;
     alias: string;
     running: boolean;
     log: string[];
     result: null | {
         ok: true;
-        kind: "installed" | "already-installed";
+        installed: "installed" | "already-installed";
         version: string | null;
+    } | {
+        ok: true;
+        connected: 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.
+         */
+        canReplaceProgram?: true;
     };
 }
 /** GET /api/machines, and the 202 body of POST /api/machines/:machineId/install. */
@@ -2860,7 +3317,7 @@ interface MachinesResponse {
      * checkout, which stands on no release the remote could download.
      */
     imageVersion: string | null;
-    job: MachineInstallJob | null;
+    job: MachineJob | null;
 }
 
-export type { AdminPasswordResetRequest, AdminUserCreateRequest, AdminUserCreateResponse, AdminUsersResponse, AgentCompactionConfigDto, AgentConfigDto, AgentConfigResponse, AgentConfigUpdateRequest, AgentCreateRequest, AgentCreateResponse, AgentImportRequest, AgentImportResponse, AgentKernelUpdateResponse, AgentMemoryConfigDto, AgentModelConfigDto, AgentSchedulesConfigDto, AgentSkillsConfigDto, AgentSkillsResponse, AgentSummary, AgentTraceDateGroup, AgentTraceFileRef, AgentTraceSessionEntry, AgentTraceSessionFile, AgentTraceSessionGroup, AgentTracesResponse, AgentVaultConfigDto, AgentsResponse, ApprovalDecisionRequest, ApprovalMode, AuthLoginRequest, AuthResponse, BenchmarkCaseScore, BenchmarkCaseSummary, BenchmarkCasesResponse, BenchmarkEvaluation, BenchmarkRunScore, BenchmarkSummary, BenchmarksResponse, CaseMaterial, ChatDefaultsDto, CommandPolicyDto, CommandPolicyRuleDto, ContextToolShare, CredentialInfo, DefaultModelResponse, DefaultModelUpdateRequest, DesktopUpdateStatus, DesktopUpdateStatusResponse, DesktopUpdaterCommandMessage, DesktopUpdaterStatusMessage, DirEntryInfo, DirListResponse, DirectorySkillItem, DirectorySkillsResponse, DraftShortcut, EndpointModelListRequest, EndpointModelListResponse, ErrorBody, FeishuBindingInfo, FeishuBindingPutRequest, FeishuBindingResponse, FeishuTestRequest, FeishuTestResponse, FilesStatRequest, FilesStatResponse, GoalResponse, GoalServerEvent, GoalStateView, HistoryMessage, InstallResponse, MachineInfo, MachineInstallJob, MachinesResponse, McpServerTestResponse, MeResponse, MemberAddRequest, MemberAddResponse, MemberInfo, MembersResponse, MemoryFileInfo, MemoryFileResponse, MemoryFilesResponse, MemoryImportMode, MemoryImportRequest, MemoryImportResponse, MemoryOverviewResponse, MemoryScopeExport, MemoryScopeInfo, MemoryTransferFile, MessagesLiveTail, MessagesPageInfo, MessagesResponse, MessagingBindingInfo, MessagingBindingStateRequest, MessagingBindingsResponse, MessagingChannel, MessagingChannelState, MessagingDeliveryError, 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, PrefsResponse, ProjectCreateRequest, ProjectCreateResponse, ProjectRole, ProjectSummary, ProjectUpdateRequest, ProjectUpdateResponse, ProjectsResponse, ProtocolProbeOutcome, QQBindingInfo, QQBindingPutRequest, QQBindingResponse, QQScanPollResponse, QQScanStartResponse, QQTestRequest, QQTestResponse, RecalledMessageResponse, RequestSpan, RetryNowResponse, ScheduleItem, ScheduleServerEvent, ScheduleStatus, ScheduleUpsertRequest, SchedulesResponse, ServerEvent, ServerSettings, ServerSettingsResponse, ServerSettingsUpdateRequest, SessionCategory, SessionCategoryCounts, SessionContextParts, SessionContextResponse, SessionCreateRequest, SessionCreateResponse, SessionForkRequest, SessionForkResponse, SessionInfo, SessionPatchRequest, SessionProcessInfo, SessionProcessesResponse, SessionResponse, SessionSource, SessionStatus, SessionTracesResponse, SessionsResponse, SkillArchiveInstallRequest, SkillGroupItem, SkillInstallRequest, SkillLibraryResponse, SkillMetadataItem, SkillUpdateRef, SteerRequest, SubagentMessageResponse, SubagentRuntimeInfo, TaskCreateRequest, TaskCreateResponse, TaskInputPart, TelegramBindingInfo, TelegramBindingPutRequest, TelegramBindingResponse, TelegramTestRequest, TelegramTestResponse, ToolCallSpan, TraceAnalysisResponse, TraceEventsResponse, TraceFileInfo, TraceImportRequest, TraceImportResponse, TraceModelSegment, TraceOtherSpan, TracePosition, TraceTaskStats, TraceToolSpan, UiPrefs, UpdateCheckResponse, UpdateRunResponse, UploadLimits, UsageAgentSeries, UsageBucket, UsageEntitySeriesCounts, UsageErrorCount, UsageErrorItem, UsageErrorKind, UsageErrors, UsageErrorsPage, UsageGranularity, UsageGroupBy, UsageGroupRow, UsageModelSeries, UsageResponse, UsageSeriesPoint, UsageTrendPointInTrace, UserInfo, VaultEntryInfo, VaultEntryUpdate, VaultResponse, VaultUpdateRequest, VersionResponse, WorkspaceFileEntry, WorkspaceFilesResponse };
+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 };