@prismshadow/penguin-server 0.1.2 → 0.1.5

package/dist/api/types.d.ts

@@ -116,6 +116,13 @@ interface ProjectCreateRequest {
 interface ProjectCreateResponse {
     project: ProjectSummary;
 }
+interface ProjectUpdateRequest {
+    /** New display name. The projectId itself is immutable — only this label can change. */
+    name: string;
+}
+interface ProjectUpdateResponse {
+    project: ProjectSummary;
+}
 interface MemberInfo {
     userId: string;
     role: ProjectRole;
@@ -186,6 +193,13 @@ interface ModelsResponse {
     defaultModel?: ModelRefDto;
     /** Vision model used as a proxy reader for read_image (describes images when the session model has vision=false). */
     visionModel?: ModelRefDto;
+    /**
+     * When the Project's model/credential config last changed (ISO; the config file's mtime,
+     * so it survives restarts). The web's auth-dead gate compares it against the last auth
+     * abort: an abort OLDER than the last credential update no longer disables the composer
+     * (the key was fixed since). Absent when the Project has no config file yet.
+     */
+    updatedAt?: string;
     models: ModelInfo[];
 }
 /** PUT full-table replace semantics: models not present are deleted; omitting apiKey = keep existing value. Key = (provider, modelId). */
@@ -467,12 +481,44 @@ interface SessionPatchRequest {
     /** Manual rename; non-empty string, overrides the auto-generated title. */
     title?: string;
 }
+/**
+ * Live in-progress tail of a running Session, carried by `MessagesResponse.live`.
+ *
+ * Contract (see runtime/live-tail.ts and the GET /messages route): the server captures
+ * `cursor` and `fragments` atomically — in one synchronous tick, before starting the
+ * trace read — while the Session is running/compacting.
+ *   - `cursor`: the Session channel's most recently assigned SSE event id
+ *     (`<epoch>-<seq>`); every event published up to and including this id is already
+ *     reflected in `fragments`.
+ *   - `fragments`: one synthetic `partial_* start` OmniMessage per open streaming
+ *     fragment, whose payload carries the full accumulated content so far (text/thinking
+ *     prefix, tool-call name + accumulated arguments, tool-output prefix + images), with
+ *     the original `origin` chain preserved.
+ *
+ * Client usage (the bundled Web App's connect-first flow): after applying `messages`,
+ * when the cursor's epoch matches the epoch of the SSE events seen on the current
+ * connection, drop every buffered **partial** event with seq <= cursor (its content is
+ * already inside `fragments`), feed `fragments` through the normal reducer path, then
+ * replay the rest of the buffer. Buffered **complete** messages are never dropped by the
+ * cursor — the regular overlap dedup decides for them — so nothing is lost even when a
+ * complete message's trace append is still in flight at read time.
+ */
+interface MessagesLiveTail {
+    cursor: string;
+    fragments: OmniMessage[];
+}
 /** 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.
+     */
+    live?: MessagesLiveTail;
 }
 /**
- * A single Prompt's input parts: text or image (data: / http(s) URL).
+ * A single Prompt's input parts: text, image (data: / http(s) URL), or an uploaded file.
  * Docs: /docs/server-api § "Session-Level Endpoints".
  */
 type TaskInputPart = {
@@ -481,6 +527,19 @@ type TaskInputPart = {
 } | {
     type: "image_url";
     imageUrl: string;
+}
+/**
+ * File attachment (the composer's "+" menu): `dataUrl` is a base64 `data:` URL of the
+ * file's bytes, capped at 10MB each (413 `file_too_large` beyond that; the request as a
+ * whole still has to fit the global 20MB body limit). The server writes it into the
+ * Session scratchpad under a sanitized name and appends an `[attached file: <path>]` line
+ * to the message text — the bytes never enter the conversation, the model opens the file
+ * by path. `fileName` is the original name (no path separators, no `..`).
+ */
+ | {
+    type: "file";
+    fileName: string;
+    dataUrl: string;
 };
 interface TaskCreateRequest {
     input: TaskInputPart[];
@@ -497,6 +556,29 @@ interface TaskCreateRequest {
      * (in queue order, one at a time). The response then carries `queued: true`.
      */
     queueIfBusy?: boolean;
+    /**
+     * Present = goal mode: the input's text becomes the objective (leading `[use_skills]`
+     * blocks and the like are stripped from the recorded objective; the round-1 message keeps
+     * them) and the server loops the Session until the goal reaches a terminal state.
+     * `budget` is the token budget (uncached input + output); omitted or -1 = unlimited.
+     */
+    goal?: {
+        budget?: number;
+    };
+}
+/** Goal-mode run state (from goal_state; the chat page's banner restores from the latest row). */
+interface GoalStateView {
+    objective: string;
+    status: "active" | "complete" | "blocked" | "budget_limited" | "aborted";
+    /** Token budget; -1 = unlimited. */
+    budget: number;
+    used: number;
+    rounds: number;
+    updatedAt: string;
+}
+interface GoalResponse {
+    /** The Session's most recent goal run; null if it never ran one. */
+    goal: GoalStateView | null;
 }
 interface TaskCreateResponse {
     /** Current actual session_id: a Trace-less invalid Session self-heals and returns a new id; the frontend updates its route accordingly. */
@@ -511,12 +593,29 @@ interface TaskCreateResponse {
  * task POST).
  */
 interface SteerRequest {
-    /** Non-empty message text (trimmed server-side). */
+    /** Message text (trimmed server-side); may be empty when `images` carries the message. */
     text: string;
+    /**
+     * Images sent with the steering message (`data:` or http(s) URLs, same rule as
+     * `TaskInputPart.image_url`): delivered as user image messages right behind the
+     * `[user_steering]` text. A model without vision receives them as scratchpad path lines
+     * instead, exactly as it would a Prompt's images. At least one of `text` / `images` must
+     * be non-empty.
+     */
+    images?: string[];
 }
 interface ApprovalDecisionRequest {
     decision: "allow" | "deny";
 }
+/**
+ * POST /api/sessions/:sessionId/retry-now — skip the in-progress reconnect backoff and
+ * fire the next retry immediately (the "retry now" button on the reconnect countdown).
+ * `skipped: false` is the benign "no reconnect wait in progress" case (idle session, or
+ * the wait elapsed in a timing race), not an error.
+ */
+interface RetryNowResponse {
+    skipped: boolean;
+}
 /** Docs: /docs/server-api § "Streaming (SSE)". */
 type ServerEvent = 
 /**
@@ -544,6 +643,16 @@ type ServerEvent =
  | {
     type: "resync_required";
 }
+/**
+ * The Project's model credentials changed (PUT /models): cached runtimes have been
+ * invalidated server-side, so an auth-dead Session can continue — the frontend clears
+ * its auth-dead composer state immediately. Published to every existing Session channel
+ * of the Project; tabs without a live channel learn the same fact from the models
+ * response's `updatedAt` on their next load.
+ */
+ | {
+    type: "credentials_updated";
+}
 /** Placeholder handshake on the user channel (reserved for automated task notifications). */
  | {
     type: "hello";
@@ -555,7 +664,32 @@ type ServerEvent =
     agentId: string;
     sessionId: string;
     source: SessionSource;
-} | ScheduleServerEvent;
+} | ScheduleServerEvent | GoalServerEvent;
+/** Goal-mode progress on the session channel (the chat page drives its goal banner from these). */
+type GoalServerEvent = 
+/** A goal run began (published before the first round). */
+{
+    type: "goal_started";
+    sessionId: string;
+    objective: string;
+    budget: number;
+}
+/** A round is starting; `used` is the runner's accounting up to this point. */
+ | {
+    type: "goal_round";
+    sessionId: string;
+    round: number;
+    used: number;
+    budget: number;
+}
+/** The goal reached a terminal state. */
+ | {
+    type: "goal_finished";
+    sessionId: string;
+    outcome: "complete" | "blocked" | "budget_limited" | "aborted";
+    rounds: number;
+    used: number;
+};
 /** Schedule notification (user-level event stream; firing and delivery are notified via /api/events). */
 type ScheduleServerEvent = 
 /** Fired and sent (sessionId is the session that received the Prompt; a new session under new-Session mode). */
@@ -790,6 +924,18 @@ interface AgentTraceDateGroup {
 interface AgentTracesResponse {
     dates: AgentTraceDateGroup[];
 }
+interface TraceImportRequest {
+    /** Base64 of the Trace file content (JSON Lines; the first record must be `session_meta`). */
+    dataBase64: string;
+}
+interface TraceImportResponse {
+    /** Session id taken from the imported file's `session_meta`. */
+    sessionId: string;
+    /** Allocated file index: always 1 — an import creates a new Session (a duplicate session id is rejected with 409 `trace_session_exists`). */
+    index: number;
+    /** Date directory the file landed in (local yyyy-mm-dd from the first record's timestamp, matching the Trace Writer's convention). */
+    date: string;
+}
 type UsageGroupBy = "date" | "agent" | "model" | "session";
 interface UsageBucket {
     total: number;
@@ -871,9 +1017,20 @@ interface UsageErrors {
     unexpected: number;
     /** The most frequent source · code (null when there are no errors). */
     topCode: UsageErrorCount | null;
-    /** Most recent N items (reverse chronological). */
+    /** Most recent N items (reverse chronological) — the first page; older ones come from `GET /usage/errors`. */
     recent: UsageErrorItem[];
 }
+/**
+ * GET /api/projects/:projectId/usage/errors — one page of the error detail table, newest
+ * first. The dashboard response above already carries the first page; this exists so
+ * "show me earlier ones" does not have to refetch the whole aggregate. It takes the same
+ * date/agent filter as the dashboard, so a page never widens what the summary counted.
+ */
+interface UsageErrorsPage {
+    items: UsageErrorItem[];
+    /** Filtered row count, so the caller knows when it has reached the end. */
+    total: number;
+}
 interface UsageResponse {
     summary: {
         today: UsageBucket;
@@ -961,21 +1118,22 @@ interface AgentImportResponse {
 /** Raw result of a single run (a scoreboard per-case runs[] entry). */
 interface BenchmarkRunScore {
     score: number;
-    cost?: number;
-    durationMs?: number;
+    /** Run cost, or null when unavailable. */
+    cost: number | null;
+    durationMs: number;
     /** Id of the Session under test in this run (links to Trace). */
-    sessionId?: string;
+    sessionId: string;
 }
 interface BenchmarkCaseScore {
     case: string;
-    /** Per-case score = average of runs (equals that single run's score under the legacy single-run format). */
+    /** Model-written average of this Case's Run scores, on the fixed 0..100 scale. */
     score: number;
-    cost?: number;
-    durationMs?: number;
-    /** For legacy format compatibility: per-case single Session id (new format keeps it inside runs[]). */
-    sessionId?: string;
-    /** Raw results per run; unset under the legacy format (the server backfills one entry when parsing as a single run). */
-    runs?: BenchmarkRunScore[];
+    /** Model-written average of known Run costs; null when every Run cost is unknown. */
+    cost: number | null;
+    /** Model-written average of Run durations, rounded to an integer. */
+    durationMs: number;
+    /** Raw results per Run. */
+    runs: BenchmarkRunScore[];
 }
 interface BenchmarkEvaluation {
     /** Evaluation timestamp (ISO 8601). */
@@ -985,15 +1143,19 @@ interface BenchmarkEvaluation {
     /** Evaluation summary body: how the score was derived, what optimizations were made to the Agent this round (required when generating, tolerated as unset when displaying). */
     summary?: string;
     /** Model actually used for this evaluation round (upstream id, paired with provider; the chart series is split by model). */
-    modelId?: string;
+    modelId: string;
     /** Provider group for `modelId`. */
-    provider?: string;
+    provider: string;
+    /** Thinking level read from the unchanged Target Agent configuration. */
+    thinkingLevel: string;
     /** Agent State version number under test. */
-    version?: number;
-    /** Total score (sum of per-case scores; max score defined by the scoring rubric). */
+    version: number;
+    /** Model-written average of Case scores, on the fixed 0..100 scale. */
     score: number;
-    cost?: number;
-    durationMs?: number;
+    /** Model-written average of known Case costs; null when every Case cost is unknown. */
+    cost: number | null;
+    /** Model-written average of Case durations, rounded to an integer. */
+    durationMs: number;
     cases: BenchmarkCaseScore[];
 }
 interface BenchmarkSummary {
@@ -1012,6 +1174,15 @@ interface BenchmarkSummary {
 interface BenchmarksResponse {
     benchmarks: BenchmarkSummary[];
 }
+/** Public Benchmark Case metadata. Rubric and Gold content are never included. */
+interface BenchmarkCaseSummary {
+    id: string;
+    /** First Markdown heading with an optional leading "Case N:" removed; falls back to id. */
+    title: string;
+}
+interface BenchmarkCasesResponse {
+    cases: BenchmarkCaseSummary[];
+}
 interface SkillMetadataItem {
     /** Skill directory name (the identity key for install / uninstall / Prompt addressing). */
     name: string;
@@ -1045,5 +1216,53 @@ interface AgentSkillsResponse {
 interface SkillInstallRequest {
     names: string[];
 }
+/** 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/update-check: newest published release vs the running version.
+ * Always HTTP 200 (fail-soft): a lookup failure sets `error` and leaves `latestVersion`
+ * null rather than failing the request; results are cached server-side.
+ */
+interface UpdateCheckResponse {
+    currentVersion: string;
+    /** Same as VersionResponse.buildDate: the running version's release date, stamped at build time. */
+    buildDate: string | null;
+    /** Newest published release (normalized, no leading `v`); null when the lookup failed or checks are disabled. */
+    latestVersion: string | null;
+    updateAvailable: boolean;
+    /** Release page of the newest release (for the "release notes" link). */
+    releaseUrl: string | null;
+    /** Publish timestamp of the newest release (ISO 8601). */
+    publishedAt: string | null;
+    /** When this result was produced (ISO 8601) — a cached result keeps its original timestamp. */
+    checkedAt: string;
+    /** Present (true) when update checks are turned off via PENGUIN_UPDATE_CHECK=off; no network call was made. */
+    disabled?: true;
+    /** Why the lookup failed: unreachable network / GitHub rate limit / unusable response. */
+    error?: "network" | "rate_limited" | "bad_response";
+}
+/**
+ * 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
+ * CLI's own refusals (source checkout, unrecognized install layout, Windows).
+ */
+interface UpdateRunResponse {
+    status: "updated" | "failed" | "unsupported";
+    /** Set when the server cannot run the CLI at all (started without `penguin server|web`). */
+    reason?: "not_launched_via_cli";
+    /** Tail of the update command's combined stdout+stderr (capped; empty when nothing ran). */
+    output: string;
+    /** True when the install changed (or was already current): restart the service to run the new version. */
+    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, BenchmarkEvaluation, BenchmarkRunScore, BenchmarkSummary, BenchmarksResponse, CredentialInfo, DirEntryInfo, DirListResponse, ErrorBody, FilesStatRequest, FilesStatResponse, MeResponse, MemberAddRequest, MemberAddResponse, MemberInfo, MembersResponse, MessagesResponse, ModelInfo, ModelPricingDto, ModelRefDto, ModelTestRequest, ModelTestResponse, ModelUpdateEntry, ModelsResponse, ModelsUpdateRequest, PasswordChangeRequest, PrefsResponse, ProjectCreateRequest, ProjectCreateResponse, ProjectRole, ProjectSummary, ProjectsResponse, RequestSpan, 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, TraceModelSegment, TraceTaskStats, TraceToolSpan, UiPrefs, UsageAgentCount, UsageBucket, UsageErrorCount, UsageErrorItem, UsageErrors, UsageGroupBy, UsageGroupRow, UsageResponse, UsageSuccessRate, UsageTrendPoint, UsageTrendPointInTrace, UserInfo, VaultEntryInfo, VaultEntryUpdate, VaultResponse, VaultUpdateRequest, WorkspaceFileEntry, WorkspaceFilesResponse };
+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, 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, 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 };