@prismshadow/penguin-server 0.1.1 → 0.1.4

package/dist/api/types.d.ts

@@ -48,6 +48,15 @@ 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 —
+     * 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;
 }
 interface PasswordChangeRequest {
     oldPassword: string;
@@ -177,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). */
@@ -382,13 +398,40 @@ interface SessionInfo {
     status: SessionStatus;
     /** Number of approvals awaiting human decision (a persisted count outside server events, for list badges). */
     pendingApprovalCount: number;
+    /** Number of queued follow-up tasks (`queueIfBusy`) awaiting auto-start once the session is idle. */
+    pendingFollowUpCount: number;
     /** Whether a Trace record exists (a Task has been started). */
     hasTrace: boolean;
     /** Whether archived (hidden from the default list, grouped under "Archived"). */
     archived: boolean;
+    /**
+     * Absolute path of the session's latest Trace file (the current context shard); absent
+     * when no Trace exists yet. Populated on the **single-session GET only** — list rows omit
+     * it (locating it costs a directory walk per Session). The web's `/model` switch puts it
+     * into the new session's `[model_switch_from]` block so the model can read the source
+     * history itself when it needs it.
+     */
+    tracePath?: string;
 }
+/**
+ * Session list category, the sidebar's four-way split applied server-side: archived wins
+ * regardless of origin (archiving is an explicit user action), then the origin's bucket,
+ * and a Session with no (or an unknown) source is `active` — user-created rows.
+ */
+type SessionCategory = "active" | SessionSource | "archived";
+/** Per-category totals across an Agent's whole Session list (returned when the list is requested with counts). */
+type SessionCategoryCounts = Record<SessionCategory, number>;
 interface SessionsResponse {
     sessions: SessionInfo[];
+    /** Present when the request asked for counts (`counts=1`): totals per category over the full list, not just the returned page. */
+    counts?: SessionCategoryCounts;
+    /**
+     * Present with `counts`: the same totals broken down by Workspace path (only paths
+     * with at least one Session appear). The sidebar's workspace grouping decides each
+     * group's folders and "More" from its own share, so a group never advertises
+     * content that lives in other Workspaces.
+     */
+    workspaceCounts?: Record<string, SessionCategoryCounts>;
 }
 /** Server directory browsing (advanced new-Workspace picker): starts from the home directory by default, can navigate up to the root. */
 interface DirEntryInfo {
@@ -431,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).
@@ -448,14 +523,71 @@ type TaskInputPart = {
 };
 interface TaskCreateRequest {
     input: TaskInputPart[];
+    /**
+     * Thinking level for this Task's LLM requests (a per-turn parameter; one of
+     * `none | low | medium | high | xhigh`, anything else is a 400). Omitted = falls back to
+     * the session's default (the Agent config's `model.thinking_level`). A queued follow-up
+     * (`queueIfBusy`) keeps its level and applies it when it auto-starts.
+     */
+    thinkingLevel?: ThinkingLevelName;
+    /**
+     * Queue instead of 409 when a Task/compaction is already in progress: the input is held
+     * server-side and auto-starts as an ordinary next task once the session returns to idle
+     * (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. */
     sessionId: string;
+    /** True when `queueIfBusy` enqueued the input as a follow-up instead of starting it (absent/false: the task started). */
+    queued?: boolean;
+}
+/**
+ * Mid-run steering (POST /api/sessions/:id/steer): a user message for the **running** Task,
+ * delivered by core between turns as a standalone `[user_steering]` user message. 202 on
+ * queue; 409 `not_running` when no Task is in progress (the frontend falls back to a normal
+ * task POST).
+ */
+interface SteerRequest {
+    /** Non-empty message text (trimmed server-side). */
+    text: 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 = 
 /**
@@ -467,10 +599,11 @@ type ServerEvent =
     toolCall: OmniMessage<ToolCallPayload>;
     origin?: string[];
 }
-/** Session run status flip (for toggling the input area and list). */
+/** Session run status flip (for toggling the input area and list); `queued` = queued follow-up count (see TaskCreateRequest.queueIfBusy). */
  | {
     type: "task_state";
     state: SessionStatus;
+    queued?: number;
 }
 /** The model-generated title after the first turn has been persisted (for in-place list updates). */
  | {
@@ -482,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";
@@ -493,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). */
@@ -582,7 +750,7 @@ interface TraceTaskStats {
     /**
      * This turn's duration span: `startTs` = the moment of this turn's **first `request_begin`**
      * — duration only looks at LLM requests, not the timestamp of user text like the user
-     * Prompt / compaction summary (`<context_summary>` is created during compaction but only
+     * Prompt / compaction summary (`[context_summary]` is created during compaction but only
      * persisted on the next run; resuming the next day would inflate the first turn by a whole
      * day for no reason); `endTs` = the moment of the last non-session_meta message in the
      * range. For a degenerate turn with no Request at all (interrupted right after sending),
@@ -728,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;
@@ -983,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, SessionCreateRequest, SessionCreateResponse, SessionInfo, SessionPatchRequest, SessionResponse, SessionSource, SessionStatus, SessionTracesResponse, SessionsResponse, SkillGroupItem, SkillInstallRequest, SkillLibraryResponse, SkillMetadataItem, 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 };