@prismshadow/penguin-server 0.2.4 → 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
@@ -216,12 +218,6 @@ interface UiPrefs {
     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;
     /**
@@ -565,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,
@@ -673,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;
@@ -765,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;
@@ -979,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
@@ -1014,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;
@@ -1027,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;
@@ -1284,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,
@@ -1336,6 +1444,159 @@ interface SessionProcessInfo {
 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 = 
 /**
@@ -1356,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). */
  | {
@@ -1474,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;
@@ -2053,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 {
@@ -2087,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`
@@ -2181,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, CommandPolicyDto, CommandPolicyRuleDto, CredentialInfo, DefaultModelResponse, DefaultModelUpdateRequest, DesktopUpdateStatus, DesktopUpdateStatusResponse, DesktopUpdaterCommandMessage, DesktopUpdaterStatusMessage, DirEntryInfo, DirListResponse, DraftShortcut, EndpointModelListRequest, EndpointModelListResponse, ErrorBody, 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, 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, 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, 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 };

package/dist/chunk-4SXGU7RO.js

@@ -0,0 +1,50 @@
+// src/hmr/manifest.ts
+import fs from "fs";
+import fsp from "fs/promises";
+import path from "path";
+function str(value) {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+async function readHarnessInfo(root) {
+  const manifest = await readManifest(root);
+  if (manifest === null) return null;
+  const bundles = {
+    platform: str(manifest.platform?.bundle),
+    cli: str(manifest.cli?.bundle),
+    web: str(manifest.web?.manifest)
+  };
+  if (bundles.platform === null && bundles.cli === null && bundles.web === null) return null;
+  const repo = str(manifest.source?.repo);
+  const revision = str(manifest.source?.revision);
+  return {
+    // Both halves or neither: half a provenance names nothing.
+    source: repo !== null && revision !== null ? { repo, revision } : null,
+    pushedAt: str(manifest.pushedAt),
+    bundles
+  };
+}
+async function readManifest(root) {
+  try {
+    const raw = await fsp.readFile(path.join(root, "hmr", "harness.json"), "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+async function resolveCliBundlePath(root) {
+  const manifest = await readManifest(root);
+  const bundle = manifest?.cli?.bundle;
+  if (typeof bundle !== "string" || bundle.length === 0) return null;
+  const hmrDir = path.join(root, "hmr");
+  const abs = path.resolve(hmrDir, bundle);
+  const withinHmrDir = abs === hmrDir || abs.startsWith(hmrDir + path.sep);
+  if (!withinHmrDir) return null;
+  return fs.existsSync(abs) ? abs : null;
+}
+
+export {
+  readHarnessInfo,
+  readManifest,
+  resolveCliBundlePath
+};
+//# sourceMappingURL=chunk-4SXGU7RO.js.map

package/dist/chunk-4SXGU7RO.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hmr/manifest.ts"],"sourcesContent":["/**\n * The harness.json shape (`<root>/hmr/harness.json`) and pure readers over it.\n *\n * Split out of host.ts so a reader never needs a running HmrHost: `penguin` is a\n * separate, short-lived process per invocation (see packages/cli/src/index.ts) — it\n * has no host instance to ask, only the data root's own harness.json on disk.\n * `resolveCliBundlePath` is that reader: a plain disk read, no HTTP, no boot, no\n * in-memory state.\n *\n * ONE atomic version, THREE independent artifacts: `platform`, `cli`, and `web` are\n * always written together by HmrHost's single merged upgrade path (see host.ts's\n * persistVersion), but each is content-addressed and stored on its own — a push to\n * POST /api/hmr/upgrade carries `platform` and `cli` as two separate single-file ESM\n * sources, so `cli.bundle` points at its OWN file, a different sha from\n * `platform.bundle`. They are read back together too (see host.ts's restore): a\n * partial record (e.g. `platform` present but `web` or `cli` missing) is never\n * trusted — the whole version is treated as absent instead of partially applied.\n */\nimport fs from \"node:fs\";\nimport fsp from \"node:fs/promises\";\nimport path from \"node:path\";\nimport type { HarnessInfo } from \"@prismshadow/penguin-core\";\n\n/**\n * The committed on-disk record: a runtime restart resumes exactly this CODE (platform,\n * cli, web). It carries no STATE — a restart always boots the resumed platform bundle\n * against its own fresh initial context (bundle.context, see host.ts's PlatformBundle),\n * never a document parked from a previous run (see host.ts's module doc for why: a\n * parked doc's live-resource handles die with the process anyway, so resuming one could\n * only ever produce handles that fail to reclaim). Paths are relative to hmrDir\n * (`<root>/hmr`).\n */\nexport interface Manifest {\n  platform?: { bundle: string };\n  /**\n   * The CLI's own bundle pointer — its own independent file (a different sha from\n   * `platform.bundle`; the two are separately compiled artifacts), kept as its own\n   * field so a reader that only wants \"which bundle does the CLI load right now\"\n   * never has to reach into `platform` at all.\n   */\n  cli?: { bundle: string };\n  /** One gzip(JSON.stringify({ files })) artifact, restored straight into memory. */\n  web?: { manifest: string };\n  /**\n   * Files the pushed platform needs as REAL files on disk, unpacked under this directory\n   * (relative to hmrDir). The web artifact stays in memory because it is only ever served\n   * as bytes; an asset is something the platform hands to the OS — a native `.node` the\n   * loader must resolve by path, a helper binary it execs — so it has to exist on the\n   * filesystem, with its exec bit intact.\n   */\n  assets?: { dir: string };\n  /**\n   * Provenance of the push that produced this version, exactly as the pushing client sent\n   * it (scripts/deploy.mjs fills it from its own checkout). Recorded, never executed or\n   * resolved. Absent for a version pushed without it, and for every version committed\n   * before the field existed — which is why every reader treats it as optional.\n   */\n  source?: { repo: string; revision: string };\n  /** When this version was committed to the store (ISO 8601). Absent on older records. */\n  pushedAt?: string;\n}\n\n/** A string field of an untrusted manifest, or null unless it is a non-empty string. */\nfunction str(value: unknown): string | null {\n  return typeof value === \"string\" && value.length > 0 ? value : null;\n}\n\n/**\n * What the store has committed, for version reporting: provenance, commit time, and the\n * three artifact pointers. Null when nothing has ever been pushed to this root.\n *\n * Read defensively rather than cast: harness.json is written only by persistVersion, but a\n * truncated or hand-edited file must degrade a `penguin version` to missing fields, never\n * crash it. A record missing every artifact pointer counts as nothing pushed.\n */\nexport async function readHarnessInfo(root: string): Promise<HarnessInfo | null> {\n  const manifest = await readManifest(root);\n  if (manifest === null) return null;\n\n  const bundles = {\n    platform: str(manifest.platform?.bundle),\n    cli: str(manifest.cli?.bundle),\n    web: str(manifest.web?.manifest),\n  };\n  if (bundles.platform === null && bundles.cli === null && bundles.web === null) return null;\n\n  const repo = str(manifest.source?.repo);\n  const revision = str(manifest.source?.revision);\n  return {\n    // Both halves or neither: half a provenance names nothing.\n    source: repo !== null && revision !== null ? { repo, revision } : null,\n    pushedAt: str(manifest.pushedAt),\n    bundles,\n  };\n}\n\n/** Reads and parses `<root>/hmr/harness.json`; null when missing or corrupt (nothing committed yet). */\nexport async function readManifest(root: string): Promise<Manifest | null> {\n  try {\n    const raw = await fsp.readFile(path.join(root, \"hmr\", \"harness.json\"), \"utf8\");\n    return JSON.parse(raw) as Manifest;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Resolves the current CLI bundle's absolute path from a data root, or null when\n * nothing has been pushed yet: a fresh root, a missing/corrupt manifest, no `cli`\n * entry, a `cli.bundle` that isn't a non-empty string (e.g. `{\"cli\":{}}` — a\n * hand-edited or truncated harness.json), a path that resolves outside `<root>/hmr/`\n * (defense in depth: `manifest.cli.bundle` is trusted content today, written only by\n * this same process's persistVersion, but a reader must never let a malformed or\n * malicious manifest value walk it out of the store directory via `..` segments), or\n * a referenced file that no longer exists (e.g. pruned from the store — see host.ts's\n * pruneStore). A null return means \"use the packaged default\" to every caller;\n * nothing here ever throws for an ordinary unconfigured or malformed root.\n */\nexport async function resolveCliBundlePath(root: string): Promise<string | null> {\n  const manifest = await readManifest(root);\n  const bundle = manifest?.cli?.bundle;\n  if (typeof bundle !== \"string\" || bundle.length === 0) return null;\n  const hmrDir = path.join(root, \"hmr\");\n  const abs = path.resolve(hmrDir, bundle);\n  const withinHmrDir = abs === hmrDir || abs.startsWith(hmrDir + path.sep);\n  if (!withinHmrDir) return null;\n  return fs.existsSync(abs) ? abs : null;\n}\n"],"mappings":";AAkBA,OAAO,QAAQ;AACf,OAAO,SAAS;AAChB,OAAO,UAAU;AA2CjB,SAAS,IAAI,OAA+B;AAC1C,SAAO,OAAO,UAAU,YAAY,MAAM,SAAS,IAAI,QAAQ;AACjE;AAUA,eAAsB,gBAAgB,MAA2C;AAC/E,QAAM,WAAW,MAAM,aAAa,IAAI;AACxC,MAAI,aAAa,KAAM,QAAO;AAE9B,QAAM,UAAU;AAAA,IACd,UAAU,IAAI,SAAS,UAAU,MAAM;AAAA,IACvC,KAAK,IAAI,SAAS,KAAK,MAAM;AAAA,IAC7B,KAAK,IAAI,SAAS,KAAK,QAAQ;AAAA,EACjC;AACA,MAAI,QAAQ,aAAa,QAAQ,QAAQ,QAAQ,QAAQ,QAAQ,QAAQ,KAAM,QAAO;AAEtF,QAAM,OAAO,IAAI,SAAS,QAAQ,IAAI;AACtC,QAAM,WAAW,IAAI,SAAS,QAAQ,QAAQ;AAC9C,SAAO;AAAA;AAAA,IAEL,QAAQ,SAAS,QAAQ,aAAa,OAAO,EAAE,MAAM,SAAS,IAAI;AAAA,IAClE,UAAU,IAAI,SAAS,QAAQ;AAAA,IAC/B;AAAA,EACF;AACF;AAGA,eAAsB,aAAa,MAAwC;AACzE,MAAI;AACF,UAAM,MAAM,MAAM,IAAI,SAAS,KAAK,KAAK,MAAM,OAAO,cAAc,GAAG,MAAM;AAC7E,WAAO,KAAK,MAAM,GAAG;AAAA,EACvB,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAcA,eAAsB,qBAAqB,MAAsC;AAC/E,QAAM,WAAW,MAAM,aAAa,IAAI;AACxC,QAAM,SAAS,UAAU,KAAK;AAC9B,MAAI,OAAO,WAAW,YAAY,OAAO,WAAW,EAAG,QAAO;AAC9D,QAAM,SAAS,KAAK,KAAK,MAAM,KAAK;AACpC,QAAM,MAAM,KAAK,QAAQ,QAAQ,MAAM;AACvC,QAAM,eAAe,QAAQ,UAAU,IAAI,WAAW,SAAS,KAAK,GAAG;AACvE,MAAI,CAAC,aAAc,QAAO;AAC1B,SAAO,GAAG,WAAW,GAAG,IAAI,MAAM;AACpC;","names":[]}

package/dist/chunk-TTGGJDNA.js

@@ -0,0 +1,14 @@
+import {
+  readHarnessInfo
+} from "./chunk-4SXGU7RO.js";
+
+// src/version-report.ts
+import { buildInfo } from "@prismshadow/penguin-core";
+async function versionReport(root) {
+  return { ...buildInfo(), harness: await readHarnessInfo(root) };
+}
+
+export {
+  versionReport
+};
+//# sourceMappingURL=chunk-TTGGJDNA.js.map

package/dist/chunk-TTGGJDNA.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/version-report.ts"],"sourcesContent":["/**\n * The one assembler behind `penguin version --json` and GET /api/version.\n *\n * The report has two halves that no single layer can produce. Core knows the artifact this\n * process is executing and nothing about data roots; the HMR store knows what harness was\n * pushed to a root and nothing about the process reading it. Joining them here — rather\n * than in each caller — is what makes \"the CLI and the API report the same thing\" a\n * structural fact instead of two spreads that have to be kept in step.\n *\n * It lives in the server package because that is where the harness.json format is owned\n * (see ./hmr/manifest.ts), and is exported as its own entry point so the CLI can reach it\n * without pulling in a server: the module graph here is core plus a `node:fs` read.\n */\nimport { buildInfo } from \"@prismshadow/penguin-core\";\nimport type { VersionReport } from \"@prismshadow/penguin-core\";\nimport { readHarnessInfo } from \"./hmr/manifest.js\";\n\n/**\n * The running build's identity plus the harness committed to `root`'s HMR store.\n *\n * Never throws: an unreadable or malformed store reports `harness: null`, which is also\n * what a root with nothing ever pushed to it reports. Version reporting degrades to fewer\n * facts, never to a failure.\n */\nexport async function versionReport(root: string): Promise<VersionReport> {\n  return { ...buildInfo(), harness: await readHarnessInfo(root) };\n}\n"],"mappings":";;;;;AAaA,SAAS,iBAAiB;AAW1B,eAAsB,cAAc,MAAsC;AACxE,SAAO,EAAE,GAAG,UAAU,GAAG,SAAS,MAAM,gBAAgB,IAAI,EAAE;AAChE;","names":[]}