@prismshadow/penguin-server 0.2.6 → 0.2.8

package/README.md

@@ -21,7 +21,7 @@ The full route tables and the SSE protocol are documented in the [Server API ref
 | `PENGUIN_HOME` | Data root (shared with SDK/CLI) | `~/.penguin/data` |
 | `PENGUIN_WEB_DB` | SQLite file path | `<root>/web.db` |
 | `PENGUIN_WEB_DIST` | Front-end build dir (static hosting + SPA fallback when present) | `../web/dist`, or the bundled `web-dist/` in the npm package |
-| `PENGUIN_TRUST_PROXY` | Trust `x-forwarded-proto` for the hot-update network gate (`1` to enable) — only behind a reverse proxy that sets/strips the header itself | unset (untrusted) |
+| `PENGUIN_TRUST_PROXY` | Trust `x-forwarded-proto` (`1` to enable): it opens the hot-update network gate over proxied HTTPS and marks session cookies `Secure` — only behind a reverse proxy that sets/strips the header itself | unset (untrusted) |
 
 `.env` in the process cwd is loaded automatically.
 
@@ -39,10 +39,10 @@ pnpm --filter @prismshadow/penguin-server start   # node dist/index.js
 
 - **CSRF**: session cookie is `SameSite=Lax` and writes accept only `Content-Type: application/json`; no CSRF token yet.
 - **Login throttling**: per-username exponential backoff after 5 consecutive failures (1s doubling to a 60s cap, `429 too_many_attempts` inside the window, reset on success; in-memory, so a restart clears it). Unknown usernames are throttled identically, so it is not an account-existence oracle. A reverse proxy can still add IP-level limits for public deployments.
-- **Built-in admin `admin` starts with a random initial password** of the form `penguin-1234`, printed once to the server console at seed time (`PENGUIN_SEED_ADMIN_PASSWORD` pins it for tests/e2e): change it immediately (a banner keeps reminding until you do).
-- Passwords use `node:crypto` scrypt (`scrypt$N$r$p$salt$hash`, timingSafeEqual); login sessions renew on a 7-day sliding window; the DB stores only the token's sha256.
+- **Built-in admin `admin` is seeded with a random password that is hashed and discarded unseen** (`PENGUIN_SEED_ADMIN_PASSWORD` pins it for tests/e2e). Until a password is set, every start prints a first-login link that signs the browser in to choose one; a banner keeps reminding until the initial flag clears.
+- Passwords use `node:crypto` scrypt (`scrypt$N$r$p$salt$hash`, timingSafeEqual). A session is a row in `auth_sessions` (the cookie holds a random token, the row its sha256); it survives a restart, renews the expiry in place, and logout deletes the row. Sessions run 30 days with sliding renewal.
 - Model credentials live in the Project's hidden 0600 config file; the API always masks them.
 - **Terminals are a shell as the OS account running the server**, i.e. the most privileged thing the API hands out — they are not Project-scoped. A terminal is only visible to the account that created it (someone else's id answers 404, not 403), and the stream WebSocket checks `Origin` on top of the session cookie because a WebSocket handshake is not subject to CORS. Do not expose a deployment with terminals enabled to accounts you would not give SSH.
-- Behind a reverse proxy, disable response buffering for SSE paths (the server already sends `X-Accel-Buffering: no`) and forward `x-forwarded-proto` to enable Secure cookies.
+- Behind a reverse proxy, disable response buffering for SSE paths (the server already sends `X-Accel-Buffering: no`), and set `PENGUIN_TRUST_PROXY=1` with `x-forwarded-proto` forwarded so session cookies are marked `Secure` — the header alone is not trusted, so without the opt-in an HTTPS deployment issues its cookies without the flag.
 
 Part of [PenguinHarness](https://github.com/Prism-Shadow/penguin-harness) · Apache-2.0

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
@@ -679,6 +701,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 +733,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;
 }
@@ -1397,9 +1434,10 @@ interface SubagentMessageResponse {
  * DELETE /api/sessions/:id/follow-ups/:followUpId: the withdrawn message's original content,
  * for the composer to restore into the input box for editing and resending (#287). File
  * attachments are read back from the Session scratchpad (then deleted from it); one that
- * disappeared meanwhile is omitted rather than failing the recall. 409 `not_pending` when
- * the entry is no longer queued — steering already delivered to the model, or a follow-up
- * already auto-started (or unknown id either way).
+ * disappeared meanwhile is omitted rather than failing the recall. 409 when the entry is no
+ * longer queued, with a code per endpoint because the reasons read differently to the user:
+ * `not_pending` — the steering message already reached the model; `follow_up_started` — the
+ * follow-up already auto-started as a task of its own (unknown ids land on the same code).
  */
 interface RecalledMessageResponse {
     text: string;
@@ -1445,15 +1483,64 @@ interface SessionProcessesResponse {
     processes: SessionProcessInfo[];
 }
 /** Messaging channels a Session can bind to. */
-type MessagingChannel = "feishu" | "telegram";
+type MessagingChannel = "feishu" | "telegram" | "qq";
 /** 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;
+    };
 }
 /** The stored Feishu config, secret masked (plaintext never leaves the server). */
 interface FeishuBindingInfo {
@@ -1469,6 +1556,26 @@ interface FeishuBindingInfo {
     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;
+    /**
+     * 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 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.
@@ -1491,6 +1598,26 @@ interface TelegramBindingInfo {
     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.
@@ -1499,8 +1626,61 @@ interface TelegramBindingInfo {
     createdAt: string;
     updatedAt: string;
 }
+/** The stored QQ config, secret masked (plaintext never leaves the server). */
+interface QQBindingInfo {
+    channel: "qq";
+    sessionId: string;
+    /** 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;
+    /** 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
+     * 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,
+     * 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.
+     *
+     * 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 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.
+     */
+    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;
+}
 /** A Session's saved config for one messaging channel (`channel` is the discriminant). */
-type MessagingBindingInfo = FeishuBindingInfo | TelegramBindingInfo;
+type MessagingBindingInfo = FeishuBindingInfo | TelegramBindingInfo | QQBindingInfo;
 /** One saved channel config with its event-connection runtime status. */
 interface MessagingChannelState {
     binding: MessagingBindingInfo;
@@ -1525,6 +1705,11 @@ 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;
+}
 /**
  * PUT …/messaging/feishu — saves credentials/config ONLY, never flipping the connection
  * (exception: an enabled binding's connector restarts with the new credentials so stored
@@ -1541,11 +1726,27 @@ 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
  * (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 {
     /** Omitted or blank keeps the stored token (the masked value never round-trips). */
@@ -1556,12 +1757,60 @@ 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
+ * (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 {
+    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;
+    /**
+     * 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.
+     */
+    renderMarkdown?: 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;
@@ -1588,11 +1837,69 @@ 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;
+}
 /**
  * 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;
@@ -2143,6 +2450,12 @@ interface UsageModelSeries extends UsageEntitySeriesCounts {
     provider: string;
     modelId: string;
 }
+/**
+ * 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;
@@ -2179,7 +2492,10 @@ 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[];
@@ -2490,5 +2806,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, 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 };

package/dist/auth-token.d.ts

@@ -0,0 +1,29 @@
+/** An hour: long enough for a controller to finish, short enough to forget. */
+declare const CLI_TOKEN_TTL_MS: number;
+/**
+ * Ceiling on a caller-supplied `--ttl-seconds`, matching the default session TTL (config.ts):
+ * a token that lives in a file must not outlive an ordinary browser session.
+ */
+declare const CLI_TOKEN_MAX_TTL_MS: number;
+type MintTokenResult = {
+    outcome: "minted";
+    token: string;
+    userId: string;
+    expiresAt: string;
+}
+/** No web.db on this root — the server has never run here, so there is no account to mint for. */
+ | {
+    outcome: "no_server";
+} | {
+    outcome: "failed";
+    detail: string;
+};
+/** Issues an API session token for the data root at `root`. */
+declare function mintApiToken(root: string, opts?: {
+    userId?: string;
+    ttlMs?: number;
+    dbPath?: string;
+    now?: Date;
+}): MintTokenResult;
+
+export { CLI_TOKEN_MAX_TTL_MS, CLI_TOKEN_TTL_MS, type MintTokenResult, mintApiToken };