@prismshadow/penguin-server 0.2.3 → 0.2.5

package/dist/api/types.d.ts

@@ -1,5 +1,6 @@
 import { OmniMessage, ToolCallPayload, CompactionMode } from '@prismshadow/penguin-core/omnimessage';
 import { ThinkingLevelName, ToolDefinitionConfig, MCPServerConfig } from '@prismshadow/penguin-core/interfaces';
+import { VersionReport } from '@prismshadow/penguin-core';
 
 /**
  * Web API DTO contract — request/response types shared between server routes and the
@@ -69,9 +70,10 @@ interface MeResponse {
      * 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) may omit it. "token" marks a request authenticated by the local API token's
+     * Bearer header (the CLI and agent-driven calls).
      */
-    sessionVia: "password" | "desktop";
+    sessionVia: "password" | "desktop" | "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
@@ -198,20 +200,33 @@ interface ServerSettingsUpdateRequest {
      */
     attachmentTotalMb?: number;
 }
+/**
+ * One draft-screen shortcut: a prompt the user wrote, filed under a name they chose. Clicking it
+ * fills the composer exactly like a built-in example does, and sends nothing. Deliberately holds
+ * no Skill list — a saved prompt is not authored against a known Skill catalog the way a shipped
+ * example is, and the Agent it will run under is picked after the click.
+ */
+interface DraftShortcut {
+    /** Stable client-generated id: what an edit or a delete addresses the row by. Unique per user. */
+    id: string;
+    title: string;
+    prompt: string;
+}
 /** User UI preferences (SQLite ui_prefs, free-form JSON; known keys declared here). */
 interface UiPrefs {
     theme?: "light" | "dark";
     lastProjectId?: string;
     /** Whether the "no API key configured" guide has already been shown: once ever (on first visit to the chat page). */
     credentialGuideSeen?: boolean;
-    /**
-     * Also list CLI-created Sessions in the sidebar (`cli=1` on the sessions list). Default
-     * off: the list then serves web rows straight from the DB, with no Trace-directory
-     * scanning (#139).
-     */
-    showCliSessions?: boolean;
     /** The initial-password notice banner (app layout) was permanently dismissed by the user. */
     initialPasswordBannerDismissed?: boolean;
+    /**
+     * 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
+     * services/draft-shortcuts.ts — count, title length and prompt length — because this is the one
+     * known key holding user-authored text rather than a flag or an id.
+     */
+    draftShortcuts?: DraftShortcut[];
     [key: string]: unknown;
 }
 interface PrefsResponse {
@@ -319,6 +334,14 @@ interface ModelInfo {
     pricing?: ModelPricingDto;
     /** Environment variable name to fall back to when api_key is empty (e.g. ANTHROPIC_API_KEY); unset if no known fallback. */
     envKey?: string;
+    /**
+     * Masked preview (same rule as `credential.apiKeyMasked`) of the value the server process
+     * currently holds for `envKey` — the plaintext is never serialized. Reported only for
+     * first-party official entries (vendor group, catalog shape unmodified); gateway, custom
+     * and user-defined groups never carry it. Absent = the variable is unset or empty, or the
+     * entry is not first-party.
+     */
+    envKeyMasked?: string;
     credential?: CredentialInfo;
     isDefault: boolean;
 }
@@ -501,6 +524,29 @@ interface ModelProtocolDetectResponse {
     detected?: string;
     probes: ModelProtocolProbeDto[];
 }
+/**
+ * Endpoint model listing (POST /api/projects/:p/models/list, owner): given a base URL and
+ * the protocol `/detect` reported, returns every model id the endpoint serves (AgentHub's
+ * `listModels()` on the routed client). Used by the add-group dialog to import a provider's
+ * whole listing in one go; the ids come back in the endpoint's own order.
+ */
+interface EndpointModelListRequest {
+    /** Endpoint base URL (as typed in the add-group dialog). */
+    baseUrl: string;
+    /** AgentHub client type to speak (normally a detected generic protocol; whole-endpoint listings need one). */
+    clientType: string;
+    /** Newly entered API key (plaintext); omitted = the SDK's environment fallback for the protocol. */
+    apiKey?: string;
+}
+/** Listing outcome: model ids on success, a truncated provider/SDK reason otherwise. */
+interface EndpointModelListResponse {
+    ok: boolean;
+    /** The model ids the endpoint serves, in the order the endpoint returned them (ok only). */
+    models?: string[];
+    /** The routed client has no models endpoint (AgentHub UnsupportedOperationError) — callers offer the manual path. */
+    unsupported?: boolean;
+    message?: string;
+}
 /**
  * PUT /api/projects/:p/models/default (owner): narrow default-model switch — flips the same
  * top-level `default_model` the models page's whole-table PUT writes, without resending the
@@ -515,6 +561,53 @@ interface DefaultModelUpdateRequest {
 interface DefaultModelResponse {
     defaultModel: ModelRefDto;
 }
+/**
+ * How the authorization code travels back. `callback` sends the browser to a harness URL
+ * the provider redirects to; `manual` asks the provider for a one-time code the user copies
+ * back by hand, for the case where that redirect cannot reach the harness.
+ */
+type ModelOAuthMode = "callback" | "manual";
+/**
+ * POST /api/projects/:p/model-oauth/start (owner): opens a flow for one provider group.
+ * The group must declare an authorization flow in the built-in catalog — the endpoints it
+ * uses come from there, never from this request.
+ */
+interface ModelOAuthStartRequest {
+    /** Provider group id (must be a catalog group that publishes a key-minting flow). */
+    provider: string;
+    /** Defaults to `callback`. */
+    mode?: ModelOAuthMode;
+}
+/** The opaque flow handle plus the page to send the user to. No secret of the flow's is included. */
+interface ModelOAuthStartResponse {
+    flowId: string;
+    authorizeUrl: string;
+}
+/** Why a flow failed, as a code the frontend phrases; never carries a code, a verifier or a key. */
+type ModelOAuthErrorCode = "invalid_request" | "code_rejected" | "upstream_failed" | "unreachable" | "apply_failed";
+/**
+ * GET /api/projects/:p/model-oauth/:flowId (owner): where a flow stands. Unknown, expired,
+ * and other users' flows are all 404 alike.
+ */
+interface ModelOAuthStatusResponse {
+    status: "pending" | "done" | "error";
+    /** The provider group the flow mints a key for. */
+    provider: string;
+    error?: ModelOAuthErrorCode;
+}
+/**
+ * POST /api/projects/:p/model-oauth/:flowId/code (owner): redeems a code the user pasted,
+ * the manual counterpart of the redirect callback. A flow is single-use either way.
+ */
+interface ModelOAuthCodeRequest {
+    code: string;
+}
+/** Redemption outcome; `applied` counts the models the minted key was written to. */
+interface ModelOAuthCodeResponse {
+    ok: boolean;
+    applied?: number;
+    error?: ModelOAuthErrorCode;
+}
 /**
  * Per-Project new-chat defaults: prefill for the chat draft page. Every key is optional —
  * an absent key means "not set" (the pre-existing behavior). Serves as the GET response,
@@ -537,6 +630,36 @@ interface ChatDefaultsDto {
      */
     thinkingLevel?: Exclude<ThinkingLevelName, "none">;
 }
