@cloudcli-ai/cloudcli 1.37.2 → 1.37.4

package/server/shared/types.ts

@@ -94,6 +94,13 @@ export type ProviderModelOption = {
 export type ProviderModelsDefinition = {
   OPTIONS: ProviderModelOption[];
   DEFAULT: string;
+  /**
+   * Reasoning-effort levels a custom entry of this catalog may declare, weakest
+   * first; empty for providers without effort support. The Providers service
+   * sets it on merged catalogs from the capability matrix, so the model
+   * library offers the same levels on every machine. Adapter catalogs omit it.
+   */
+  EFFORT_LEVELS?: string[];
 };
 
 /**
@@ -110,6 +117,22 @@ export type CustomProviderModelRecord = {
   modelId: string;
   model: string;
   sortOrder: number;
+  /** NULL for rows that never declared effort levels, including pre-existing rows. */
+  effort: CustomProviderModelEffort | null;
+};
+
+/**
+ * Reasoning-effort levels a user declared for one custom model.
+ *
+ * `values` holds unique, non-empty level ids drawn from the levels the
+ * provider's predefined models declare, and is never empty (an empty
+ * declaration is stored as NULL). `default`, when present, is one of `values`
+ * and documents the level the provider applies when the composer sends
+ * `Default`, mirroring `ProviderModelOption['effort'].default`.
+ */
+export type CustomProviderModelEffort = {
+  values: string[];
+  default?: string;
 };
 
 /**
@@ -122,6 +145,12 @@ export type CustomProviderModelRecord = {
 export type CustomProviderModelInput = {
   id: string;
   model: string;
+  /**
+   * Optional reasoning-effort declaration. `undefined` leaves stored metadata
+   * untouched on update (and stores none on create) so clients that predate
+   * effort metadata keep working; `null` clears it.
+   */
+  effort?: CustomProviderModelEffort | null;
 };
 
 // ---------------------------
@@ -186,10 +215,12 @@ export type MessageKind =
   | 'complete'
   | 'status'
   | 'permission_request'
+  | 'permission_resolved'
   | 'permission_cancelled'
   | 'session_created'
-  | 'interactive_prompt'
-  | 'task_notification';
+  | 'history_truncated'
+  | 'task_notification'
+  | 'task_status';
 
 /**
  * Event kinds added by the chat gateway layer on top of provider message kinds.
@@ -215,14 +246,75 @@ export type GatewayEventKind =
  */
 export type ServerEventKind = MessageKind | GatewayEventKind;
 
+/** The owning project as it appears inside a `session_upserted` delta. */
+export type SessionUpsertedProject = {
+  projectId: string;
+  path: string;
+  fullPath: string;
+  displayName: string;
+  isStarred: boolean;
+};
+
+/**
+ * The `session_upserted` sidebar delta, built only by
+ * `modules/websocket/services/session-upsert-broadcast.service.ts`.
+ *
+ * Typed rather than assembled as an untyped object literal because the payload
+ * used to be built in two places and silently drifted apart: one copy set
+ * `providerSessionId` and the other did not, and nothing could detect it.
+ *
+ * `providerSessionId` is how a client recognises that a row it is currently
+ * showing has been merged into its canonical app-session row, so it is always
+ * present — `null` only while the provider has not reported an id yet.
+ */
+export type SessionUpsertedEvent = {
+  kind: 'session_upserted';
+  sessionId: string;
+  providerSessionId: string | null;
+  provider: LLMProvider;
+  session: {
+    id: string;
+    summary: string;
+    messageCount: number;
+    lastActivity: string;
+  };
+  project: SessionUpsertedProject | null;
+  timestamp: string;
+};
+
 /**
  * Provider-neutral message envelope used in REST responses and realtime channels.
  *
  * Every provider-specific message must be converted into this shape before being
  * emitted outside provider-specific modules.
  */
