@prismshadow/penguin-server 0.2.0 → 0.2.2

package/README.md

@@ -36,8 +36,8 @@ pnpm --filter @prismshadow/penguin-server start   # node dist/index.js
 ## Security notes (known MVP limits)
 
 - **CSRF**: session cookie is `SameSite=Lax` and writes accept only `Content-Type: application/json`; no CSRF token yet.
-- **No login rate limiting**: add throttling at a reverse proxy for public deployments.
-- **Built-in admin starts as `admin` / `penguin-2026`**: change it immediately (a banner keeps reminding until you do).
+- **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.
 - Model credentials live in the Project's hidden 0600 config file; the API always masks them.
 - 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.

package/dist/api/types.d.ts

@@ -49,17 +49,33 @@ interface AuthResponse {
 interface MeResponse {
     user: UserInfo;
     /**
-     * Whether Workspace HTML previews open on a separate origin (see design §
-     * "Workspace 文件预览"). False means this deployment has no usable preview origin —
+     * Whether Workspace HTML previews open on a separate origin (the loopback
+     * counterpart of the App host, or PENGUIN_PREVIEW_ORIGIN when set). False means this
+     * deployment has no usable preview origin —
      * the App is reached on something other than a loopback name and
      * PENGUIN_PREVIEW_ORIGIN is unset — so previews fall back to the same-origin sandbox,
      * where `localStorage`, cookies and third-party embeds do not work. Computed per
      * request, since it depends on the host the caller is using.
      */
     previewIsolated: boolean;
+    /**
+     * 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.
+     */
+    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.
+     */
+    sessionVia: "password" | "desktop";
 }
 interface PasswordChangeRequest {
-    oldPassword: string;
+    /** Omitted only by desktop-established sessions (desktop mode); required otherwise. */
+    oldPassword?: string;
     /** At least 8 characters. */
     newPassword: string;
 }
@@ -79,6 +95,51 @@ interface AdminPasswordResetRequest {
     /** New initial password (at least 8 characters); resets invalidate all of the user's sessions. */
     password: string;
 }
+/**
+ * Admin-level server-global settings (SQLite server_settings):
+ * two independent proxy switches sharing one optional explicit address. In every
+ * on-state the effective NO_PROXY always includes localhost/127.0.0.1/::1 (loopback is
+ * never proxied), and changes apply to newly initiated connections/spawns immediately —
+ * no restart.
+ */
+interface ServerSettings {
+    /**
+     * "Application uses the proxy" (default on): the server's own outbound traffic (LLM
+     * requests, the update check, image fetches). On with `proxyUrl` set = that address
+     * for both http and https; on without an address = the proxy environment variables
+     * HTTP_PROXY / HTTPS_PROXY (both spellings); off = always direct.
+     */
+    proxyForApp: boolean;
+    /**
+     * "Agent environment uses the proxy" (default on): agent command subprocess
+     * environments. On with `proxyUrl` set = HTTP_PROXY / HTTPS_PROXY (plus lowercase
+     * twins) injected as that address with the merged NO_PROXY, overriding inherited
+     * values; on without an address = the host environment passes through unchanged;
+     * off = the proxy variables are stripped (NO_PROXY kept).
+     */
+    proxyForAgent: boolean;
+    /**
+     * The shared explicit proxy address (canonical `http(s)://host[:port]`), or null =
+     * follow the proxy environment variables. When set it takes precedence over
+     * HTTP_PROXY / HTTPS_PROXY wherever the owning switch is on.
+     */
+    proxyUrl: string | null;
+}
+interface ServerSettingsResponse {
+    settings: ServerSettings;
+}
+/** PUT body: every field optional, omitted fields keep their current value (mirrors prefs). */
+interface ServerSettingsUpdateRequest {
+    proxyForApp?: boolean;
+    proxyForAgent?: boolean;
+    /**
+     * New proxy address. Accepted forms: `http://host[:port]`, `https://host[:port]`, or
+     * bare `host[:port]` (normalized to `http://…` — only normalized values are stored,
+     * and the response echoes the stored form). Empty/whitespace-only or null clears the
+     * address (follow the environment variables); anything else is 400 `invalid_proxy_url`.
+     */
+    proxyUrl?: string | null;
+}
 /** User UI preferences (SQLite ui_prefs, free-form JSON; known keys declared here). */
 interface UiPrefs {
     theme?: "light" | "dark";
@@ -91,6 +152,8 @@ interface UiPrefs {
      * scanning (#139).
      */
     showCliSessions?: boolean;
+    /** The initial-password notice banner (app layout) was permanently dismissed by the user. */
+    initialPasswordBannerDismissed?: boolean;
     [key: string]: unknown;
 }
 interface PrefsResponse {
@@ -290,6 +353,42 @@ interface ModelTestResponse {
     tps?: number;
     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
+ * table (and thus without touching credentials). The pair must name a configured model
+ * entry, exactly like the whole-table route's defaultModel validation.
+ */
+interface DefaultModelUpdateRequest {
+    provider: string;
+    modelId: string;
+}
+/** Response mirrors what GET models reports as `defaultModel`. */
+interface DefaultModelResponse {
+    defaultModel: ModelRefDto;
+}
+/**
+ * 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,
+ * the PUT request body (whole-block replace: an omitted key clears it) and the PUT
+ * response (the stored block). The default MODEL is deliberately not here: it stays the
+ * top-level `default_model` served/written via the models routes (single-sourced with the
+ * models page).
+ */
+interface ChatDefaultsDto {
+    /** Preselected Agent; must reference an existing Agent of the Project (400 unknown_agent). */
+    agentId?: string;
+    /** Prefilled Workspace directory; absent/empty = a temporary workspace. */
+    workspace?: string;
+    /** Prefilled approval mode; absent = the built-in "allow-all". */
+    approvalMode?: ApprovalMode;
+    /**
+     * Fallback thinking level for Agents whose config has no explicit `model.thinking_level`
+     * (resolution chain: Agent explicit > this project default > built-in "medium"). Never
+     * "none" — only the four selectable tiers.
+     */
+    thinkingLevel?: Exclude<ThinkingLevelName, "none">;
+}
 /** Read-only vault entry display: key name + masked value; plaintext is never sent. */
 interface VaultEntryInfo {
     key: string;
@@ -326,12 +425,16 @@ interface AgentSummary {
     toolCount: number;
     /** Agent State version number (the `version` in system_config.yaml; treated as 1 if missing). */
     version: number;
+    /** Whether the config's kernel stamp is behind the current defaults generation (a missing stamp counts as outdated) — drives the list card's update hint. */
+    kernelOutdated: boolean;
     /** Vault key count (number of keys in agent_state/.vault.toml). */
     vaultKeyCount: number;
     /** Schedule count (number of .toml files under agent_state/schedule/, including invalid ones). */
     scheduleCount: number;
     /** Installed Skill count (number of agent_state/skills/<name>/ directories with a SKILL.md). */
     skillCount: number;
+    /** Memory count (topic files summed over the scope directories under agent_state/memory/, independent of the memory switch). */
+    memoryCount: number;
 }
 interface AgentsResponse {
     agents: AgentSummary[];
@@ -357,16 +460,69 @@ interface AgentCompactionConfigDto {
     mode?: "summarize" | "discard";
     prompt?: string;
 }
+/** Memory config. All fields report effective values (a config with no `memory` section reads as enabled with the built-in prompts, matching core); the prompts are edited on the Memory tab. */
+interface AgentMemoryConfigDto {
+    enabled: boolean;
+    /** The always-injected half of the `{{MEMORY}}` block (carries `{{USER_MEMORY_INDEX}}`; the User directory is literal text). */
+    prompt: string;
+    /** Appended only in a persistent Workspace (carries `{{WORKSPACE_MEMORY_INDEX}}` and the rendered `{{WORKSPACE_MEMORY_DIR}}` directory). */
+    workspacePrompt: string;
+}
+/**
+ * Vault prompt-injection config, edited on the Vault tab. `enabled` / `prompt` report
+ * effective values (a config with no `vault` section reads as enabled with the built-in
+ * prompt, matching core); the last two are read-only facts computed from the stored template.
+ */
+interface AgentVaultConfigDto {
+    /** Whether the Vault section enters the model context (values are injected into subprocesses regardless). */
+    enabled: boolean;
+    /** The `{{VAULT}}` block (carries `{{VAULT_KEYS}}`). */
+    prompt: string;
+    /** Whether the stored template carries `{{VAULT}}`; POST …/vault/template-placeholder inserts (or migrates to) it explicitly. */
+    templateHasPlaceholder: boolean;
+    /** Whether the stored template still carries the legacy hardcoded # Vault section verbatim (a pre-`{{VAULT}}` Agent) — the migration case of the insert endpoint. */
+    legacySectionPresent: boolean;
+}
+/** Skills prompt-injection config, edited on the Skills tab; same field semantics as AgentVaultConfigDto, for `{{SKILLS}}` / `{{SKILL_METADATA}}` and the legacy # Skills section. */
+interface AgentSkillsConfigDto {
+    /** Whether the Skills section enters the model context (installed skills remain explicitly invocable regardless). */
+    enabled: boolean;
+    /** The `{{SKILLS}}` block (carries `{{SKILL_METADATA}}`). */
+    prompt: string;
+    /** Whether the stored template carries `{{SKILLS}}`; POST …/skills/template-placeholder inserts (or migrates to) it explicitly. */
+    templateHasPlaceholder: boolean;
+    /** Whether the stored template still carries the legacy hardcoded # Skills section verbatim — the migration case of the insert endpoint. */
+    legacySectionPresent: boolean;
+}
+/** Schedules prompt-injection config, edited on the Schedules tab. No legacy field: Schedules never had a hardcoded template section. */
+interface AgentSchedulesConfigDto {
+    /** Whether the Scheduled Tasks section enters the model context (the server fires configured tasks regardless). */
+    enabled: boolean;
+    /** The `{{SCHEDULES}}` block (carries `{{SCHEDULE_LIST}}`). */
+    prompt: string;
+    /** Whether the stored template carries `{{SCHEDULES}}`; POST …/schedules/template-placeholder inserts it explicitly. */
+    templateHasPlaceholder: boolean;
+}
 /** Structured view of system_config.yaml (for the edit form). */
 interface AgentConfigDto {
     name?: string;
     description?: string;
     /** Agent State version number (treated as 1 if missing; shown in the settings page overview). */
     version: number;
+    /** The stored kernel stamp (`kernel_version`): which defaults generation the config is based on; null when the config predates the kernel-version mechanism. */
+    kernelVersion: string | null;
+    /** The current defaults generation (core's KERNEL_VERSION) — what a kernel update would stamp. */
+    kernelLatest: string;
+    /** Whether the stamp is behind kernelLatest (a missing stamp counts as outdated). */
+    kernelOutdated: boolean;
     systemPrompt: string;
     maxTurns?: number;
     model?: AgentModelConfigDto;
     compaction?: AgentCompactionConfigDto;
+    memory: AgentMemoryConfigDto;
+    vault: AgentVaultConfigDto;
+    skills: AgentSkillsConfigDto;
+    schedules: AgentSchedulesConfigDto;
     toolsBuiltin: ToolDefinitionConfig[];
     mcpServers: MCPServerConfig[];
 }
@@ -379,6 +535,29 @@ interface AgentConfigResponse {
     stateDir: string;
     activeSessionCount: number;
 }
+/**
+ * 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.
+ */
+interface AgentKernelUpdateResponse {
+    /** Leaves advanced to the new default (previously missing, or an untouched old default). */
+    advanced: string[];
+    /** Leaves kept because the stored value matches no recorded defaults generation (user customizations, kept conservatively). */
+    kept: string[];
+    /** The kernel stamp written (the current defaults generation). */
+    kernelVersion: string;
+}
+/** POST …/config/mcp-test result: reachability of one MCP Server entry. */
+interface McpServerTestResponse {
+    ok: boolean;
+    /** Discovered tool names (`mcp__<server>__<tool>`), present on success. */
+    tools?: string[];
+    /** Failure detail (connect error, timeout, server stderr tail), present on failure. */
+    error?: string;
+    /** Connect + discovery wall time (both outcomes) — the models test reports latency, this matches. */
+    latencyMs?: number;
+}
 /** PUT any subset: only provided keys are updated (remaining YAML content and comments preserved); agentsMd overwrites the whole file. */
 interface AgentConfigUpdateRequest {
     agentsMd?: string;
@@ -389,10 +568,73 @@ interface AgentConfigUpdateRequest {
         maxTurns?: number;
         model?: AgentModelConfigDto;
         compaction?: AgentCompactionConfigDto;
+        memory?: Partial<AgentMemoryConfigDto>;
+        /** Only the writable half of the DTO — the template facts (templateHasPlaceholder / legacySectionPresent) are computed, never written. */
+        vault?: {
+            enabled?: boolean;
+            prompt?: string;
+        };
+        skills?: {
+            enabled?: boolean;
+            prompt?: string;
+        };
+        schedules?: {
+            enabled?: boolean;
+            prompt?: string;
+        };
         toolsBuiltin?: ToolDefinitionConfig[];
         mcpServers?: MCPServerConfig[];
     };
 }
+/** One Memory scope directory: `agent_state/memory/user/` or `agent_state/memory/<workspaceKey>/`. */
+interface MemoryScopeInfo {
+    /** Directory name under `memory/`: `user`, or a Workspace's `<safe-basename>-<hash>` key. */
+    scopeKey: string;
+    /** `user` — the scope every Session reads, temporary Workspaces included; `workspace` — one Workspace's scope. */
+    kind: "user" | "workspace";
+    /** Workspace path the key was derived from, read from the directory's `.workspace` marker; unset on the user scope (it stands for no path) and for a directory edited by hand. */
+    workspacePath?: string;
+    /** Number of Markdown topic files in the directory (the `MEMORY.md` index not counted). */
+    fileCount: number;
+    /** Most recent topic-file mtime in the directory (ISO 8601); unset when the directory holds no topic file. */
+    updatedAt?: string;
+}
+/** One Memory topic file, as listed (frontmatter only — the body is fetched per file). */
+interface MemoryFileInfo {
+    /** File name inside the scope directory, e.g. `prefers-pnpm.md`. */
+    name: string;
+    /** Frontmatter `name`; falls back to the file name. */
+    title: string;
+    /** Frontmatter `description`; empty when the file declares none. */
+    description: string;
+    /** Frontmatter `updated_at`, verbatim. */
+    updatedAt?: string;
+    /** File size in bytes. */
+    size: number;
+    /** File mtime (ISO 8601). */
+    modifiedAt: string;
+}
+/** GET …/memory — the tab's landing payload: the switch and every scope group, user scope first. */
+interface MemoryOverviewResponse {
+    /** Whether Memory reaches the model context (the Agent-level switch). */
+    enabled: boolean;
+    /** Whether the prompt template carries the `{{MEMORY}}` placeholder. An Agent created before Memory has none and injects nothing; POST …/memory/template-placeholder inserts it explicitly. */
+    templateHasMemory: boolean;
+    /** Absolute path of `agent_state/memory/`. */
+    memoryDir: string;
+    scopes: MemoryScopeInfo[];
+}
+/** GET …/memory/scopes/:key/files */
+interface MemoryFilesResponse {
+    scopeKey: string;
+    files: MemoryFileInfo[];
+}
+/** GET …/memory/scopes/:key/files/:name */
+interface MemoryFileResponse {
+    scopeKey: string;
+    file: MemoryFileInfo;
+    content: string;
+}
 interface SessionInfo {
     sessionId: string;
     projectId: string;
@@ -513,15 +755,57 @@ interface MessagesLiveTail {
     cursor: string;
     fragments: OmniMessage[];
 }
+/**
+ * Pagination envelope of a windowed `GET /messages` (`tailLimit` / `before` requests
+ * only; the parameterless full read never carries it). A window is a run of whole
+ * message-bearing units — one unit = one Task in the Web reducer's sense, opened by a
+ * main-session user prompt — cut so that no pairing (tool_call/output), compaction span
+ * or steering group ever splits across windows.
+ */
+interface MessagesPageInfo {
+    /**
+     * Cursor of this window's first unit (`<shardIndex>:<ordinal>`): pass it back as
+     * `before=` to fetch the previous window. Stable across requests and compaction —
+     * rotation opens a NEW shard and closed shards are immutable. Absent = this window
+     * reaches the very beginning of the transcript (no older history).
+     */
+    before?: string;
+    /**
+     * Outline turns (the Web conversation outline's entry rule) opened BEFORE this
+     * window: the client offsets its global "round N" numbering by this, so a partial
+     * window never mis-numbers. 0 when the window starts at the beginning.
+     */
+    earlierTurns: number;
+    /**
+     * Cumulative stats accrued before this window, seeded into the client's stats
+     * tracker so header chips and per-turn cumulative rows equal a full load:
+     * finished-Task elapsed, subagent token totals, and the last main-session
+     * session/context token readings.
+     */
+    prior: {
+        subagentTokens: number;
+        elapsedMs: number;
+        sessionTokens: number;
+        contextTokens: number;
+    };
+}
 /** Message history: the full messages and events from concatenating all of this Session's Trace files in order (excludes partial_*). */
 interface MessagesResponse {
     messages: OmniMessage[];
     /**
      * Present only while the Session is running/compacting: the in-progress stream tail
      * (open streaming fragments + the channel cursor they cover), so a client joining
-     * mid-stream can render the currently streaming message. Omitted when idle.
+     * mid-stream can render the currently streaming message. Omitted when idle. On
+     * windowed requests it rides TAIL pages only — a `before` page is immutable history
+     * and never carries it.
      */
     live?: MessagesLiveTail;
+    /**
+     * Present exactly on windowed requests (`tailLimit` / `before`): `messages` is then
+     * the requested window (subagent pointers inside it expanded as usual) rather than
+     * the full transcript. See MessagesPageInfo.
+     */
+    page?: MessagesPageInfo;
 }
 /**
  * A single Prompt's input parts: text, image (data: / http(s) URL), or an uploaded file.
@@ -647,6 +931,23 @@ interface ApprovalDecisionRequest {
 interface RetryNowResponse {
     skipped: boolean;
 }
+/**
+ * One background command process started by the Session (an exec_command promoted past
+ * its yield window). Served from the ACTIVE runtime only: a session whose runtime entry
+ * is gone truthfully reports an empty list.
+ */
+interface SessionProcessInfo {
+    processId: string;
+    /** OS pid of the process-group leader; null when the spawn itself failed. */
+    pid: number | null;
+    cmd: string;
+    cwd: string;
+    startedAt: string;
+    running: boolean;
+}
+interface SessionProcessesResponse {
+    processes: SessionProcessInfo[];
+}
 /** Docs: /docs/server-api § "Streaming (SSE)". */
 type ServerEvent = 
 /**
@@ -914,6 +1215,23 @@ interface TraceToolSpan {
     /** The Task that initiated this tool (grouped with its tool_call segment): async output belongs to this Task even if it arrives after request_end. */
     taskIndex: number;
 }
+/**
+ * Non-tool auxiliary phase on the timeline: rendered in its own lane under the "other"
+ * legend category — deliberately not a tool span, since nothing was called. Currently the
+ * first run's MCP connect + discovery (from the mcp_connect_begin/end event pair).
+ */
+interface TraceOtherSpan {
+    /** Unique bar key (e.g. `mcp-connect-<beginTs>`). */
+    key: string;
+    /** Lane label, e.g. "mcp connect". */
+    name: string;
+    startTs: string;
+    endTs: string;
+    /** Attached to the Task that follows the phase (same grouping convention as toolSpans). */
+    taskIndex: number;
+    /** True when the phase ended with failures (some servers unreachable) or was aborted. */
+    failed?: boolean;
+}
 interface UsageTrendPointInTrace {
     ts: string;
     requestTotal: number;
@@ -935,6 +1253,8 @@ interface TraceAnalysisResponse {
     modelSegments: TraceModelSegment[];
     /** Execution timeline: each tool's approval/execution phases (independent lane, can overlap with model decoding). */
     toolSpans: TraceToolSpan[];
+    /** Execution timeline: non-tool auxiliary phases (their own "other" lanes — currently the first run's MCP connect + discovery). */
+    otherSpans: TraceOtherSpan[];
     /** Number of request_end events with status ∈ {timeout, malformed}. */
     reconnectCount: number;
     /** Number of compaction_begin events. */
@@ -953,9 +1273,56 @@ interface AgentTraceDateGroup {
     date: string;
     sessions: AgentTraceSessionGroup[];
 }
-/** Agent → date → Session → Trace file drill-down browsing structure (reverse chronological). */
+/** One Trace file in the session-centric listing (`date` carried per file: one Session's shards can span date directories). */
+interface AgentTraceSessionFile {
+    index: number;
+    date: string;
+    sizeBytes: number;
+}
+/** One Session's Trace files merged across date directories (the paginated listing's unit). */
+interface AgentTraceSessionEntry {
+    sessionId: string;
+    /**
+     * Display title, resolved only for the returned page: the sessions DB title when one
+     * exists, else derived from the Session's first user prompt (bounded head-read of the
+     * earliest shard); absent when neither yields one (the client falls back to its
+     * default title — raw session ids are never rendered).
+     */
+    title?: string;
+    /**
+     * Sidebar category of this Session, from the same bounded classification the listing
+     * filters and counts with: archived exactly from the DB row; origin from the shared
+     * in-process registry / previously observed session_meta; a DB-untracked Session this
+     * process has not yet head-read falls into `active` until a page surfaces it (its
+     * head-read then registers the true origin for subsequent requests).
+     */
+    category: SessionCategory;
+    /** Workspace path locked at creation (DB row or observed session_meta); "" when unknown — the client's merged temp-group fallback. */
+    workspace: string;
+    /** Sorted by index ascending (a higher index is newer). */
+    files: AgentTraceSessionFile[];
+}
+/**
+ * Agent-level Trace browsing structure. Without `limit` the response is the legacy full
+ * drill-down (`dates`: Agent → date → Session → Trace file, reverse chronological) and the
+ * paging fields are absent. With `offset`/`limit` the response is session-group-centric:
+ * `sessions` carries the requested slice (newest first by sessionId desc — ids embed a
+ * timestamp, so that is reverse chronological) with titles and classification,
+ * `totalSessions` the session-group count (within `category` when one is given, so paging
+ * and the count agree), `counts` / `workspaceCounts` the per-category totals over ALL of
+ * the Agent's session groups (folder labels / workspace-mode group headers), and `dates`
+ * stays empty (per-file stats are only taken for the returned page).
+ */
 interface AgentTracesResponse {
     dates: AgentTraceDateGroup[];
+    /** Present only when the request paginates: the requested slice of Session groups, newest first. */
+    sessions?: AgentTraceSessionEntry[];
+    /** Present only when the request paginates: session-group count of the paged (category-filtered) set. */
+    totalSessions?: number;
+    /** Present only when the request paginates: per-category totals over all of the Agent's session groups. */
+    counts?: SessionCategoryCounts;
+    /** Present only when the request paginates: `counts` broken down by Workspace path ("" = unknown). */
+    workspaceCounts?: Record<string, SessionCategoryCounts>;
 }
 interface TraceImportRequest {
     /** Base64 of the Trace file content (JSON Lines; the first record must be `session_meta`). */
@@ -1250,6 +1617,18 @@ interface AgentSkillsResponse {
 interface SkillInstallRequest {
     names: string[];
 }
+/**
+ * POST /api/projects/:p/agents/:a/skills/archive: install one Skill from an uploaded zip.
+ * Layout: SKILL.md at the zip root, or exactly one top-level directory containing SKILL.md
+ * (the directory name is then the Skill name). 201 returns the refreshed installed list
+ * (AgentSkillsResponse); an already-installed name without `overwrite` is 409 `skill_exists`.
+ */
+interface SkillArchiveInstallRequest {
+    /** Base64-encoded zip archive (decoded size capped at 14MB, same as the Agent snapshot import). */
+    dataBase64: string;
+    /** 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;
@@ -1299,4 +1678,4 @@ interface UpdateRunResponse {
     needsRestart: boolean;
 }
 
-export type { AdminPasswordResetRequest, AdminUserCreateRequest, AdminUserCreateResponse, AdminUsersResponse, AgentCompactionConfigDto, AgentConfigDto, AgentConfigResponse, AgentConfigUpdateRequest, AgentCreateRequest, AgentCreateResponse, AgentImportRequest, AgentImportResponse, AgentModelConfigDto, AgentSkillsResponse, AgentSummary, AgentTraceDateGroup, AgentTraceFileRef, AgentTraceSessionGroup, AgentTracesResponse, AgentsResponse, ApprovalDecisionRequest, ApprovalMode, AuthLoginRequest, AuthResponse, BenchmarkCaseScore, BenchmarkCaseSummary, BenchmarkCasesResponse, BenchmarkEvaluation, BenchmarkRunScore, BenchmarkSummary, BenchmarksResponse, CaseMaterial, CredentialInfo, DirEntryInfo, DirListResponse, ErrorBody, FilesStatRequest, FilesStatResponse, GoalResponse, GoalServerEvent, GoalStateView, MeResponse, MemberAddRequest, MemberAddResponse, MemberInfo, MembersResponse, MessagesLiveTail, MessagesResponse, ModelInfo, ModelPricingDto, ModelRefDto, ModelTestRequest, ModelTestResponse, ModelUpdateEntry, ModelsResponse, ModelsUpdateRequest, PasswordChangeRequest, PendingSteeringInfo, PrefsResponse, ProjectCreateRequest, ProjectCreateResponse, ProjectRole, ProjectSummary, ProjectUpdateRequest, ProjectUpdateResponse, ProjectsResponse, RequestSpan, RetryNowResponse, ScheduleItem, ScheduleServerEvent, ScheduleStatus, ScheduleUpsertRequest, SchedulesResponse, ServerEvent, SessionCategory, SessionCategoryCounts, SessionCreateRequest, SessionCreateResponse, SessionInfo, SessionPatchRequest, SessionResponse, SessionSource, SessionStatus, SessionTracesResponse, SessionsResponse, SkillGroupItem, SkillInstallRequest, SkillLibraryResponse, SkillMetadataItem, SteerRequest, TaskCreateRequest, TaskCreateResponse, TaskInputPart, ToolCallSpan, TraceAnalysisResponse, TraceEventsResponse, TraceFileInfo, TraceImportRequest, TraceImportResponse, TraceModelSegment, TraceTaskStats, TraceToolSpan, UiPrefs, UpdateCheckResponse, UpdateRunResponse, 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, CredentialInfo, DefaultModelResponse, DefaultModelUpdateRequest, DirEntryInfo, DirListResponse, ErrorBody, FilesStatRequest, FilesStatResponse, GoalResponse, GoalServerEvent, GoalStateView, McpServerTestResponse, MeResponse, MemberAddRequest, MemberAddResponse, MemberInfo, MembersResponse, MemoryFileInfo, MemoryFileResponse, MemoryFilesResponse, MemoryOverviewResponse, MemoryScopeInfo, MessagesLiveTail, MessagesPageInfo, MessagesResponse, ModelInfo, ModelPricingDto, ModelRefDto, ModelTestRequest, ModelTestResponse, ModelUpdateEntry, ModelsResponse, ModelsUpdateRequest, PasswordChangeRequest, PendingSteeringInfo, PrefsResponse, ProjectCreateRequest, ProjectCreateResponse, ProjectRole, ProjectSummary, ProjectUpdateRequest, ProjectUpdateResponse, ProjectsResponse, RequestSpan, RetryNowResponse, ScheduleItem, ScheduleServerEvent, ScheduleStatus, ScheduleUpsertRequest, SchedulesResponse, ServerEvent, ServerSettings, ServerSettingsResponse, ServerSettingsUpdateRequest, SessionCategory, SessionCategoryCounts, SessionCreateRequest, SessionCreateResponse, 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, TraceTaskStats, TraceToolSpan, UiPrefs, UpdateCheckResponse, UpdateRunResponse, UsageAgentCount, UsageBucket, UsageErrorCount, UsageErrorItem, UsageErrors, UsageErrorsPage, UsageGroupBy, UsageGroupRow, UsageResponse, UsageSuccessRate, UsageTrendPoint, UsageTrendPointInTrace, UserInfo, VaultEntryInfo, VaultEntryUpdate, VaultResponse, VaultUpdateRequest, VersionResponse, WorkspaceFileEntry, WorkspaceFilesResponse };

package/dist/chunk-OMBFPEGQ.js

@@ -0,0 +1,76 @@
+// src/lock.ts
+import fs from "fs";
+import net from "net";
+import path from "path";
+var PROBE_TIMEOUT_MS = 500;
+function serverLockPath(root) {
+  return path.join(root, "server.lock");
+}
+function readServerLock(root) {
+  let raw;
+  try {
+    raw = fs.readFileSync(serverLockPath(root), "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.pid !== "number" || !Number.isInteger(parsed.pid) || typeof parsed.port !== "number" || !Number.isInteger(parsed.port)) {
+      return null;
+    }
+    return { pid: parsed.pid, port: parsed.port, startedAt: String(parsed.startedAt ?? "") };
+  } catch {
+    return null;
+  }
+}
+function pidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM";
+  }
+}
+function portAccepts(port) {
+  return new Promise((resolve) => {
+    const socket = net.connect({ host: "127.0.0.1", port, timeout: PROBE_TIMEOUT_MS });
+    const done = (ok) => {
+      socket.destroy();
+      resolve(ok);
+    };
+    socket.once("connect", () => done(true));
+    socket.once("timeout", () => done(false));
+    socket.once("error", () => done(false));
+  });
+}
+async function isServerLockAlive(lock) {
+  return pidAlive(lock.pid) && await portAccepts(lock.port);
+}
+async function liveServerLock(root) {
+  const lock = readServerLock(root);
+  if (!lock) return null;
+  return await isServerLockAlive(lock) ? lock : null;
+}
+function acquireServerLock(root, lock) {
+  const target = serverLockPath(root);
+  const tmp = `${target}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(lock) + "\n");
+  fs.renameSync(tmp, target);
+}
+function releaseServerLock(root) {
+  try {
+    const lock = readServerLock(root);
+    if (lock && lock.pid === process.pid) fs.rmSync(serverLockPath(root));
+  } catch {
+  }
+}
+
+export {
+  serverLockPath,
+  readServerLock,
+  isServerLockAlive,
+  liveServerLock,
+  acquireServerLock,
+  releaseServerLock
+};
+//# sourceMappingURL=chunk-OMBFPEGQ.js.map

package/dist/chunk-OMBFPEGQ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/lock.ts"],"sourcesContent":["/**\n * Root-level server instance lock (`<root>/server.lock`).\n *\n * web.db is single-process / single-writer (see db/database.ts), and two servers on one\n * data root would also double-run the schedule scheduler — so a data root admits one\n * server at a time. The lock records {pid, port, startedAt}; liveness requires BOTH the\n * pid to be alive AND the recorded port to accept a TCP connection, because either signal\n * alone false-positives (pids get recycled, ports get taken by unrelated processes). A\n * lock that fails the liveness check is stale and is simply overwritten by the next\n * server.\n *\n * Published as `@prismshadow/penguin-server/lock` (side-effect-free) so the CLI and the\n * desktop shell can pre-check a root without importing the package entry, which starts\n * listening.\n */\nimport fs from \"node:fs\";\nimport net from \"node:net\";\nimport path from \"node:path\";\n\nexport interface ServerLock {\n  pid: number;\n  port: number;\n  startedAt: string;\n}\n\n/** TCP probe budget: loopback either connects immediately or the port is dead. */\nconst PROBE_TIMEOUT_MS = 500;\n\nexport function serverLockPath(root: string): string {\n  return path.join(root, \"server.lock\");\n}\n\n/** Reads the lock file; a missing or malformed file reads as \"no lock\". */\nexport function readServerLock(root: string): ServerLock | null {\n  let raw: string;\n  try {\n    raw = fs.readFileSync(serverLockPath(root), \"utf8\");\n  } catch {\n    return null;\n  }\n  try {\n    const parsed = JSON.parse(raw) as Partial<ServerLock>;\n    if (\n      typeof parsed.pid !== \"number\" ||\n      !Number.isInteger(parsed.pid) ||\n      typeof parsed.port !== \"number\" ||\n      !Number.isInteger(parsed.port)\n    ) {\n      return null;\n    }\n    return { pid: parsed.pid, port: parsed.port, startedAt: String(parsed.startedAt ?? \"\") };\n  } catch {\n    return null;\n  }\n}\n\nfunction pidAlive(pid: number): boolean {\n  try {\n    process.kill(pid, 0);\n    return true;\n  } catch (err) {\n    // EPERM = the process exists but belongs to another user — still alive.\n    return (err as NodeJS.ErrnoException).code === \"EPERM\";\n  }\n}\n\nfunction portAccepts(port: number): Promise<boolean> {\n  return new Promise((resolve) => {\n    // 127.0.0.1 rather than localhost: this is a raw TCP liveness probe, not an App\n    // request, and the server binds 127.0.0.1 (plus ::1) on loopback setups.\n    const socket = net.connect({ host: \"127.0.0.1\", port, timeout: PROBE_TIMEOUT_MS });\n    const done = (ok: boolean) => {\n      socket.destroy();\n      resolve(ok);\n    };\n    socket.once(\"connect\", () => done(true));\n    socket.once(\"timeout\", () => done(false));\n    socket.once(\"error\", () => done(false));\n  });\n}\n\n/** True when the lock's process is alive AND its port accepts connections. */\nexport async function isServerLockAlive(lock: ServerLock): Promise<boolean> {\n  return pidAlive(lock.pid) && (await portAccepts(lock.port));\n}\n\n/** Convenience for pre-checks: the live lock on this root, or null (absent or stale). */\nexport async function liveServerLock(root: string): Promise<ServerLock | null> {\n  const lock = readServerLock(root);\n  if (!lock) return null;\n  return (await isServerLockAlive(lock)) ? lock : null;\n}\n\n/** Writes the lock atomically (tmp + rename; the parent directory must already exist). */\nexport function acquireServerLock(root: string, lock: ServerLock): void {\n  const target = serverLockPath(root);\n  const tmp = `${target}.${process.pid}.tmp`;\n  fs.writeFileSync(tmp, JSON.stringify(lock) + \"\\n\");\n  fs.renameSync(tmp, target);\n}\n\n/** Removes the lock if it is still ours (best-effort; never throws on shutdown paths). */\nexport function releaseServerLock(root: string): void {\n  try {\n    const lock = readServerLock(root);\n    if (lock && lock.pid === process.pid) fs.rmSync(serverLockPath(root));\n  } catch {\n    // Best-effort: a stale leftover is overwritten by the next server anyway.\n  }\n}\n"],"mappings":";AAeA,OAAO,QAAQ;AACf,OAAO,SAAS;AAChB,OAAO,UAAU;AASjB,IAAM,mBAAmB;AAElB,SAAS,eAAe,MAAsB;AACnD,SAAO,KAAK,KAAK,MAAM,aAAa;AACtC;AAGO,SAAS,eAAe,MAAiC;AAC9D,MAAI;AACJ,MAAI;AACF,UAAM,GAAG,aAAa,eAAe,IAAI,GAAG,MAAM;AAAA,EACpD,QAAQ;AACN,WAAO;AAAA,EACT;AACA,MAAI;AACF,UAAM,SAAS,KAAK,MAAM,GAAG;AAC7B,QACE,OAAO,OAAO,QAAQ,YACtB,CAAC,OAAO,UAAU,OAAO,GAAG,KAC5B,OAAO,OAAO,SAAS,YACvB,CAAC,OAAO,UAAU,OAAO,IAAI,GAC7B;AACA,aAAO;AAAA,IACT;AACA,WAAO,EAAE,KAAK,OAAO,KAAK,MAAM,OAAO,MAAM,WAAW,OAAO,OAAO,aAAa,EAAE,EAAE;AAAA,EACzF,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAEA,SAAS,SAAS,KAAsB;AACtC,MAAI;AACF,YAAQ,KAAK,KAAK,CAAC;AACnB,WAAO;AAAA,EACT,SAAS,KAAK;AAEZ,WAAQ,IAA8B,SAAS;AAAA,EACjD;AACF;AAEA,SAAS,YAAY,MAAgC;AACnD,SAAO,IAAI,QAAQ,CAAC,YAAY;AAG9B,UAAM,SAAS,IAAI,QAAQ,EAAE,MAAM,aAAa,MAAM,SAAS,iBAAiB,CAAC;AACjF,UAAM,OAAO,CAAC,OAAgB;AAC5B,aAAO,QAAQ;AACf,cAAQ,EAAE;AAAA,IACZ;AACA,WAAO,KAAK,WAAW,MAAM,KAAK,IAAI,CAAC;AACvC,WAAO,KAAK,WAAW,MAAM,KAAK,KAAK,CAAC;AACxC,WAAO,KAAK,SAAS,MAAM,KAAK,KAAK,CAAC;AAAA,EACxC,CAAC;AACH;AAGA,eAAsB,kBAAkB,MAAoC;AAC1E,SAAO,SAAS,KAAK,GAAG,KAAM,MAAM,YAAY,KAAK,IAAI;AAC3D;AAGA,eAAsB,eAAe,MAA0C;AAC7E,QAAM,OAAO,eAAe,IAAI;AAChC,MAAI,CAAC,KAAM,QAAO;AAClB,SAAQ,MAAM,kBAAkB,IAAI,IAAK,OAAO;AAClD;AAGO,SAAS,kBAAkB,MAAc,MAAwB;AACtE,QAAM,SAAS,eAAe,IAAI;AAClC,QAAM,MAAM,GAAG,MAAM,IAAI,QAAQ,GAAG;AACpC,KAAG,cAAc,KAAK,KAAK,UAAU,IAAI,IAAI,IAAI;AACjD,KAAG,WAAW,KAAK,MAAM;AAC3B;AAGO,SAAS,kBAAkB,MAAoB;AACpD,MAAI;AACF,UAAM,OAAO,eAAe,IAAI;AAChC,QAAI,QAAQ,KAAK,QAAQ,QAAQ,IAAK,IAAG,OAAO,eAAe,IAAI,CAAC;AAAA,EACtE,QAAQ;AAAA,EAER;AACF;","names":[]}