+/**
+ * One deny rule of the sandbox command policy — plain project-editable data. The factory
+ * rules are seeded into new projects and carry no special status thereafter: every rule
+ * can be edited, disabled, or deleted.
+ */
+interface CommandPolicyRuleDto {
+    name: string;
+    /** JavaScript regex source, matched against the whitespace-normalized command. */
+    pattern: string;
+    /** What the rule catches (free text). */
+    description?: string;
+    /** Per-rule switch, effective value (defaults on). */
+    enabled: boolean;
+}
+/**
+ * Per-Project sandbox command policy: deny rules for shell commands, evaluated ahead of
+ * the approval mode (a hit is denied even under allow-all). Serves as the GET response and
+ * the PUT response. The PUT request body carries `enabled?` plus the full `rules` list
+ * (required — a PUT always materializes the list into the config, model-presets style);
+ * per-rule `enabled` may be omitted there and defaults to on. Owner-only to write; any
+ * member may read.
+ */
+interface CommandPolicyDto {
+    /** Effective master switch; an absent stored value reads as true (the policy defaults on). */
+    enabled: boolean;
+    /** The effective rule list — the factory set when the project predates seeding and has none stored. */
+    rules: CommandPolicyRuleDto[];
+    /** The factory set, served for the settings UI's "restore defaults". */
+    defaultRules: CommandPolicyRuleDto[];
+}
 /** Read-only vault entry display: key name + masked value; plaintext is never sent. */
 interface VaultEntryInfo {
     key: string;
@@ -593,6 +716,28 @@ interface AgentCreateRequest {
     /** Display name; defaults to agentId. */
     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.
+     */
+    skills?: 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
+     * back from `.agents/skills` / `.claude/skills` at creation time. Both are required together,
+     * and every name must still be there (404 `unknown_skill` otherwise, before anything is
+     * created) — the client sends names, never Skill content.
+     */
+    skillsDirectory?: string;
+    directorySkills?: string[];
+    /**
+     * 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.
+     * Explicit `name` / `description` override the package's values; absent ones keep them.
+     */
+    dataBase64?: string;
 }
 interface AgentCreateResponse {
     agent: AgentSummary;
@@ -685,13 +830,13 @@ interface AgentConfigResponse {
 }
 /**
  * POST …/config/kernel-update result: the smart merge's outcome (core's applyKernelUpdate).
- * Paths are dotted config leaves (`system_prompt`, `memory.prompt`, `tools.builtin.<name>`…)
- * in defaults-traversal order; the client maps them to display names.
+ * The entries are Agent settings **tabs** (`prompt`, `runtime`, `tools`, `skills`, `memory`,
+ * `vault`, `schedules`) in the settings page's tab order; the client maps them to tab labels.
  */
 interface AgentKernelUpdateResponse {
-    /** Leaves advanced to the new default (previously missing, or an untouched old default). */
+    /** Tabs advanced to the current defaults (previously absent, or an untouched old default). */
     advanced: string[];
-    /** Leaves kept because the stored value matches no recorded defaults generation (user customizations, kept conservatively). */
+    /** Tabs kept whole because they match no recorded default (customized, kept conservatively). */
     kept: string[];
     /** The kernel stamp written (the current defaults generation). */
     kernelVersion: string;
@@ -744,6 +889,8 @@ interface MemoryScopeInfo {
     workspacePath?: string;
     /** Number of Markdown topic files in the directory (the `MEMORY.md` index not counted). */
     fileCount: number;
+    /** Whether the directory holds a `MEMORY.md` index, so an import confirmation can say whether one would be replaced. */
+    hasIndex: boolean;
     /** Most recent topic-file mtime in the directory (ISO 8601); unset when the directory holds no topic file. */
     updatedAt?: string;
 }
@@ -783,6 +930,64 @@ interface MemoryFileResponse {
     file: MemoryFileInfo;
     content: string;
 }
+/** One topic file inside a transfer document: the name it had in its scope, and its whole text. */
+interface MemoryTransferFile {
+    /** File name inside the scope directory, e.g. `prefers-pnpm.md` — a name, never a path. */
+    name: string;
+    /** The file's full Markdown text, frontmatter included. */
+    content: string;
+}
+/**
+ * GET …/memory/scopes/:key/export, and the body a POST …/import carries back: everything one
+ * scope holds, as one JSON document — the topic files and the scope's own `MEMORY.md`.
+ */
+interface MemoryScopeExport {
+    /** Format marker, so a foreign JSON file is refused with a clear reason rather than half-imported. */
+    format: "penguin-memory-scope";
+    /** Document version. A reader accepts exactly this; a later format bumps it and states its own compatibility. */
+    version: 1;
+    /** The scope this was exported from. Informational: an import writes into the scope its URL names. */
+    scopeKey: string;
+    kind: MemoryScopeInfo["kind"];
+    /** The Workspace the source scope stood for, when it had a `.workspace` marker. */
+    workspacePath?: string;
+    /** When the document was produced (ISO 8601). */
+    exportedAt: string;
+    /** The scope's `MEMORY.md`, or null when the scope has none. Only the index reaches the model's context. */
+    index: string | null;
+    files: MemoryTransferFile[];
+}
+/**
+ * What an import does with a name the target scope already holds:
+ *   - `skip` — keep what is on disk, write only names the scope does not have (destroys nothing);
+ *   - `overwrite` — replace a same-named file's content;
+ *   - `replace` — additionally delete every topic file the document does not carry.
+ * The two destructive modes require `confirm`.
+ */
+type MemoryImportMode = "skip" | "overwrite" | "replace";
+/** POST …/memory/scopes/:key/import */
+interface MemoryImportRequest {
+    /** Defaults to `skip`. */
+    mode?: MemoryImportMode;
+    /** Required by `overwrite` and `replace`; without it they are refused with 409 `memory_import_confirm_required`. */
+    confirm?: boolean;
+    payload: MemoryScopeExport;
+}
+/** What one import did, name by name, so the UI can report it rather than claim success. */
+interface MemoryImportResponse {
+    scopeKey: string;
+    mode: MemoryImportMode;
+    /** Names written that the scope did not have. */
+    added: string[];
+    /** Names whose existing content was replaced. */
+    overwritten: string[];
+    /** Names left untouched because the scope already had them (`skip` only). */
+    skipped: string[];
+    /** Names deleted because `replace` dropped everything the document did not carry. */
+    removed: string[];
+    /** Whether the scope's `MEMORY.md` was written or extended. */
+    indexWritten: boolean;
+}
 interface SessionInfo {
     sessionId: string;
     projectId: string;
@@ -839,6 +1044,8 @@ interface SessionInfo {
      * history itself when it needs it.
      */
     tracePath?: string;
+    /** Present when the Session has an ENABLED messaging binding: its channel (the sidebar row's per-channel indicator). */
+    messagingChannel?: MessagingChannel;
 }
 /**
  * Session list category, the sidebar's four-way split applied server-side: archived wins
@@ -874,6 +1081,17 @@ interface DirListResponse {
     /** Subdirectory list (sorted by name, files excluded). */
     entries: DirEntryInfo[];
 }
+/** One Skill found in a picked directory: metadata plus which of the two layouts it came from. */
+interface DirectorySkillItem extends SkillMetadataItem {
+    /** `.agents/skills` or `.claude/skills` — shown so the origin of an offered Skill is visible. */
+    source: string;
+}
+interface DirectorySkillsResponse {
+    /** Absolute path that was scanned (realpath). */
+    path: string;
+    /** Installable Skills found under the directory's Skill layouts; empty when it carries none. */
+    skills: DirectorySkillItem[];
+}
 interface SessionCreateRequest {
     /** Upstream id of the session's model; always sent together with provider. Omit both for the Project's default Model. */
     modelId?: string;
@@ -887,6 +1105,12 @@ interface SessionCreateRequest {
     workspace?: string;
     /** Defaults to allow-all. */
     approvalMode?: ApprovalMode;
+    /**
+     * Creating-client hint stored on the Session row: "cli" when the CLI creates the
+     * Session through the API; defaults to "web". Informational provenance only — lists
+     * serve every row regardless of client.
+     */
+    client?: "web" | "cli";
 }
 interface SessionCreateResponse {
     session: SessionInfo;
@@ -1144,6 +1368,30 @@ interface PendingFollowUpInfo {
     /** Number of file attachments in the queued input. */
     files: number;
 }
+/**
+ * One live subagent child of a session's runtime, carried on `task_state` events and the SSE
+ * subscribe snapshot: the child Session id (the origin hop the stream already correlates by),
+ * its background registry handle (null while it only lives inside a foreground collect
+ * window), and whether a round is currently running. Only an ACTIVE parent runtime reports
+ * children — after a server restart the in-process children are gone, and the empty list is
+ * the truth.
+ */
+interface SubagentRuntimeInfo {
+    sessionId: string;
+    subagentId: string | null;
+    running: boolean;
+}
+/**
+ * Response of POST /api/sessions/:sessionId/subagents/:childSessionId/message — a user input
+ * on the child, whatever its state: `steered` = queued as a mid-run interjection, `started` =
+ * began a follow-up run on the idle child, `resumed` = the released child session was revived
+ * (resume-session semantics) and the message began its next round. The failure shapes are
+ * HTTP statuses instead: 404 when the child's session record does not exist or cannot be
+ * revived, 409 when the child cannot take the message right now.
+ */
+interface SubagentMessageResponse {
+    outcome: "steered" | "started" | "resumed";
+}
 /**
  * Response of the two recall endpoints — DELETE /api/sessions/:id/steer/:steerId and
  * DELETE /api/sessions/:id/follow-ups/:followUpId: the withdrawn message's original content,
@@ -1190,10 +1438,165 @@ interface SessionProcessInfo {
     cwd: string;
     startedAt: string;
     running: boolean;
+    /** The service the process serves, when detected: the last local URL its output printed, else an origin probed from its listening ports. */
+    serviceUrl?: string;
 }
 interface SessionProcessesResponse {
     processes: SessionProcessInfo[];
 }
+/** Messaging channels a Session can bind to. */
+type MessagingChannel = "feishu" | "telegram";
+/** Event-connection runtime state of one binding (kept in memory, not persisted). */
+type MessagingRuntimeState = "disconnected" | "connecting" | "connected" | "error";
+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;
+}
+/** The stored Feishu config, secret masked (plaintext never leaves the server). */
+interface FeishuBindingInfo {
+    channel: "feishu";
+    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;
+    /**
+     * 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 {
+    channel: "telegram";
+    sessionId: string;
+    /** The numeric bot id (the token's half before the colon) — the channel-scoped account identity, never secret. */
+    botId: string;
+    /**
+     * Masked bot token (site-wide mask rule: `***`, or `first4…last4` for long values);
+     * absent when no token is stored (cleared) — the binding cannot be enabled until one
+     * 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;
+    /**
+     * 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;
+}
+/** A Session's saved config for one messaging channel (`channel` is the discriminant). */
+type MessagingBindingInfo = FeishuBindingInfo | TelegramBindingInfo;
+/** One saved channel config with its event-connection runtime status. */
+interface MessagingChannelState {
+    binding: MessagingBindingInfo;
+    /** Only the enabled channel's connection is ever anything but disconnected. */
+    status: MessagingRuntimeStatus;
+}
+/**
+ * GET …/messaging response — the channel-agnostic read the channel-aware binding editor
+ * loads: EVERY saved channel config (masked) with its runtime status. A Session may keep
+ * both channels saved; at most one of them is enabled.
+ */
+interface MessagingBindingsResponse {
+    bindings: MessagingChannelState[];
+}
+/** GET / PUT …/messaging/feishu response: the Feishu config (null = not saved) plus its runtime status. */
+interface FeishuBindingResponse {
+    binding: FeishuBindingInfo | null;
+    status: MessagingRuntimeStatus;
+}
+/** GET / PUT …/messaging/telegram response (the Telegram narrowing of the same envelope). */
+interface TelegramBindingResponse {
+    binding: TelegramBindingInfo | 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 {
+    appId: string;
+    /** Omitted or blank keeps the stored secret (the masked value never round-trips). */
+    appSecret?: string;
+    /** Defaults to https://open.feishu.cn when omitted or blank. */
+    baseDomain?: 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/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.
+ */
+interface TelegramBindingPutRequest {
+    /** Omitted or blank keeps the stored token (the masked value never round-trips). */
+    botToken?: string;
+    /**
+     * Drops the STORED token (the models-page clear idiom; a typed `botToken` wins over
+     * it — and the row keeps its bot identity). Refused with 409
+     * `messaging_disable_before_clear` while the binding is enabled.
+     */
+    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`.
+ */
+interface MessagingBindingStateRequest {
+    enabled: boolean;
+}
+/** POST …/messaging/feishu/test — draft values; each omitted field falls back to the stored binding. */
+interface FeishuTestRequest {
+    appId?: string;
+    appSecret?: string;
+    baseDomain?: string;
+}
+/** Credential-test outcome (an unreachable/rejected credential is `ok:false`, not an HTTP error). */
+interface FeishuTestResponse {
+    ok: boolean;
+    latencyMs?: number;
+    error?: string;
+}
+/** POST …/messaging/telegram/test — a draft token, falling back to the stored binding when omitted. */
+interface TelegramTestRequest {
+    botToken?: string;
+}
+/** Telegram credential-test outcome: success additionally names the bot the token signs in as. */
+interface TelegramTestResponse {
+    ok: boolean;
+    latencyMs?: number;
+    /** The bot's `@username`, when the API reports one. */
+    botUsername?: string;
+    error?: string;
+}
+/**
+ * POST …/messaging/<channel>/test-message — sent to the last known chat (409
+ * `feishu_no_chat` / `telegram_no_chat` before one exists).
+ */
+interface MessagingTestMessageResponse {
+    ok: true;
+}
 /** Docs: /docs/server-api § "Streaming (SSE)". */
 type ServerEvent = 
 /**
@@ -1214,6 +1617,12 @@ type ServerEvent =
     pendingSteering?: PendingSteeringInfo[];
     /** Queued follow-up tasks awaiting auto-start (absent = none): per-entry content + recall handle, alongside the `queued` count. */
     pendingFollowUps?: PendingFollowUpInfo[];
+    /**
+     * Live subagent children of this session's runtime (absent = none): the panel renders
+     * child running marks from this structural liveness instead of parsing tool-output
+     * text. Refreshed on every child run start/settle.
+     */
+    subagents?: SubagentRuntimeInfo[];
 }
 /** The model-generated title after the first turn has been persisted (for in-place list updates). */
  | {
@@ -1332,6 +1741,51 @@ interface TraceFileInfo {
 interface SessionTracesResponse {
     files: TraceFileInfo[];
 }
+/** One tool's share of the context: its calls plus their results. Its *definition* is counted in `toolDefs`, not here. */
+interface ContextToolShare {
+    name: string;
+    tokens: number;
+}
+/**
+ * What the Session's current model context is made of — the part derived from its messages.
+ *
+ * Every token figure is an **estimate** from a character heuristic, not a tokenizer: the
+ * authoritative occupancy is the last `token_usage`'s `request.total`, which says how large the
+ * context is but not what fills it. Consumers should present these as shares of that measured
+ * occupancy rather than as counts of their own.
+ *
+ * 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).
+ */
+interface SessionContextParts {
+    systemPrompt: number;
+    toolDefs: number;
+    userMessages: number;
+    assistantMessages: number;
+    toolRequests: number;
+    toolResults: number;
+    /** Sum of the six parts. */
+    total: number;
+    /** Tools ranked by the context their traffic occupies, descending; at most five. */
+    topTools: ContextToolShare[];
+    /**
+     * 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
+     * carries. The same state in which the chat page's context ring shows `—`.
+     */
+    contextClosed: boolean;
+}
+/** `GET /api/sessions/:id/context`: the message-derived composition plus where compaction will fire. */
+interface SessionContextResponse extends SessionContextParts {
+    /**
+     * Occupancy (tokens) at which this Session's next Request triggers context compaction: the
+     * Agent's configured `compaction.max_context_length`, capped by what the model's context window
+     * leaves room for. Null when compaction is disabled, when the Agent's config could not be read,
+     * or when the derived threshold is not below the window — nothing to mark inside the gauge.
+     */
+    compactionThreshold: number | null;
+}
 interface TraceEventsResponse {
     events: OmniMessage[];
     offset: number;
@@ -1647,35 +2101,47 @@ interface UsageGroupRow {
     cost: number | null;
     hasUncosted: boolean;
 }
-interface UsageTrendPoint {
-    date: string;
-    total: number;
-    cost: number | null;
-    /** Daily Token buckets (for the cost center's "Token Changes" stacked chart: cacheRead/cacheWrite/output). */
+/** Time-series precision for the usage series (`granularity` query parameter). `minute` requires the `fromTs`/`toTs` window bounds. */
+type UsageGranularity = "minute" | "hour" | "day" | "week" | "month";
+/**
+ * One bucket of the usage time series (for the cost center's time-series charts).
+ * Buckets are zero-filled across the whole requested range, so consecutive points
+ * are always adjacent in time. Bucket keys by granularity: minute
+ * `yyyy-mm-ddThh:mm` and hour `yyyy-mm-ddThh:00` (server-local clock), day
+ * `yyyy-mm-dd`, week the ISO week's Monday `yyyy-mm-dd`, month `yyyy-mm`.
+ */
+interface UsageSeriesPoint {
+    bucket: string;
     cacheRead: number;
     cacheWrite: number;
     output: number;
+    total: number;
+    /** Cost converted at query time (USD); null when no priced Model contributed. */
+    cost: number | null;
+    requests: number;
+    /** Successful requests in the bucket. */
+    completed: number;
+    /** Success-rate denominator: all requests minus aborted (a user interruption is not a model failure). */
+    denominator: number;
+}
+/**
+ * One entity's per-bucket request and success counts, aligned index-for-index
+ * with `series` (the requests-and-success-rate chart draws one such entity —
+ * or stacks them all). `denominator` excludes aborted, same as elsewhere.
+ */
+interface UsageEntitySeriesCounts {
+    requests: number[];
+    completed: number[];
+    denominator: number[];
 }
-/** Invocation count per Agent (for the cost center's "Agent Invocation Count" chart). */
-interface UsageAgentCount {
+/** Per-Agent counts per bucket. */
+interface UsageAgentSeries extends UsageEntitySeriesCounts {
     agentId: string;
-    requests: number;
-    total: number;
 }
-/** Request success rate per Model (for the cost center's "Model Success Rate" chart; rows broken down by (provider, modelId)). */
-interface UsageSuccessRate {
+/** Per-Model counts per bucket (entity identity is the (provider, modelId) pair). */
+interface UsageModelSeries extends UsageEntitySeriesCounts {
     provider: string;
     modelId: string;
-    /** Number of successful requests. */
-    completed: number;
-    /** Success rate denominator = all requests − aborted (user-initiated interruption isn't a model failure and shouldn't lower the success rate). */
-    total: number;
-    /** Count of user interruptions (excluded from success rate, shown separately). */
-    aborted: number;
-    /** Failure breakdown (shown on hover; unknown statuses count toward total but not these three). */
-    failed: number;
-    timeout: number;
-    malformed: number;
 }
 /** Occurrence count of an error for a given source · code (the "most common" metric in the stats center's error panel). */
 interface UsageErrorCount {
@@ -1728,12 +2194,27 @@ interface UsageResponse {
     };
     groupBy: UsageGroupBy;
     groups: UsageGroupRow[];
-    /** Daily trend for the last 30 days (includes Token buckets and cost; affected by agent/model filters). */
-    trend: UsageTrendPoint[];
-    /** Invocation count per Agent (affected by date/model filters). */
-    byAgent: UsageAgentCount[];
-    /** Raw success rate counts per Model (affected by date/agent filters). */
-    success: UsageSuccessRate[];
+    /** Effective precision of `series` (the validated `granularity` query parameter; defaults to day). */
+    granularity: UsageGranularity;
+    /**
+     * Usage time series over the requested from/to range (defaulting to the last 30
+     * days), zero-filled at `granularity`; affected by agent/model filters. Carries
+     * everything the time-series charts draw: Token buckets, cost, request count,
+     * and per-bucket success counts.
+     */
+    series: UsageSeriesPoint[];
+    /**
+     * Per-Agent counts per bucket, aligned index-for-index with `series`, sorted
+     * by total requests descending. Unaffected by the agent filter — the by-Agent
+     * chart draws the whole breakdown — but affected by date/model filters.
+     */
+    byAgentSeries: UsageAgentSeries[];
+    /**
+     * Per-Model counts per bucket, aligned index-for-index with `series`, sorted
+     * by total requests descending. Unaffected by the model filter — the by-Model
+     * chart draws the whole breakdown — but affected by date/agent filters.
+     */
+    byModelSeries: UsageModelSeries[];
     /** Server-side error capture stats (affected by date/agent filters; unaffected by model filter). */
     errors: UsageErrors;
     /** List of Agent ids that have appeared in this Project (for the filter dropdown; unaffected by current filters). */
@@ -1884,7 +2365,7 @@ interface SkillMetadataItem {
     icon?: string;
     /** Version number (natural number, frontmatter version; falls back to 1 if invalid). */
     version: number;
-    /** Update date (YYYY-MM-DD, frontmatter updated; defaults to an empty string). */
+    /** Update timestamp (frontmatter updated, ISO 8601 UTC by convention; defaults to an empty string). */
     updated: string;
 }
 interface SkillGroupItem {
@@ -1918,17 +2399,15 @@ interface SkillArchiveInstallRequest {
     /** Replace an already-installed Skill of the same name (deletes its directory first). */
     overwrite?: boolean;
 }
-/** GET /api/version: the running server's release identity (from core's VERSION / BUILD_DATE). */
-interface VersionResponse {
-    version: string;
-    /**
-     * The **running** version's release date (UTC yyyy-mm-dd), stamped into core's
-     * BUILD_DATE at build time by the release workflow — the web's "last updated" date
-     * needs no network. Null for a dev/source build and for releases that predate the
-     * stamping (v0.1.2 and earlier): the UI then shows the version alone.
-     */
-    buildDate: string | null;
-}
+/**
+ * GET /api/version: the running build's identity plus this root's pushed harness, verbatim
+ * from `versionReport()` — the same record `penguin version --json` prints, so the two
+ * cannot drift apart. Field meanings live on {@link VersionReport} and {@link HarnessInfo};
+ * the ones the web reads are `version` and `buildDate` (the stamped release date behind the
+ * sidebar's "last updated", needing no network, and null for a source build or a release
+ * predating the stamping — v0.1.2 and earlier — where the UI shows the version alone).
+ */
+type VersionResponse = VersionReport;
 /**
  * GET /api/version/update-check: newest published release vs the running version.
  * Always HTTP 200 (fail-soft): a lookup failure sets `error` and leaves `latestVersion`
@@ -1952,6 +2431,51 @@ interface UpdateCheckResponse {
     /** Why the lookup failed: unreachable network / GitHub rate limit / unusable response. */
     error?: "network" | "rate_limited" | "bad_response";
 }
+/**
+ * The desktop shell's updater snapshot, pushed to the embedded server over the
+ * 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
+ * check (or its failure) must not hide the actionable "restart to install" step.
+ */
+interface DesktopUpdateStatus {
+    /** Installed shell version (Electron app.getVersion()). */
+    appVersion: string;
+    /**
+     * Bumped by the shell on every updater event it folds, whether or not the visible
+     * state changed. A row-initiated check settles when the seq has moved past its
+     * at-click value and the state is no longer `checking` — snapshot equality can't
+     * 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`). */
+    version?: string;
+    /** Download progress 0–100 (`downloading`). */
+    percent?: number;
+    /** Updater failure text (`error`). */
+    message?: string;
+    /** Why this install form cannot update itself (`unsupported`): dev run, or a Linux install that is not an AppImage (e.g. .deb — the system package manager owns it). */
+    reason?: "dev" | "linux-not-appimage";
+}
+/**
+ * GET /api/desktop/update (desktop-shell sessions only): the latest shell snapshot.
+ * `status` is null until the shell's first push lands (a beat after server start).
+ */
+interface DesktopUpdateStatusResponse {
+    status: DesktopUpdateStatus | null;
+}
+/** Shell → server push over the utilityProcess message channel. */
+interface DesktopUpdaterStatusMessage {
+    type: "desktop-updater-status";
+    status: DesktopUpdateStatus;
+}
+/** Server → shell command over the utilityProcess message channel (relayed from POST /api/desktop/update/check|install). */
+interface DesktopUpdaterCommandMessage {
+    type: "desktop-updater-command";
+    action: "check" | "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
@@ -1967,4 +2491,4 @@ interface UpdateRunResponse {
     needsRestart: boolean;
 }
 
-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, CredentialInfo, DefaultModelResponse, DefaultModelUpdateRequest, DirEntryInfo, DirListResponse, ErrorBody, FilesStatRequest, FilesStatResponse, GoalResponse, GoalServerEvent, GoalStateView, HistoryMessage, McpServerTestResponse, MeResponse, MemberAddRequest, MemberAddResponse, MemberInfo, MembersResponse, MemoryFileInfo, MemoryFileResponse, MemoryFilesResponse, MemoryOverviewResponse, MemoryScopeInfo, MessagesLiveTail, MessagesPageInfo, MessagesResponse, ModelInfo, 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, SessionCreateRequest, SessionCreateResponse, SessionForkRequest, SessionForkResponse, SessionInfo, SessionPatchRequest, SessionProcessInfo, SessionProcessesResponse, SessionResponse, SessionSource, SessionStatus, SessionTracesResponse, SessionsResponse, SkillArchiveInstallRequest, SkillGroupItem, SkillInstallRequest, SkillLibraryResponse, SkillMetadataItem, SteerRequest, TaskCreateRequest, TaskCreateResponse, TaskInputPart, ToolCallSpan, TraceAnalysisResponse, TraceEventsResponse, TraceFileInfo, TraceImportRequest, TraceImportResponse, TraceModelSegment, TraceOtherSpan, TracePosition, TraceTaskStats, TraceToolSpan, UiPrefs, UpdateCheckResponse, UpdateRunResponse, UploadLimits, UsageAgentCount, UsageBucket, UsageErrorCount, UsageErrorItem, UsageErrors, UsageErrorsPage, UsageGroupBy, UsageGroupRow, UsageResponse, UsageSuccessRate, UsageTrendPoint, 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, 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 };