+/**
+ * A compaction, as the transcript records it.
+ *
+ * `running` is the status the CLI sends when it starts compacting, `done` the
+ * boundary it sends when it has, `failed` a compaction that did not finish.
+ * The token counts and duration only come with a boundary.
+ */
+export type CompactionInfo = {
+  phase: 'running' | 'done' | 'failed';
+  /** Whether the user asked for it or the context window did. */
+  trigger?: 'manual' | 'auto';
+  /** Tokens the conversation held before and after, when the boundary reports them. */
+  preTokens?: number;
+  postTokens?: number;
+  durationMs?: number;
+  error?: string | null;
+};
+
 export type NormalizedMessage = {
   id: string;
+  /**
+   * The provider's own identifier for the transcript row this message came
+   * from, when the provider has stable per-row identity (today: Claude's
+   * `uuid`). It is what "edit this message" and "fork from here" address, so it
+   * has to survive a reload — never a value this app synthesized.
+   */
+  transcriptAnchorId?: string;
   sessionId: string;
   timestamp: string;
   provider: LLMProvider;
@@ -236,6 +328,15 @@ export type NormalizedMessage = {
   seq?: number;
   role?: 'user' | 'assistant';
   content?: string;
+  /**
+   * The model that produced this assistant message, as the provider reported
+   * it on the transcript row (today: Claude's `message.model`, e.g.
+   * `claude-opus-5`). Absent on user turns — no provider records which model a
+   * request went out with — and absent when the provider named a placeholder
+   * such as `<synthetic>`, so a locally-fabricated notice is never labelled
+   * with a model it did not run on.
+   */
+  model?: string;
   /**
    * Optional display-oriented metadata used by providers that need to expose
    * richer transcript artifacts without introducing a brand-new message kind.
@@ -251,6 +352,8 @@ export type NormalizedMessage = {
   isLocalCommand?: boolean;
   isLocalCommandStdout?: boolean;
   isCompactSummary?: boolean;
+  /** Set on the row that stands in for a compaction, so the UI can draw it as one. */
+  compact?: CompactionInfo;
   images?: unknown;
   /** Non-image files attached to a user turn after provider history normalization. */
   files?: unknown;
@@ -274,13 +377,226 @@ export type NormalizedMessage = {
   status?: string;
   summary?: string;
   tokenBudget?: unknown;
-  subagentTools?: unknown;
+  /**
+   * Timeline of everything a subagent did, attached to the `tool_use` that
+   * spawned it. Present for Claude `Agent`/`Task` calls and Codex
+   * `spawn_agent` calls; absent for every other tool.
+   */
+  subagentTools?: SubagentActivity[];
+  /** Identity and lifecycle of the subagent this `tool_use` spawned. */
+  subagent?: SubagentInfo;
+  /** The workflow run this `tool_use` launched, read from its journal on disk. */
+  workflow?: WorkflowInfo;
+  /** Stored memory the reply drew on, when the provider reports it. */
+  memoryCitations?: MemoryCitation[];
   toolUseResult?: unknown;
   sequence?: number;
   rowid?: number;
+  /**
+   * `task_status` fields: one lifecycle event of a background task the live
+   * run is tracking. `taskId` is the provider's task handle; `toolUseId` names
+   * the call that launched it and is absent on `updated`, which the SDK keys by
+   * task id alone. `status` and `summary` above carry the event's own.
+   */
+  event?: 'started' | 'progress' | 'updated' | 'notification';
+  taskId?: string;
+  toolUseId?: string;
+  taskType?: string;
+  workflowName?: string;
+  description?: string;
+  usage?: TaskUsage;
+  outputFile?: string;
+  /** A workflow's `progress` only: where each agent the run spawned stands. */
+  agents?: WorkflowAgentProgress[];
   [key: string]: unknown;
 };
 
+/**
+ * What a background task has spent so far, as the CLI reports it on
+ * `task_progress` and `task_notification`.
+ */
+export type TaskUsage = {
+  totalTokens: number;
+  toolUses: number;
+  durationMs: number;
+};
+
+/**
+ * One background task a live session still has outstanding — a spawned
+ * agent, a workflow run or a backgrounded command — as the runtime tracks it
+ * from the stream's `task_started` until the event that settles it.
+ *
+ * `taskId` is the handle a stop request names; `toolUseId` is the call that
+ * launched it, which is how the client pairs the task with its card.
+ * `startedAt` is the server clock at `task_started`, so a session whose turn
+ * has ended can still report how long its work has been going.
+ */
+export type BackgroundTaskSummary = {
+  taskId: string;
+  toolUseId: string;
+  taskType: string;
+  description: string;
+  workflowName?: string;
+  startedAt: number;
+  /**
+   * The task was launched by a subagent or workflow agent, not by the
+   * session's own turn: its `toolUseId` names a call in that agent's
+   * transcript, so no card in this session's transcript matches it. Listed so
+   * it can still be stopped; not counted as the session's own work.
+   */
+  nested?: boolean;
+};
+
+/**
+ * Where one agent of a running workflow stands, as the SDK reports it on the
+ * run's `task_progress` events.
+ *
+ * An entry the script has queued but not yet started has no `agentId` and is
+ * identified by `index` alone; once the agent runs, `agentId` names the
+ * transcript it writes. `lastToolName` and `lastToolSummary` are the agent's
+ * own latest tool call — unlike the event's task-level `last_tool_name`, which
+ * for a workflow is the current agent's label.
+ */
+export type WorkflowAgentProgress = {
+  index: number;
+  label?: string;
+  /** The title of the script phase the agent runs under, when it has one. */
+  phase?: string;
+  agentId?: string;
+  model?: string;
+  state: 'queued' | 'running' | 'done' | 'failed';
+  startedAt?: number;
+  lastToolName?: string;
+  lastToolSummary?: string;
+  promptPreview?: string;
+  tokens?: number;
+  toolCalls?: number;
+  durationMs?: number;
+  resultPreview?: string;
+};
+
+/**
+ * One workflow agent's recorded timeline, read from its transcript on demand
+ * when the card is opened — the SDK never streams an agent's own rows to the
+ * parent session, so this is the only way to see what it did.
+ *
+ * `activityCount` is the full length of the timeline; `activity` is capped
+ * for transport like a subagent's `subagentTools`.
+ */
+export type WorkflowAgentActivity = {
+  agent: {
+    id: string;
+    label?: string;
+    model?: string;
+    status: 'running' | 'completed' | 'failed' | 'stopped';
+  };
+  activity: SubagentActivity[];
+  activityCount: number;
+};
+
+/**
+ * One agent a workflow run spawned, as its journal records it.
+ *
+ * `label` and `phase` are whatever the script passed when it spawned the
+ * agent; older scripts passed neither. An agent with a `started` record and no
+ * `result` or `failed` one is still running as far as the journal knows.
+ */
+export type WorkflowAgentInfo = {
+  id: string;
+  label?: string;
+  phase?: string;
+  /** `stopped` is an agent the journal never settled although the run itself has — abandoned by a stop or a resume that re-ran the step. */
+  status: 'running' | 'completed' | 'failed' | 'stopped';
+};
+
+/**
+ * A `Workflow` tool call's run, attached to the `tool_use` that launched it.
+ *
+ * `status` follows the same rule as a background agent's: the task
+ * notification's word when one exists, else `running` only while the process
+ * that launched it is still up, else `stopped`. The agent list and counts come
+ * from `<transcriptDir>/journal.jsonl`; both are empty when the run left no
+ * journal behind (a fork copies only the parent's transcript).
+ */
+export type WorkflowInfo = {
+  runId: string;
+  name: string;
+  description?: string;
+  status: 'running' | 'completed' | 'failed' | 'stopped';
+  agents: WorkflowAgentInfo[];
+  agentCounts: { total: number; completed: number; failed: number; running: number; stopped: number };
+  scriptPath?: string;
+};
+
+/**
+ * One stored memory an assistant reply drew on.
+ *
+ * Codex appends these to a reply that used its memory files, naming the file
+ * and line range it read plus a short note on what it took from there. The
+ * transcript shows them as a footnote so a memory-derived claim is traceable
+ * rather than arriving as an unattributed assertion.
+ */
+export type MemoryCitation = {
+  /** File and line range that was read, e.g. `MEMORY.md:137-142`. */
+  source: string;
+  /** What the reply took from that range, when the provider states it. */
+  note?: string;
+};
+
+/**
+ * One entry in a subagent's recorded timeline.
+ *
+ * Providers store a subagent's work in a separate transcript (Claude:
+ * `<session>/subagents/agent-<id>.jsonl`; Codex: a sibling rollout keyed by
+ * `agent_thread_id`). Both are flattened into this shape so the transcript can
+ * replay a subagent's run with the same renderers the main thread uses.
+ *
+ * `kind` decides which fields matter: `tool` uses the tool fields, `text` and
+ * `thinking` use `content`. Consumers must not assume tool fields exist on the
+ * text kinds.
+ */
+export type SubagentActivity = {
+  kind: 'tool' | 'text' | 'thinking';
+  timestamp?: string;
+  /** Tool-call identity; only set when `kind` is `tool`. */
+  toolId?: string;
+  toolName?: string;
+  toolInput?: unknown;
+  toolResult?: { content?: string; isError?: boolean } | null;
+  /** Message body; only set when `kind` is `text` or `thinking`. */
+  content?: string;
+};
+
+/**
+ * Identity and lifecycle of one spawned subagent, normalized across providers.
+ *
+ * `status` is `running` until the call that spawned the agent resolves. After
+ * that it is whatever the provider reported — Claude's task notification
+ * carries one — and `completed` when the provider reported nothing. A failed
+ * tool call *inside* the agent is not a failed agent, so it is never inferred
+ * from the transcript. A background agent whose session process ended before
+ * it reported is `stopped`: no outcome exists and none is coming.
+ */
+export type SubagentInfo = {
+  /** Provider-native agent id — Claude `agentId`, Codex `agent_thread_id`. */
+  id: string;
+  /** Human-facing label: Claude's agent type, or Codex's assigned nickname. */
+  name?: string;
+  /** Agent type/preset when the provider records one (Claude `agentType`). */
+  type?: string;
+  /** One-line task summary shown in the collapsed header. */
+  description?: string;
+  status: 'running' | 'completed' | 'failed' | 'stopped';
+  /** Model the subagent ran on, when the provider records it. */
+  model?: string;
+  /**
+   * How many activities the agent actually recorded. It exceeds
+   * `subagentTools.length` when a long run was truncated for transport, which
+   * lets the UI say so instead of silently showing a partial timeline.
+   */
+  activityCount?: number;
+};
+
 /**
  * Output gateway shared by WebSocket and SSE provider runs.
  *
@@ -292,7 +608,6 @@ export type ProviderRuntimeWriter = {
   setSessionId?(sessionId: string): void;
   userId?: string | number | null;
   isWebSocketWriter?: boolean;
-  isSSEStreamWriter?: boolean;
 };
 
 export type ProviderPermissionDecision = {
@@ -322,6 +637,15 @@ export type ProviderRuntimeContext = {
   getProviderModels(): Promise<ProviderModelsDefinition>;
   normalizeMessage(raw: unknown, sessionId: string | null): NormalizedMessage[];
   isProviderInstalled(): Promise<boolean>;
+  /**
+   * Builds the SDK query for a run. Production leaves this unset and the
+   * runtime uses the SDK's own; tests supply a scripted stream so the hold
+   * and background-work paths can be driven without a CLI process.
+   */
+  createQuery?: (input: { prompt: AsyncIterable<unknown>; options: AnyRecord }) => AsyncIterable<unknown> & {
+    interrupt(): Promise<void>;
+    stopTask?(taskId: string): Promise<void>;
+  };
 };
 
 export type ProviderRunFunction = (
@@ -546,6 +870,29 @@ export type UpsertProviderMcpServerInput = {
 
 // ---------------------------
 //----------------- PROVIDER AUTH TYPES ------------
+/**
+ * Records that an API-key style credential is taking precedence over a
+ * still-valid subscription login in `~/.claude/.credentials.json`.
+ *
+ * Claude Code always prefers `ANTHROPIC_AUTH_TOKEN` / `ANTHROPIC_API_KEY` over
+ * the OAuth login written by `claude /login`, so when both exist every request
+ * is billed to the key (pay-as-you-go) rather than the subscription — usually
+ * without the user realising it. The Claude auth provider fills this in so the
+ * settings UI can say which variable won and where it was found; the fix
+ * differs per source (unset the variable and restart the server for
+ * `process_env`, edit the `env` block of `~/.claude/settings.json` for
+ * `settings_file`). It is never set when the login in the credentials file is
+ * missing or expired, because then nothing is being bypassed.
+ */
+export type ProviderAuthSubscriptionOverride = {
+  /** The environment variable Claude Code is using instead of the login. */
+  variable: 'ANTHROPIC_API_KEY' | 'ANTHROPIC_AUTH_TOKEN';
+  /** Where that variable was found: the server process env or the settings.json env block. */
+  source: 'process_env' | 'settings_file';
+  /** Email recorded in the credentials file for the bypassed login, when known. */
+  subscriptionEmail: string | null;
+};
+
 /**
  * Authentication status result returned by provider health checks.
  *
@@ -559,6 +906,12 @@ export type ProviderAuthStatus = {
   email: string | null;
   method: string | null;
   error?: string;
+  /**
+   * Present only when `method` is `api_key` and a valid subscription login is
+   * being bypassed; see ProviderAuthSubscriptionOverride. Omitted otherwise so
+   * existing consumers that never look for it are unaffected.
+   */
+  subscriptionOverride?: ProviderAuthSubscriptionOverride;
 };
 
 // ---------------------------
@@ -642,12 +995,13 @@ export type WorkspacePathValidationResult = {
 };
 
 // ---------------------------
-//----------------- GIT WORKTREE MANAGEMENT ------------
+//----------------- GIT COMMAND EXECUTION AND WORKTREE MANAGEMENT ------------
 /**
  * Captured output of one completed `git` invocation.
  *
- * Returned by `GitCommandRunner` implementations so worktree services can read
- * both streams without caring about process plumbing.
+ * Returned by `GitCommandRunner` and `GitProcessRunner` implementations so the
+ * git and worktree services can read both streams without caring about
+ * process plumbing.
  */
 export type GitCommandResult = {
   stdout: string;
@@ -664,6 +1018,20 @@ export type GitCommandResult = {
  */
 export type GitCommandRunner = (args: string[], cwd: string) => Promise<GitCommandResult>;
 
+/**
+ * Executes `command args...` inside `options.cwd` and resolves with the captured output.
+ *
+ * This is the `spawnAsync` shape the Git routes module injects into its typed
+ * services (branch deletion, branch compare) so their tests can substitute a
+ * fake runner. Like `GitCommandRunner`, the promise must reject on a non-zero
+ * exit code, with `stderr` attached to the error when available.
+ */
+export type GitProcessRunner = (
+  command: string,
+  args: string[],
+  options: { cwd: string },
+) => Promise<GitCommandResult>;
+
 /**
  * One entry parsed from `git worktree list --porcelain`.
  *
@@ -987,6 +1355,13 @@ export type FileTreeProjectGateway = {
 export type FileTreeWorkspaceGateway = {
   rootPath: string;
   validatePath(candidatePath: string): Promise<WorkspacePathValidationResult>;
+  /**
+   * Resolves a path readable outside the workspace root — the system temp
+   * directory and the Claude projects directory — or `null` when it is not
+   * one. Read-only: the write policy is `validatePath` and it does not consult
+   * this.
+   */
+  resolveReadOnlyRootPath(candidatePath: string): Promise<string | null>;
 };
 
 /**