@prismshadow/penguin-server 0.1.2 → 0.1.4

package/dist/api/types.d.ts

@@ -186,6 +186,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,9 +474,41 @@ 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).
@@ -497,6 +536,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. */
@@ -517,6 +579,15 @@ interface SteerRequest {
 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 +615,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 +636,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 +896,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;
@@ -1045,5 +1163,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, 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, 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, UsageGroupBy, UsageGroupRow, UsageResponse, UsageSuccessRate, UsageTrendPoint, UsageTrendPointInTrace, UserInfo, VaultEntryInfo, VaultEntryUpdate, VaultResponse, VaultUpdateRequest, VersionResponse, WorkspaceFileEntry, WorkspaceFilesResponse };