@prismshadow/penguin-server 0.2.7 → 0.2.9

package/dist/api/types.d.ts

@@ -47,6 +47,19 @@ interface AuthLoginRequest {
 interface AuthResponse {
     user: UserInfo;
 }
+/**
+ * GET /api/install — the identity of the data root this server is serving (install-id.ts),
+ * read by the web app before it mounts so state persisted against a DIFFERENT root can be
+ * swept. Public, like the login route it sits next to.
+ */
+interface InstallResponse {
+    /**
+     * Opaque per-data-root id, or null when the server could not establish one (an
+     * unreadable or unwritable root). Null means "unknown", and a client must change
+     * nothing on it — never treat it as a new install.
+     */
+    installId: string | null;
+}
 interface MeResponse {
     user: UserInfo;
     /**
@@ -62,18 +75,19 @@ interface MeResponse {
     /**
      * Whether this server runs in desktop mode (spawned by the desktop shell with
      * PENGUIN_DESKTOP_TOKEN). The web app then hides the logout entry, the
-     * initial-password banner and the self-update entry, and omits the old-password
-     * field when changing the password.
+     * initial-password banner and the self-update entry.
      */
     desktopMode: boolean;
     /**
-     * How THIS session was established. Distinct from desktopMode: a browser signed into a
-     * desktop-mode server holds a "password" session and must still provide the old
-     * password when changing it — only "desktop" sessions (opened by the shell's one-shot
-     * token) may omit it. "token" marks a request authenticated by the local API token's
-     * Bearer header (the CLI and agent-driven calls).
+     * How THIS session was established — distinct from desktopMode, which describes the
+     * server: a browser signed into a desktop-mode server holds a "password" session.
+     * "desktop" is the shell's own window (one-shot token); "setup" was claimed through the
+     * first-login link on a server whose admin password has never been set. Both may set a
+     * password without the old one (it is random and was never shown); only "desktop" opens
+     * desktop-only routes. "token" marks a request authenticated by the local API token's
+     * Bearer header (the CLI and agent-driven calls) — no stored session at all.
      */
-    sessionVia: "password" | "desktop" | "token";
+    sessionVia: "password" | "desktop" | "setup" | "token";
     /**
      * The upload limits currently in force, so the composer can refuse an oversize pick before
      * reading it and can name the real number in the message. They are admin-settable and ride
@@ -108,7 +122,7 @@ interface UploadLimits {
     attachmentLimitMaxMb: number;
 }
 interface PasswordChangeRequest {
-    /** Omitted only by desktop-established sessions (desktop mode); required otherwise. */
+    /** Omitted only by a "desktop" or "setup" session (see {@link MeResponse.sessionVia}); required otherwise. */
     oldPassword?: string;
     /** At least 8 characters. */
     newPassword: string;
@@ -220,6 +234,14 @@ interface UiPrefs {
     credentialGuideSeen?: boolean;
     /** The initial-password notice banner (app layout) was permanently dismissed by the user. */
     initialPasswordBannerDismissed?: boolean;
+    /**
+     * "I have dealt with this" markers for the dismissible to-do badges, per Project id and then
+     * per trail (`skills` / `models` / `errors`). Each value is the SIGNATURE of what was waved
+     * away rather than a hidden flag, so anything new raises the dot again (web's
+     * `lib/todo-badges.ts`). Replaced whole on every write, like `draftShortcuts`: the merge is
+     * shallow, so this whole map is one field.
+     */
+    todoDismissed?: Record<string, Record<string, string>>;
     /**
      * The draft screen's user-defined shortcuts, in display order. Replaced whole on every write
      * (the merge is shallow, so the array is one field like any other) and bounded on write by
@@ -593,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;
 }
 /**
@@ -679,6 +708,13 @@ 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. */
+    name: string;
+    /** The LIBRARY's version, i.e. what installing again would bring, not what is on disk. */
+    version: number;
+}
 interface AgentSummary {
     agentId: string;
     name?: string;
@@ -704,6 +740,14 @@ 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
+     * library version for them to be behind.
+     */
+    skillUpdates: SkillUpdateRef[];
     /** Memory count (topic files summed over the scope directories under agent_state/memory/, independent of the memory switch). */
     memoryCount: number;
 }
@@ -1446,20 +1490,117 @@ interface SessionProcessesResponse {
     processes: SessionProcessInfo[];
 }
 /** Messaging channels a Session can bind to. */
-type MessagingChannel = "feishu" | "telegram";
+type MessagingChannel = "feishu" | "telegram" | "qq" | "wechat";
 /** Event-connection runtime state of one binding (kept in memory, not persisted). */
 type MessagingRuntimeState = "disconnected" | "connecting" | "connected" | "error";
+/**
+ * A failure that happened AFTER an inbound message was accepted — as opposed to a
+ * connection failure, which `MessagingRuntimeStatus.lastError` reports.
+ *
+ * The two stages fail in completely different places and lead to different actions, and
+ * from the chat they are indistinguishable (both produce silence), which is why the stage
+ * is stated rather than folded into one message.
+ */
+interface MessagingDeliveryError {
+    /** ISO 8601 timestamp of the failure. */
+    at: string;
+    /** `inbound` — the message arrived and its Task never started; `send` — a reply never reached the chat. */
+    stage: "inbound" | "send";
+    /** The failure's own message, as the channel or the Session reported it. */
+    detail: string;
+}
 interface MessagingRuntimeStatus {
     state: MessagingRuntimeState;
     /** Failure detail; present only in the `error` state. */
     lastError?: string;
     /** When the state last changed (ISO 8601); absent for a binding that never connected. */
     changedAt?: string;
+    /**
+     * When this binding last accepted an inbound message (ISO 8601).
+     *
+     * "Connected, and nothing has arrived" is the answer to the one question a chat cannot
+     * answer for itself — whether the platform is delivering anything at all. A channel that
+     * withholds messages (Telegram's group privacy, a bot that is not a member) produces
+     * exactly that, with no error anywhere.
+     *
+     * In-process AND scoped to one connection: it starts empty on every (re)connect, and a
+     * re-enable or a credential save opens a new one. So an absent field means "nothing since
+     * this connection opened", never "nothing ever" — anything reporting it has to say which,
+     * or it sends a reader off to fix a channel that is working.
+     */
+    lastInboundAt?: string;
+    /**
+     * The most recent post-acceptance failure; absent when none has happened since this
+     * connection opened, and never cleared by a later success — an intermittent failure would
+     * otherwise be erased by the next ordinary message. `at` is what says how stale it is.
+     */
+    lastDeliveryError?: MessagingDeliveryError;
+    /**
+     * The most recent CONNECTION failure, kept after the connection recovers — unlike
+     * `lastError`, which belongs to the `error` state and is gone the moment the state leaves it.
+     *
+     * A connection that fails and recovers repeatedly (a second program polling the same bot
+     * token takes turns with this one) reads as `connected` in any snapshot taken between
+     * flaps, with nothing at all to show for the failures in between. This is what is left
+     * behind — for the life of the connection, like the two above it.
+     */
+    lastConnectionError?: {
+        at: string;
+        detail: string;
+    };
+}
+/**
+ * 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;
+    /** 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 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 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 {
+interface FeishuBindingInfo extends MessagingBindingCommon {
     channel: "feishu";
-    sessionId: string;
     appId: string;
     /**
      * Masked app secret (site-wide mask rule: `***`, or `first4…last4` for long values);
@@ -1468,20 +1609,10 @@ interface FeishuBindingInfo {
      */
     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;
-    /**
-     * 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.
-     */
-    lastChatKnown: boolean;
-    createdAt: string;
-    updatedAt: 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;
     /**
@@ -1490,18 +1621,78 @@ 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;
+}
+/**
+ * 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";
+    /** The bot's App ID — the channel-scoped account identity, never secret. */
+    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;
     /**
-     * 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.
+     * 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
+     * platform's passive-reply budget rather than the channel-neutral ceiling, so it yields
+     * far fewer messages here than on the other channels.
+     */
+    linePerMessage: boolean;
+    /**
+     * 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
+     * every-message relay spends one per completed message. But a passive reply is accepted
+     * only for a few minutes after the inbound message that funds it, and holding the reply
+     * to the run's end spends that window on the run: a run that outlives it delivers nothing
+     * at all, where the every-message relay would have sent whatever completed inside it.
+     */
+    finalReplyOnly: boolean;
+    /**
+     * 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.
      */
     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;
+type MessagingBindingInfo = FeishuBindingInfo | TelegramBindingInfo | QQBindingInfo | WeChatBindingInfo;
 /** One saved channel config with its event-connection runtime status. */
 interface MessagingChannelState {
     binding: MessagingBindingInfo;
@@ -1526,12 +1717,37 @@ interface TelegramBindingResponse {
     binding: TelegramBindingInfo | null;
     status: MessagingRuntimeStatus;
 }
+/** GET / PUT …/messaging/qq response (the QQ narrowing of the same envelope). */
+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;
@@ -1546,9 +1762,10 @@ interface FeishuBindingPutRequest {
 /**
  * PUT …/messaging/telegram — saves the credential ONLY, same contract as the Feishu PUT
  * (an enabled binding's connector restarts with the new token; the connection toggle is
- * POST …/state). 409 `telegram_bot_in_use` when the token's bot id is bound elsewhere.
+ * 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;
     /**
@@ -1558,11 +1775,46 @@ interface TelegramBindingPutRequest {
      */
     clearBotToken?: boolean;
 }
+/**
+ * PUT …/messaging/qq — saves the credential pair ONLY, same contract as the Feishu PUT
+ * (an enabled binding's connector restarts with the new credentials; the connection toggle
+ * 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 extends MessagingDeliveryPatch {
+    appId: string;
+    /** Omitted or blank keeps the stored secret (the masked value never round-trips). */
+    appSecret?: string;
+    /**
+     * Drops the STORED secret (the models-page clear idiom; a typed `appSecret` wins over
+     * 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 {
+    /**
+     * 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.
+     */
+    clearBotToken?: boolean;
+}
 /**
  * POST …/messaging/<channel>/state — enable connects with the STORED credentials,
- * disable terminates. Enabling is mutually exclusive per Session: while another channel
- * is enabled it answers 409 `another_channel_enabled` (turn that one off first), and a
- * config whose secret is missing answers its channel's 400 `*_required`.
+ * disable terminates. Enabling is what binds the bot account to this Session, and it is
+ * mutually exclusive twice over: while another channel of the same Session is enabled it
+ * answers 409 `another_channel_enabled`, and while another SESSION has the same account
+ * enabled it answers 409 `account_enabled_elsewhere` (both say: turn that one off first).
+ * A config whose secret is missing answers its channel's 400 `*_required`.
  */
 interface MessagingBindingStateRequest {
     enabled: boolean;
@@ -1589,11 +1841,145 @@ interface TelegramTestResponse {
     latencyMs?: number;
     /** The bot's `@username`, when the API reports one. */
     botUsername?: string;
+    /**
+     * True when @BotFather's **Group Privacy** is ON for this bot, which is the default. In
+     * every group where the bot is not an administrator it then receives only a command
+     * addressed to it or a reply to one of its own messages — an ordinary sentence is never
+     * delivered, so a binding that answers fine in a direct chat stays silent there. The
+     * setting is account-wide and Telegram overrides it for a group the bot administers, so
+     * this reports the setting and never the outcome in any particular group. Absent when the
+     * API did not report the setting; never inferred.
+     */
+    groupPrivacy?: boolean;
     error?: string;
 }
+/** POST …/messaging/qq/test — draft values; each omitted field falls back to the stored binding. */
+interface QQTestRequest {
+    appId?: string;
+    appSecret?: string;
+}
+/**
+ * QQ credential-test outcome. There is no account label: the platform's only credential
+ * call is the access-token exchange, which identifies nothing beyond the App ID that was
+ * sent to it.
+ */
+interface QQTestResponse {
+    ok: boolean;
+    latencyMs?: number;
+    error?: string;
+}
+/**
+ * POST …/messaging/qq/scan — starts a scan-to-connect flow: the server registers a bind
+ * task under a fresh AES key it keeps to itself, and answers with what the browser may
+ * know. The key is absent from this type on purpose — it decrypts the App Secret, so it
+ * never leaves the server (the same rule that keeps a stored secret from round-tripping).
+ */
+interface QQScanStartResponse {
+    /** Opaque bind-task handle, passed back to the poll endpoint. */
+    taskId: string;
+    /** The URL to ENCODE into a QR code. It is opened by the QQ app, never fetched by the browser. */
+    qrUrl: string;
+    /** How often to poll, in milliseconds (the interval the protocol is designed around). */
+    pollMs: number;
+}
+/**
+ * POST …/messaging/qq/scan/poll — one step of the scan. `pending` means keep polling,
+ * `expired` means start a new task and show a new QR, and `completed` means the server has
+ * already decrypted the App Secret and SAVED the binding: `appId` names the bot that landed.
+ * 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, was already
+ * resolved, or is being resolved by a poll still in flight answers 404
+ * `qq_scan_task_unknown`: the task is claimed by one poll, so a client whose interval fires
+ * before the previous request came back binds once rather than once per overlapping poll.
+ */
+interface QQScanPollResponse {
+    status: "none" | "pending" | "completed" | "expired";
+    /** The bound bot's App ID; present only on `completed`. Never the secret. */
+    appId?: string;
+    /** 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` before one exists).
+ * `feishu_no_chat` / `telegram_no_chat` / `qq_no_chat` before one exists). On QQ this can
+ * still fail with 502 afterwards: the platform accepts only replies to a message sent from
+ * QQ minutes earlier, so a known chat does not mean a deliverable one.
  */
 interface MessagingTestMessageResponse {
     ok: true;
@@ -2144,6 +2530,29 @@ 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
+ * colour, and `GET /usage/errors` takes one of them as its `kind` filter.
+ */
+type UsageErrorKind = "unexpected" | "expected";
 /** Occurrence count of an error for a given source · code (the "most common" metric in the stats center's error panel). */
 interface UsageErrorCount {
     source: string;
@@ -2169,6 +2578,15 @@ interface UsageErrorItem {
  */
 interface UsageErrors {
     total: number;
+    /**
+     * How many of {@link total} a clear would actually take (see {@link UsageErrorsClearResponse}).
+     *
+     * The same as `total` for an ordinary member, and smaller for an admin, whose reads include
+     * unattributed rows that no Project-scoped clear removes. The confirmation is the only place
+     * this matters, and it is the place it matters most: an irreversible delete has to name the
+     * number that will really go, not the number on screen.
+     */
+    clearable: 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). */
@@ -2180,13 +2598,28 @@ 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.
+ * 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
+ * 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.
  */
 interface UsageErrorsPage {
     items: UsageErrorItem[];
     /** 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 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. Errors with no Project attribution are never included, whoever asks: they
+ * belong to no Project and are surfaced in every Project's admin view.
+ */
+interface UsageErrorsClearResponse {
+    /** How many rows were deleted, so the caller can say what went instead of guessing. */
+    deleted: number;
+}
 interface UsageResponse {
     summary: {
         today: UsageBucket;
@@ -2491,5 +2924,61 @@ interface UpdateRunResponse {
     /** True when the install changed (or was already current): restart the service to run the new version. */
     needsRestart: boolean;
 }
+/** 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. */
+    id: string;
+    /**
+     * The alias exactly as written in the config. The list is the config text and nothing
+     * else — no `ssh -G`, no processes, no network — so a config declaring hundreds of hosts
+     * costs one file read; an alias is resolved only when it is actually installed to.
+     */
+    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.
+     *
+     * 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
+     * remote instead would cost an ssh round trip per host at page load, which is the price
+     * the config-text list exists to avoid.
+     */
+    installed: {
+        version: string;
+        at: string;
+    } | null;
+}
+/**
+ * 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.
+ */
+interface MachineInstallJob {
+    machineId: string;
+    alias: string;
+    running: boolean;
+    log: string[];
+    result: null | {
+        ok: true;
+        kind: "installed" | "already-installed";
+        version: string | null;
+    } | {
+        ok: false;
+        step: string;
+        message: 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.
+     */
+    imageVersion: string | null;
+    job: MachineInstallJob | 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, McpServerTestResponse, MeResponse, MemberAddRequest, MemberAddResponse, MemberInfo, MembersResponse, MemoryFileInfo, MemoryFileResponse, MemoryFilesResponse, MemoryImportMode, MemoryImportRequest, MemoryImportResponse, MemoryOverviewResponse, MemoryScopeExport, MemoryScopeInfo, MemoryTransferFile, MessagesLiveTail, MessagesPageInfo, MessagesResponse, MessagingBindingInfo, MessagingBindingStateRequest, MessagingBindingsResponse, MessagingChannel, MessagingChannelState, 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, 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, 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, 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, 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, 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, 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, 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 };