@sanqianx/claude-ai-workbench 0.13.2 → 0.13.4

package/packages/contracts/index.d.ts

@@ -1,517 +1,519 @@
-export type PermissionMode = "default" | "acceptEdits" | "plan" | "bypassPermissions";
-export type ProfileProtocol = "anthropic-compatible" | "openai-compatible" | string;
-export type AgentId = "claude-code" | "codex" | "opencode" | "zcode";
-export type EffortLevel = "low" | "medium" | "high" | "max";
-
-export interface AgentCapabilities {
-  backgroundTasks?: boolean;
-  thinking: boolean;
-  permissions: boolean;
-  toolStream: boolean;
-  images: boolean;
-  resume: true;
-  modelOverride: boolean;
-  generationParams: readonly string[];
-}
-
-export interface AgentDefinition {
-  id: AgentId;
-  label: string;
-  transport: string;
-  authModes: readonly string[];
-  capabilities: AgentCapabilities;
-}
-
-export interface AgentStatus extends AgentDefinition {
-  scanState?: 'unknown' | 'ready' | 'error';
-  checkedAt?: string;
-  errorCode?: string | null;
-  capabilities: { generationParams: string[] } & Omit<AgentCapabilities, "generationParams">;
-  available: boolean;
-  version: string | null;
-}
-
-export interface Project {
-  id: string;
-  name: string;
-  rootPath: string;
-  createdAt: string;
-  updatedAt: string;
-  defaultAiProfileId?: string | null;
-  defaultModel?: string | null;
-  defaultAgentId?: AgentId;
-}
-
-export interface ProjectInput {
-  name: string;
-  rootPath: string;
-  defaultAiProfileId?: string | null;
-  defaultModel?: string | null;
-  defaultAgentId?: AgentId;
-}
-
-export type ProjectPatch = Partial<Omit<ProjectInput, "rootPath">>;
-
-export interface ModelListEntry {
-  id: string;
-  openaiId?: string;
-  label: string;
-  tags: string[];
-}
-
-export interface WorkbenchContext {
-  contextId: string;
-  contextType?: string;
-  displayName?: string;
-  workspaceRef?: string;
-  aiProfileId?: string | null;
-  model?: string | null;
-  metadata?: Record<string, unknown>;
-}
-
-export interface AiProfileModels {
-  default: string;
-  fast?: string;
-  reasoning?: string;
-  coding?: string;
-  largeContext?: string;
-  list?: ModelListEntry[];
-  [role: string]: string | undefined | ModelListEntry[];
-}
-
-export interface AiProfileInput {
-  id: string;
-  name?: string;
-  provider: string;
-  protocol?: ProfileProtocol;
-  runtime?: "claude-code";
-  baseUrl: string;
-  openaiBaseUrl?: string;
-  credentialRef?: string;
-  models: AiProfileModels;
-  contextWindow?: number;
-  timeoutMs?: number;
-  permissionMode?: PermissionMode;
-  systemPrompt?: Record<string, unknown> | string;
-  enabled?: boolean;
-}
-
-export interface AiProfile extends AiProfileInput {
-  name: string;
-  protocol: ProfileProtocol;
-  runtime: "claude-code";
-  credentialRef: string;
-  contextWindow: number;
-  timeoutMs: number;
-  permissionMode: PermissionMode;
-  systemPrompt: Record<string, unknown>;
-  enabled: boolean;
-  credentialConfigured?: boolean;
-  credentialMasked?: string;
-}
-
-export interface CredentialInput { secret: string; }
-
-export interface ProfileTestResult {
-  ok: true;
-  runtime: "claude-code";
-  runtimeVerified: true;
-  profileId: string;
-  model: string;
-  firstEventMs: number;
-  durationMs: number;
-  resultPreview: string;
-}
-
-export interface HealthResult {
-  status: "ok";
-  version: string;
-  apiVersion: string;
-  activeProcesses: number;
-  sessions: number;
-  time: string;
-  /** Absent on servers built before task identity existed. */
-  taskIdentity?: TaskRuntimeIdentity;
-}
-
-// Task identity reported via /health. storeScope is the persistent store id
-// (null when the store file could not be established); runtimeEpoch is a
-// per-service-instance generation that is never persisted.
-export interface TaskRuntimeIdentity {
-  storeScope: string | null;
-  runtimeEpoch: string;
-  available: boolean;
-  errorCode: string | null;
-}
-
-export interface RuntimeInfo {
-  runtime: "claude-code";
-  available: boolean;
-  executable: string | null;
-  transport: string;
-}
-
-export interface SessionSummary {
-  tasks?: BackgroundTask[];
-  backgroundTaskCount?: number;
-  sessionId: string;
-  contextId: string;
-  projectId: string;
-  agentId: AgentId;
-  title: string;
-  active: boolean;
-  state: string;
-  model: string | null;
-  aiProfileId: string | null;
-  providerName?: string | null;
-  authSource?: "profile-injected" | "agent-owned";
-  selectedModel?: string | null;
-  permissionMode: PermissionMode;
-  archived: boolean;
-  turns: number;
-  startedAt: string;
-  updatedAt: string;
-  connectionState: string;
-}
-
-export type ResyncReason = "stale-cursor" | "history-gap";
-
-export interface BackgroundTask {
-  taskId: string;
-  parentSessionId: string;
-  toolUseId?: string;
-  status: 'pending' | 'running' | 'completed' | 'failed' | 'stopped';
-  description?: string;
-  summary?: string;
-  lastToolName?: string;
-  usage?: {total_tokens?: number; tool_uses?: number; duration_ms?: number};
-}
-
-// Task identity: opaque, already-resolved ids. storeScope is the stable storage
-// identity - never a port, PID or runtime epoch.
-export interface TaskScope {
-  storeScope: string;
-  contextId: string;
-  parentSessionId: string;
-}
-
-export interface NativeTaskRef extends TaskScope {
-  kind: "native-task";
-  ownerRunId: string;
-  taskId: string;
-}
-
-// Native task-history reads (GET /sessions/:id/native-tasks and POST
-// /sessions/:id/native-tasks/history). Every field mirrors what the reviewed
-// reader actually returns; null means "not observed in the journal", never a
-// fabricated placeholder.
-export type NativeTaskAssociation = "bound" | "main-command" | "unassigned";
-export type NativeTaskStatus = "pending" | "running" | "completed" | "failed" | "stopped";
-
-export interface NativeTaskDiagnosticItem {
-  code: string;
-  source: "reader" | "index" | "service";
-  [key: string]: unknown;
-}
-
-export interface NativeTaskDiagnostics {
-  items: NativeTaskDiagnosticItem[];
-  total: number;
-  truncated: boolean;
-}
-
-// One task out of the session's durable journal. taskRef is null until a
-// bound state row established ownership; status/statusSource are null until
-// a lifecycle row was observed. firstOffset/lastOffset are byte offsets into
-// the history file, useful only for diagnostics.
-export interface NativeTaskSummary {
-  sdkSessionId: string;
-  taskId: string;
-  taskKind: string | null;
-  taskType: string | null;
-  typeConflict: boolean;
-  status: NativeTaskStatus | null;
-  statusSource: string | null;
-  association: NativeTaskAssociation;
-  taskRef: NativeTaskRef | null;
-  ownerRunId: string | null;
-  owner: Record<string, unknown> | null;
-  mainToolUseId: string | null;
-  rowCount: number;
-  firstOffset: number;
-  lastOffset: number;
-}
-
-// Verbatim journal row: type plus whatever the collector stamped. Row bodies
-// are not normalized by the read path. Observed row types: claude/task-*,
-// claude/native-trace, claude/native-task-state and
-// claude/native-task-transcript (see NativeTaskTranscriptRow).
-export interface NativeTaskHistoryRow {
-  type: string;
-  sequence?: number;
-  at?: string;
-  [key: string]: unknown;
-}
-
-// One claude/native-task-transcript journal row: a snapshot of a bound
-// agent's transcript read through the SDK's public getSubagentMessages at a
-// real terminal signal (SubagentStop, an SDK terminal task event, or the
-// bounded turn-end sweep). entries/toolSteps/usage/diagnostics carry the
-// normalized, redacted content; read.status carries fixed codes
-// ('ok' | 'unavailable' | 'failed') with content-free reason codes instead
-// of SDK error text; chunk marks byte-bounded slicing and whether the
-// snapshot read completed. source is always 'sdk-public-read'. This is a
-// snapshot read, never a claim of per-token streaming, and the row attaches
-// to the bound agent task only - never to the main reply.
-export interface NativeTaskTranscriptRow {
-  type: "claude/native-task-transcript";
-  source: "sdk-public-read";
-  scope: TaskScope;
-  sdkSessionId: string;
-  taskId: string;
-  taskRef: NativeTaskRef | null;
-  ownerRunId: string | null;
-  capture: string;
-  read: { status: "ok" | "unavailable" | "failed"; reason?: string; at: string };
-  entries: unknown[];
-  toolSteps: unknown[];
-  usage: { records: unknown[]; summary: unknown | null };
-  diagnostics: unknown[];
-  stats: unknown | null;
-  chunk: { index: number; count: number; complete: boolean };
-  sequence?: number;
-  at?: string;
-  [key: string]: unknown;
-}
-
-export interface NativeTaskListPage {
-  fileId: string;
-  tasks: NativeTaskSummary[];
-  incomplete: string[];
-  diagnostics: NativeTaskDiagnostics;
-  scope: TaskScope;
-}
-
-export interface NativeTaskEventsPage {
-  events: NativeTaskHistoryRow[];
-  nextCursor: string | null;
-  hasMore: boolean;
-  fileId: string;
-  incomplete: string[];
-  diagnostics: NativeTaskDiagnostics;
-  taskRef: NativeTaskRef;
-  scope: TaskScope;
-}
-
-// Delegated sessions (POST/GET /sessions/:id/delegations). delegationId is a
-// Workbench server-command identity - it is NOT an SDK ownerRunId and implies
-// no SDK tool causality (sdkRunIdClaimed/inputCausalityClaimed stay false).
-// initiator states the honestly observed origin of the command; it is never
-// an authentication claim about a model or leader.
-export type DelegationPhase =
-  | "reserved"
-  | "child-created"
-  | "child-create-failed"
-  | "dispatching"
-  | "dispatched"
-  | "dispatch-unknown";
-
-export type DelegationOutcome =
-  | "not-started"
-  | "not-dispatched"
-  | "pending"
-  | "dispatched"
-  | "unknown";
-
-export interface DelegatedSessionRef {
-  kind: "delegated-session";
-  storeScope: string;
-  contextId: string;
-  parentSessionId: string;
-  delegationId: string;
-  childSessionId: string;
-  workspaceRef: string;
-}
-
-export interface DelegationCommandRecord extends DelegatedSessionRef {
-  requestId: string;
-  issuedAt: string;
-  source: "workbench-delegation-command";
-  basis: "server-command";
-  sdkRunIdClaimed: false;
-  inputCausalityClaimed: false;
-  initiator: {type: "external-api"; authenticatedAs: string | null};
-  selection: {profileId: string | null; model: string | null};
-}
-
-export interface DelegationDispatchState {
-  state: "not-dispatched" | "awaiting-dispatch" | "dispatching" | "dispatched" | "dispatch-unknown";
-  attemptId?: string;
-  at?: string;
-  reason?: string;
-  code?: string;
-  errorCode?: string;
-}
-
-export interface DelegationChildStatus {
-  sessionId: string;
-  present: boolean;
-  state: string;
-  agentId?: string;
-  model?: string | null;
-  active?: boolean;
-  turns?: number;
-  archived?: boolean;
-}
-
-export interface DelegationView {
-  delegation: DelegationCommandRecord;
-  phase: DelegationPhase;
-  outcome: DelegationOutcome;
-  dispatch: DelegationDispatchState;
-  child: DelegationChildStatus;
-}
-
-export interface DelegationAcceptResult extends DelegationView {
-  accepted: boolean;
-}
-
-export interface DelegationListPage {
-  scope: TaskScope;
-  delegations: DelegationView[];
-}
-
-// POST /sessions/:id/delegations request body. parentSessionId comes from the
-// route only; delegationId/childSessionId/workspaceRef are server-generated.
-export interface DelegationCommandInput {
-  scope: {storeScope: string; contextId: string};
-  requestId: string;
-  text: string;
-  agentId?: string;
-  aiProfileId?: string | null;
-  model?: string | null;
-  permissionMode?: PermissionMode;
-  effort?: EffortLevel;
-}
-
-export interface SessionChangeEvent {
-  type: 'workbench/session-changed' | 'workbench/sessions-snapshot' | 'workbench/resync';
-  revision: number;
-  contextId?: string;
-  session?: SessionSummary;
-  sessions?: SessionSummary[];
-  deleted?: boolean;
-}
-
-export interface WorkbenchResyncEvent {
-  type: "workbench/resync";
-  sessionId: string;
-  contextId: string;
-  at?: string;
-  reason: ResyncReason;
-  from: number;
-  highWater: number;
-  firstSequence: number;
-}
-
-export interface WorkbenchEvent {
-  type: string;
-  sessionId: string;
-  contextId: string;
-  sequence?: number;
-  at: string;
-  [key: string]: unknown;
-}
-
-export interface ImageAttachmentInput {
-  id?: string;
-  name: string;
-  mediaType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
-  data: string;
-  size?: number;
-  width?: number;
-  height?: number;
-}
-
-export interface ImageAttachment {
-  id: string;
-  name: string;
-  mediaType: ImageAttachmentInput["mediaType"];
-  size: number;
-  width?: number;
-  height?: number;
-  url: string;
-}
-
-export interface TextAttachmentInput {
-  id?: string;
-  name: string;
-  mediaType: "text/plain" | "text/markdown" | "application/json" | "text/csv";
-  data: string;
-  size?: number;
-}
-
-export type AttachmentInput = ImageAttachmentInput | TextAttachmentInput;
-export interface TextAttachment {
-  id: string;
-  name: string;
-  mediaType: TextAttachmentInput["mediaType"];
-  size: number;
-  url: string;
-}
-export type Attachment = ImageAttachment | TextAttachment;
-
-export interface SlashCommand {
-  name: string;
-  description: string;
-  argumentHint?: string;
-  aliases?: string[];
-  source?: string;
-}
-
-export interface SessionSnapshot {
-  session: SessionSummary;
-  events: WorkbenchEvent[];
-  permission: Record<string, unknown> | null;
-  permissionMode: PermissionMode;
-  tokenUsage: Record<string, unknown>;
-}
-
-export interface SessionHistoryPage {
-  events: WorkbenchEvent[];
-  nextCursor: string | null;
-  incomplete: boolean;
-  highWater: number;
-}
-
-export declare const API_VERSION: "v1";
-export declare const DEFAULT_API_PREFIX: "/api/claude-workbench/v1";
-export declare const RUNTIME: "claude-code";
-export declare const DEFAULT_AGENT: AgentId;
-export declare const AGENT_IDS: readonly AgentId[];
-export declare const EFFORT_LEVELS: readonly EffortLevel[];
-export declare const AGENTS: Record<AgentId, AgentDefinition>;
-export declare const PERMISSION_MODES: readonly PermissionMode[];
-export declare const IMAGE_MEDIA_TYPES: readonly ImageAttachmentInput["mediaType"][];
-export declare const TEXT_MEDIA_TYPES: readonly TextAttachmentInput["mediaType"][];
-export declare const TEXT_FILE_TYPES: Readonly<Record<string, TextAttachmentInput["mediaType"]>>;
-export declare const MAX_IMAGE_BYTES: number;
-export declare const MAX_IMAGES_PER_MESSAGE: number;
-export declare const MAX_IMAGE_MESSAGE_BYTES: number;
-export declare const MAX_TEXT_BYTES: number;
-export declare const MAX_ATTACHMENTS_PER_MESSAGE: number;
-export declare const MAX_ATTACHMENT_MESSAGE_BYTES: number;
-export declare const EVENT_TYPES: readonly string[];
-export declare function cleanId(value: unknown, field?: string): string;
-export declare function normalizeContext(input: unknown): WorkbenchContext;
-export declare function normalizeProfile(input: unknown, idOverride?: string): AiProfile;
-export declare function normalizeProject(input: unknown, idOverride?: string): Project;
-export declare function normalizeAgentId(value: unknown): AgentId;
-export declare function normalizeEffort(value: unknown): EffortLevel | undefined;
-export declare function normalizeModelEntries(input: unknown): ModelListEntry[];
-export declare function normalizeImageAttachments(input: unknown): Array<ImageAttachmentInput & { size: number }>;
-export declare function normalizeAttachments(input: unknown): Array<AttachmentInput & { size: number }>;
-export declare function appendTextAttachments(text: string, attachments?: AttachmentInput[]): string;
-export declare function resolveOpenAIBaseUrl(profile?: Partial<AiProfileInput>): string;
-export declare function resolveOpenAIModel(profile?: Partial<AiProfileInput> & { mainModel?: string }, model?: string): string;
-export declare function positiveInt(value: unknown, fallback: number): number;
+export type PermissionMode = "default" | "acceptEdits" | "plan" | "bypassPermissions";
+export type ProfileProtocol = "anthropic-compatible" | "openai-compatible" | string;
+export type AgentId = "claude-code" | "codex" | "opencode" | "zcode";
+export type EffortLevel = "low" | "medium" | "high" | "max";
+
+export interface AgentCapabilities {
+  backgroundTasks?: boolean;
+  thinking: boolean;
+  permissions: boolean;
+  toolStream: boolean;
+  images: boolean;
+  resume: true;
+  modelOverride: boolean;
+  generationParams: readonly string[];
+}
+
+export interface AgentDefinition {
+  id: AgentId;
+  label: string;
+  transport: string;
+  authModes: readonly string[];
+  capabilities: AgentCapabilities;
+}
+
+export interface AgentStatus extends AgentDefinition {
+  scanState?: 'unknown' | 'ready' | 'error';
+  checkedAt?: string;
+  errorCode?: string | null;
+  capabilities: { generationParams: string[] } & Omit<AgentCapabilities, "generationParams">;
+  available: boolean;
+  version: string | null;
+}
+
+export interface Project {
+  id: string;
+  name: string;
+  rootPath: string;
+  createdAt: string;
+  updatedAt: string;
+  defaultAiProfileId?: string | null;
+  defaultModel?: string | null;
+  defaultAgentId?: AgentId;
+}
+
+export interface ProjectInput {
+  name: string;
+  rootPath: string;
+  defaultAiProfileId?: string | null;
+  defaultModel?: string | null;
+  defaultAgentId?: AgentId;
+}
+
+export type ProjectPatch = Partial<Omit<ProjectInput, "rootPath">>;
+
+export interface ModelListEntry {
+  id: string;
+  openaiId?: string;
+  label: string;
+  tags: string[];
+}
+
+export interface WorkbenchContext {
+  contextId: string;
+  contextType?: string;
+  displayName?: string;
+  workspaceRef?: string;
+  aiProfileId?: string | null;
+  model?: string | null;
+  metadata?: Record<string, unknown>;
+}
+
+export interface AiProfileModels {
+  default: string;
+  fast?: string;
+  reasoning?: string;
+  coding?: string;
+  largeContext?: string;
+  list?: ModelListEntry[];
+  [role: string]: string | undefined | ModelListEntry[];
+}
+
+export interface AiProfileInput {
+  id: string;
+  name?: string;
+  provider: string;
+  protocol?: ProfileProtocol;
+  runtime?: "claude-code";
+  baseUrl: string;
+  openaiBaseUrl?: string;
+  credentialRef?: string;
+  models: AiProfileModels;
+  contextWindow?: number;
+  timeoutMs?: number;
+  permissionMode?: PermissionMode;
+  systemPrompt?: Record<string, unknown> | string;
+  enabled?: boolean;
+}
+
+export interface AiProfile extends AiProfileInput {
+  name: string;
+  protocol: ProfileProtocol;
+  runtime: "claude-code";
+  credentialRef: string;
+  contextWindow: number;
+  timeoutMs: number;
+  permissionMode: PermissionMode;
+  systemPrompt: Record<string, unknown>;
+  enabled: boolean;
+  credentialConfigured?: boolean;
+  credentialMasked?: string;
+}
+
+export interface CredentialInput { secret: string; }
+
+export interface ProfileTestResult {
+  ok: true;
+  runtime: "claude-code";
+  runtimeVerified: true;
+  profileId: string;
+  model: string;
+  firstEventMs: number;
+  durationMs: number;
+  resultPreview: string;
+}
+
+export interface HealthResult {
+  status: "ok";
+  version: string;
+  apiVersion: string;
+  activeProcesses: number;
+  sessions: number;
+  time: string;
+  /** Absent on servers built before task identity existed. */
+  taskIdentity?: TaskRuntimeIdentity;
+}
+
+// Task identity reported via /health. storeScope is the persistent store id
+// (null when the store file could not be established); runtimeEpoch is a
+// per-service-instance generation that is never persisted.
+export interface TaskRuntimeIdentity {
+  storeScope: string | null;
+  runtimeEpoch: string;
+  available: boolean;
+  errorCode: string | null;
+}
+
+export interface RuntimeInfo {
+  runtime: "claude-code";
+  available: boolean;
+  executable: string | null;
+  transport: string;
+}
+
+export interface SessionSummary {
+  tasks?: BackgroundTask[];
+  backgroundTaskCount?: number;
+  sessionId: string;
+  contextId: string;
+  projectId: string;
+  agentId: AgentId;
+  title: string;
+  active: boolean;
+  state: string;
+  model: string | null;
+  aiProfileId: string | null;
+  providerName?: string | null;
+  authSource?: "profile-injected" | "agent-owned";
+  selectedModel?: string | null;
+  permissionMode: PermissionMode;
+  archived: boolean;
+  turns: number;
+  startedAt: string;
+  updatedAt: string;
+  connectionState: string;
+}
+
+export type ResyncReason = "stale-cursor" | "history-gap";
+
+export interface BackgroundTask {
+  taskId: string;
+  parentSessionId: string;
+  toolUseId?: string;
+  status: 'pending' | 'running' | 'completed' | 'failed' | 'stopped';
+  description?: string;
+  summary?: string;
+  lastToolName?: string;
+  usage?: {total_tokens?: number; tool_uses?: number; duration_ms?: number};
+}
+
+// Task identity: opaque, already-resolved ids. storeScope is the stable storage
+// identity - never a port, PID or runtime epoch.
+export interface TaskScope {
+  storeScope: string;
+  contextId: string;
+  parentSessionId: string;
+}
+
+export interface NativeTaskRef extends TaskScope {
+  kind: "native-task";
+  ownerRunId: string;
+  taskId: string;
+}
+
+// Native task-history reads (GET /sessions/:id/native-tasks and POST
+// /sessions/:id/native-tasks/history). Every field mirrors what the reviewed
+// reader actually returns; null means "not observed in the journal", never a
+// fabricated placeholder.
+export type NativeTaskAssociation = "bound" | "main-command" | "unassigned";
+export type NativeTaskStatus = "pending" | "running" | "completed" | "failed" | "stopped";
+
+export interface NativeTaskDiagnosticItem {
+  code: string;
+  source: "reader" | "index" | "service";
+  [key: string]: unknown;
+}
+
+export interface NativeTaskDiagnostics {
+  items: NativeTaskDiagnosticItem[];
+  total: number;
+  truncated: boolean;
+}
+
+// One task out of the session's durable journal. taskRef is null until a
+// bound state row established ownership; status/statusSource are null until
+// a lifecycle row was observed. firstOffset/lastOffset are byte offsets into
+// the history file, useful only for diagnostics.
+export interface NativeTaskSummary {
+  sdkSessionId: string;
+  taskId: string;
+  taskKind: string | null;
+  taskType: string | null;
+  typeConflict: boolean;
+  status: NativeTaskStatus | null;
+  statusSource: string | null;
+  association: NativeTaskAssociation;
+  taskRef: NativeTaskRef | null;
+  ownerRunId: string | null;
+  owner: Record<string, unknown> | null;
+  mainToolUseId: string | null;
+  rowCount: number;
+  firstOffset: number;
+  lastOffset: number;
+}
+
+// Verbatim journal row: type plus whatever the collector stamped. Row bodies
+// are not normalized by the read path. Observed row types: claude/task-*,
+// claude/native-trace, claude/native-task-state and
+// claude/native-task-transcript (see NativeTaskTranscriptRow).
+export interface NativeTaskHistoryRow {
+  type: string;
+  sequence?: number;
+  at?: string;
+  [key: string]: unknown;
+}
+
+// One claude/native-task-transcript journal row: a snapshot of a bound
+// agent's transcript read through the SDK's public getSubagentMessages at a
+// real terminal signal (SubagentStop, an SDK terminal task event, or the
+// bounded turn-end sweep). entries/toolSteps/usage/diagnostics carry the
+// normalized, redacted content; read.status carries fixed codes
+// ('ok' | 'unavailable' | 'failed') with content-free reason codes instead
+// of SDK error text; chunk marks byte-bounded slicing and whether the
+// snapshot read completed. source is always 'sdk-public-read'. This is a
+// snapshot read, never a claim of per-token streaming, and the row attaches
+// to the bound agent task only - never to the main reply.
+export interface NativeTaskTranscriptRow {
+  type: "claude/native-task-transcript";
+  source: "sdk-public-read";
+  scope: TaskScope;
+  sdkSessionId: string;
+  taskId: string;
+  taskRef: NativeTaskRef | null;
+  ownerRunId: string | null;
+  capture: string;
+  read: { status: "ok" | "unavailable" | "failed"; reason?: string; at: string };
+  entries: unknown[];
+  toolSteps: unknown[];
+  usage: { records: unknown[]; summary: unknown | null };
+  diagnostics: unknown[];
+  stats: unknown | null;
+  chunk: { index: number; count: number; complete: boolean };
+  sequence?: number;
+  at?: string;
+  [key: string]: unknown;
+}
+
+export interface NativeTaskListPage {
+  fileId: string;
+  tasks: NativeTaskSummary[];
+  incomplete: string[];
+  diagnostics: NativeTaskDiagnostics;
+  scope: TaskScope;
+}
+
+export interface NativeTaskEventsPage {
+  events: NativeTaskHistoryRow[];
+  nextCursor: string | null;
+  hasMore: boolean;
+  fileId: string;
+  incomplete: string[];
+  diagnostics: NativeTaskDiagnostics;
+  taskRef: NativeTaskRef;
+  scope: TaskScope;
+}
+
+// Delegated sessions (POST/GET /sessions/:id/delegations). delegationId is a
+// Workbench server-command identity - it is NOT an SDK ownerRunId and implies
+// no SDK tool causality (sdkRunIdClaimed/inputCausalityClaimed stay false).
+// initiator states the honestly observed origin of the command; it is never
+// an authentication claim about a model or leader.
+export type DelegationPhase =
+  | "reserved"
+  | "child-created"
+  | "child-create-failed"
+  | "dispatching"
+  | "dispatched"
+  | "dispatch-unknown";
+
+export type DelegationOutcome =
+  | "not-started"
+  | "not-dispatched"
+  | "pending"
+  | "dispatched"
+  | "unknown";
+
+export interface DelegatedSessionRef {
+  kind: "delegated-session";
+  storeScope: string;
+  contextId: string;
+  parentSessionId: string;
+  delegationId: string;
+  childSessionId: string;
+  workspaceRef: string;
+}
+
+export interface DelegationCommandRecord extends DelegatedSessionRef {
+  requestId: string;
+  issuedAt: string;
+  source: "workbench-delegation-command";
+  basis: "server-command";
+  sdkRunIdClaimed: false;
+  inputCausalityClaimed: false;
+  initiator: {type: "external-api"; authenticatedAs: string | null};
+  selection: {profileId: string | null; model: string | null};
+}
+
+export interface DelegationDispatchState {
+  state: "not-dispatched" | "awaiting-dispatch" | "dispatching" | "dispatched" | "dispatch-unknown";
+  attemptId?: string;
+  at?: string;
+  reason?: string;
+  code?: string;
+  errorCode?: string;
+}
+
+export interface DelegationChildStatus {
+  sessionId: string;
+  present: boolean;
+  state: string;
+  agentId?: string;
+  model?: string | null;
+  active?: boolean;
+  turns?: number;
+  archived?: boolean;
+}
+
+export interface DelegationView {
+  context?: { mode: 'parent-snapshot'; truncated: boolean };
+  delegation: DelegationCommandRecord;
+  phase: DelegationPhase;
+  outcome: DelegationOutcome;
+  dispatch: DelegationDispatchState;
+  child: DelegationChildStatus;
+}
+
+export interface DelegationAcceptResult extends DelegationView {
+  accepted: boolean;
+}
+
+export interface DelegationListPage {
+  scope: TaskScope;
+  delegations: DelegationView[];
+}
+
+// POST /sessions/:id/delegations request body. parentSessionId comes from the
+// route only; delegationId/childSessionId/workspaceRef are server-generated.
+export interface DelegationCommandInput {
+  contextMode?: 'parent-snapshot';
+  scope: {storeScope: string; contextId: string};
+  requestId: string;
+  text: string;
+  agentId?: string;
+  aiProfileId?: string | null;
+  model?: string | null;
+  permissionMode?: PermissionMode;
+  effort?: EffortLevel;
+}
+
+export interface SessionChangeEvent {
+  type: 'workbench/session-changed' | 'workbench/sessions-snapshot' | 'workbench/resync';
+  revision: number;
+  contextId?: string;
+  session?: SessionSummary;
+  sessions?: SessionSummary[];
+  deleted?: boolean;
+}
+
+export interface WorkbenchResyncEvent {
+  type: "workbench/resync";
+  sessionId: string;
+  contextId: string;
+  at?: string;
+  reason: ResyncReason;
+  from: number;
+  highWater: number;
+  firstSequence: number;
+}
+
+export interface WorkbenchEvent {
+  type: string;
+  sessionId: string;
+  contextId: string;
+  sequence?: number;
+  at: string;
+  [key: string]: unknown;
+}
+
+export interface ImageAttachmentInput {
+  id?: string;
+  name: string;
+  mediaType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
+  data: string;
+  size?: number;
+  width?: number;
+  height?: number;
+}
+
+export interface ImageAttachment {
+  id: string;
+  name: string;
+  mediaType: ImageAttachmentInput["mediaType"];
+  size: number;
+  width?: number;
+  height?: number;
+  url: string;
+}
+
+export interface TextAttachmentInput {
+  id?: string;
+  name: string;
+  mediaType: "text/plain" | "text/markdown" | "application/json" | "text/csv";
+  data: string;
+  size?: number;
+}
+
+export type AttachmentInput = ImageAttachmentInput | TextAttachmentInput;
+export interface TextAttachment {
+  id: string;
+  name: string;
+  mediaType: TextAttachmentInput["mediaType"];
+  size: number;
+  url: string;
+}
+export type Attachment = ImageAttachment | TextAttachment;
+
+export interface SlashCommand {
+  name: string;
+  description: string;
+  argumentHint?: string;
+  aliases?: string[];
+  source?: string;
+}
+
+export interface SessionSnapshot {
+  session: SessionSummary;
+  events: WorkbenchEvent[];
+  permission: Record<string, unknown> | null;
+  permissionMode: PermissionMode;
+  tokenUsage: Record<string, unknown>;
+}
+
+export interface SessionHistoryPage {
+  events: WorkbenchEvent[];
+  nextCursor: string | null;
+  incomplete: boolean;
+  highWater: number;
+}
+
+export declare const API_VERSION: "v1";
+export declare const DEFAULT_API_PREFIX: "/api/claude-workbench/v1";
+export declare const RUNTIME: "claude-code";
+export declare const DEFAULT_AGENT: AgentId;
+export declare const AGENT_IDS: readonly AgentId[];
+export declare const EFFORT_LEVELS: readonly EffortLevel[];
+export declare const AGENTS: Record<AgentId, AgentDefinition>;
+export declare const PERMISSION_MODES: readonly PermissionMode[];
+export declare const IMAGE_MEDIA_TYPES: readonly ImageAttachmentInput["mediaType"][];
+export declare const TEXT_MEDIA_TYPES: readonly TextAttachmentInput["mediaType"][];
+export declare const TEXT_FILE_TYPES: Readonly<Record<string, TextAttachmentInput["mediaType"]>>;
+export declare const MAX_IMAGE_BYTES: number;
+export declare const MAX_IMAGES_PER_MESSAGE: number;
+export declare const MAX_IMAGE_MESSAGE_BYTES: number;
+export declare const MAX_TEXT_BYTES: number;
+export declare const MAX_ATTACHMENTS_PER_MESSAGE: number;
+export declare const MAX_ATTACHMENT_MESSAGE_BYTES: number;
+export declare const EVENT_TYPES: readonly string[];
+export declare function cleanId(value: unknown, field?: string): string;
+export declare function normalizeContext(input: unknown): WorkbenchContext;
+export declare function normalizeProfile(input: unknown, idOverride?: string): AiProfile;
+export declare function normalizeProject(input: unknown, idOverride?: string): Project;
+export declare function normalizeAgentId(value: unknown): AgentId;
+export declare function normalizeEffort(value: unknown): EffortLevel | undefined;
+export declare function normalizeModelEntries(input: unknown): ModelListEntry[];
+export declare function normalizeImageAttachments(input: unknown): Array<ImageAttachmentInput & { size: number }>;
+export declare function normalizeAttachments(input: unknown): Array<AttachmentInput & { size: number }>;
+export declare function appendTextAttachments(text: string, attachments?: AttachmentInput[]): string;
+export declare function resolveOpenAIBaseUrl(profile?: Partial<AiProfileInput>): string;
+export declare function resolveOpenAIModel(profile?: Partial<AiProfileInput> & { mainModel?: string }, model?: string): string;
+export declare function positiveInt(value: unknown, fallback: number): number;