agl 1.0.17 → 21.0.2

package/ts_interfaces/interfaces.ts

@@ -0,0 +1,827 @@
+import * as plugins from './plugins.js';
+
+export const controllerProtocolVersion = 22 as const;
+export const controllerUpgradeManagementVersion = 2 as const;
+export const controllerPackageName = 'agl' as const;
+export const controllerMaxToolEventBytes = 48 * 1024;
+export const controllerMaxLiveMessageEventBytes = 128 * 1024;
+export const controllerInitialMessageBundleLimit = 20;
+export const controllerMaximumMessageBundles = 200;
+export const controllerMaximumTranscriptBytes = 512 * 1024;
+export const controllerLiveToolPayloadNotice =
+  '[elided: this tool payload exceeds the live transfer budget]' as const;
+export const controllerMaxDraftTextBytes = 64 * 1024;
+export const controllerMaxDraftAttachments = 8;
+export const controllerMaxDraftAttachmentBytes = 10 * 1024 * 1024;
+export const controllerMaxDraftAttachmentTotalBytes = 10 * 1024 * 1024;
+export const controllerMaxAttachmentPromptSuffixBytes = 16 * 1024;
+
+export const controllerHarnessIds = ['opencode', 'flex', 'controller'] as const;
+export const controllerSessionHarnessIds = ['opencode', 'flex'] as const;
+export type TControllerHarnessId = (typeof controllerHarnessIds)[number];
+export type TControllerSessionHarnessId = (typeof controllerSessionHarnessIds)[number];
+
+export interface IControllerRuntimeId {
+  harnessId: TControllerHarnessId;
+  nativeId: string;
+}
+
+export type TControllerSessionId = IControllerRuntimeId & {
+  harnessId: TControllerSessionHarnessId;
+};
+
+export type TControllerTerminalId = IControllerRuntimeId & {
+  harnessId: 'controller';
+};
+
+export type TControllerLayoutItemId = TControllerSessionId | TControllerTerminalId;
+
+/** Collision-free key for maps and sets containing qualified runtime IDs. */
+export const controllerRuntimeIdKey = (runtimeIdArg: IControllerRuntimeId): string =>
+  JSON.stringify([runtimeIdArg.harnessId, runtimeIdArg.nativeId]);
+
+export type TControllerLifecycleState = 'starting' | 'ready' | 'stopping' | 'stopped';
+export type TControllerProcessMode = 'detached' | 'foreground';
+export type TControllerHarnessLifecycleState = 'starting' | 'ready' | 'stopping' | 'stopped' | 'failed';
+export type TControllerAuthState = 'setupRequired' | 'ready';
+export type TControllerSessionStatus = 'idle' | 'busy' | 'retry' | 'error';
+export type TControllerMessageRole = 'user' | 'assistant' | 'system' | 'tool';
+export type TControllerToolStatus = 'pending' | 'running' | 'completed' | 'error';
+export type TControllerPermissionReply = 'once' | 'reject';
+/**
+ * Built-in OpenCode session operations exposed as slash commands, next to the
+ * per-project custom command catalog.
+ */
+export const controllerBuiltinCommands = ['compact', 'undo', 'redo', 'init'] as const;
+export type TControllerBuiltinCommand = (typeof controllerBuiltinCommands)[number];
+export type TControllerSlashCommandKind = 'builtin' | 'template' | 'handler';
+export type TControllerSlashWorkspaceReversion = 'supported' | 'unsupported' | 'not-applicable';
+
+export interface IControllerAffectedWorkspace {
+  id: string;
+  label: string;
+}
+
+export interface IControllerSessionReversionGroup {
+  runId: string;
+  kind: 'candidate' | 'barrier' | 'no-change';
+  visibility: 'visible' | 'hidden';
+  affectedWorkspaces: IControllerAffectedWorkspace[];
+  affectedWorkspacesTruncated: boolean;
+}
+
+export interface IControllerSessionReversionInfo {
+  undoAvailable: boolean;
+  redoAvailable: boolean;
+  groups: IControllerSessionReversionGroup[];
+}
+
+export interface IControllerSlashCommandDescriptor<
+  TMetadata extends Record<string, unknown> = Record<string, never>,
+> {
+  name: string;
+  description: string;
+  kind: TControllerSlashCommandKind;
+  hints: string[];
+  available: boolean;
+  unavailableReason?: string;
+  workspaceReversion: TControllerSlashWorkspaceReversion;
+  metadata: TMetadata;
+}
+
+export interface IControllerSlashListResult<
+  TDescriptor extends IControllerSlashCommandDescriptor = IControllerSlashCommandDescriptor,
+> {
+  commands: TDescriptor[];
+  reversion: IControllerSessionReversionInfo;
+}
+
+export type TControllerSlashExecuteResult<TResult = unknown> =
+  | { type: 'operation'; name: string }
+  | { type: 'handler-result'; name: string; result: TResult }
+  | { type: 'prompt-admission'; name: string; queueId?: string; runId?: string }
+  | { type: 'literal-prompt'; name: string };
+export type TControllerTodoStatus = 'pending' | 'in_progress' | 'completed' | 'cancelled';
+export type TControllerResourceKind = 'terminal' | 'browser';
+export type TControllerResourceLifecycle = 'active' | 'retiring' | 'retired';
+export type TControllerResourceAgentAvailability =
+  | 'detached'
+  | 'transitioning'
+  | 'available'
+  | 'dependencyUnavailable';
+export type TControllerTerminalProcessState = 'running' | 'stopped';
+export type TControllerBrowserRuntimeState = 'available' | 'unavailable';
+
+export type TControllerUpgradePhase =
+  | 'preparing'
+  | 'pausing'
+  | 'installing'
+  | 'restarting'
+  | 'continuing'
+  | 'completed'
+  | 'failed';
+
+export interface IControllerUpgradeStatus {
+  fromVersion: string;
+  toVersion: string;
+  phase: TControllerUpgradePhase;
+}
+
+export interface IControllerStatus {
+  packageName: string;
+  packageVersion: string;
+  protocolVersion: typeof controllerProtocolVersion;
+  upgradeManagementVersion: number;
+  controllerPid: number;
+  processGroupId: number;
+  processFingerprint: string;
+  processMode: TControllerProcessMode;
+  lifecycleState: TControllerLifecycleState;
+  startedAt: number;
+  setupRequired: boolean;
+  upgrade?: IControllerUpgradeStatus;
+  harnesses: Array<{
+    harnessId: TControllerSessionHarnessId;
+    pid?: number;
+    state: TControllerHarnessLifecycleState;
+    healthy: boolean;
+    version?: string;
+  }>;
+}
+
+export interface IControllerSystemMetrics {
+  sampledAt: number;
+  cpuUsagePercent: number | null;
+  /** Actively used memory, excluding reclaimable buffers and caches. */
+  memoryUsedBytes: number | null;
+  memoryTotalBytes: number | null;
+  networkReceiveBytesPerSecond: number | null;
+  networkTransmitBytesPerSecond: number | null;
+}
+
+export interface IControllerProject {
+  id: string;
+  /** Path relative to the configured projects root; doubles as display name. */
+  name: string;
+  /** Absolute resolved path of the project worktree. */
+  directory: string;
+  createdAt: number;
+}
+
+export interface IControllerResourceAttachment {
+  /** Stable authority owned by this resource for its complete lifetime. */
+  authorityId: string;
+  /** Monotonic fence advanced by every attach, detach, or reassignment. */
+  revision: number;
+  sessionId: TControllerSessionId | null;
+}
+
+export interface IControllerResourceBase {
+  id: string;
+  projectId: string;
+  kind: TControllerResourceKind;
+  title: string;
+  lifecycle: TControllerResourceLifecycle;
+  attachment: IControllerResourceAttachment;
+  agentAvailability: TControllerResourceAgentAvailability;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface IControllerTerminalResource extends IControllerResourceBase {
+  kind: 'terminal';
+  command: string;
+  cwd: string;
+  processState: TControllerTerminalProcessState;
+  stoppedAt?: number;
+  lastExitCode?: number;
+}
+
+export interface IControllerBrowserResource extends IControllerResourceBase {
+  kind: 'browser';
+  browserRuntimeState: TControllerBrowserRuntimeState;
+}
+
+export type TControllerResource = IControllerTerminalResource | IControllerBrowserResource;
+
+export interface IControllerBrowserViewport {
+  width: number;
+  height: number;
+  deviceScaleFactor: number;
+}
+
+export interface IControllerBrowserTabState {
+  id: string;
+  url: string;
+  title: string;
+  active: boolean;
+  status: 'open' | 'crashed';
+  generation: number;
+  appliedViewportRevision: number;
+  streaming: boolean;
+}
+
+export interface IControllerBrowserViewState {
+  status: 'stopped' | 'starting' | 'running' | 'stopping';
+  activeTabId: string | null;
+  viewportRevision: number;
+  viewport: IControllerBrowserViewport;
+  tabs: IControllerBrowserTabState[];
+  lastError?: { code: string; message: string; fatal: boolean; tabId?: string };
+}
+
+export interface IControllerBrowserFrame<
+  TDirection extends plugins.typedrequestInterfaces.TVirtualStreamDirection,
+> {
+  tabId: string;
+  sequence: number;
+  generation: number;
+  viewportRevision: number;
+  viewport: IControllerBrowserViewport;
+  format: 'jpeg' | 'png';
+  mimeType: 'image/jpeg' | 'image/png';
+  width: number;
+  height: number;
+  metadata: {
+    offsetTop: number;
+    pageScaleFactor: number;
+    deviceWidth: number;
+    deviceHeight: number;
+    scrollOffsetX: number;
+    scrollOffsetY: number;
+    timestamp?: number;
+  };
+  dataStream: plugins.typedrequestInterfaces.TVirtualStream<TDirection>;
+}
+
+export type TControllerBrowserViewEvent<
+  TDirection extends plugins.typedrequestInterfaces.TVirtualStreamDirection,
+> =
+  | { type: 'state'; state: IControllerBrowserViewState }
+  | { type: 'frame'; frame: IControllerBrowserFrame<TDirection> }
+  | { type: 'error'; error: { code: string; message: string; fatal: boolean; tabId?: string } };
+
+export interface IControllerBrowserFrameAcknowledgement {
+  tabId: string;
+  sequence: number;
+  generation: number;
+  viewportRevision: number;
+}
+
+export interface IControllerBrowserInputBase {
+  tabId: string;
+  generation: number;
+  viewportRevision: number;
+}
+
+export interface IControllerBrowserModifierState {
+  alt?: boolean;
+  control?: boolean;
+  meta?: boolean;
+  shift?: boolean;
+}
+
+export interface IControllerBrowserMouseInput extends IControllerBrowserInputBase {
+  type: 'move' | 'down' | 'up';
+  x: number;
+  y: number;
+  button?: 'none' | 'left' | 'middle' | 'right' | 'back' | 'forward';
+  buttons?: number;
+  clickCount?: number;
+  modifiers?: IControllerBrowserModifierState;
+}
+
+export interface IControllerBrowserWheelInput extends IControllerBrowserInputBase {
+  x: number;
+  y: number;
+  deltaX: number;
+  deltaY: number;
+  modifiers?: IControllerBrowserModifierState;
+}
+
+export interface IControllerBrowserKeyInput extends IControllerBrowserInputBase {
+  type: 'down' | 'up';
+  key: string;
+  code?: string;
+  text?: string;
+  unmodifiedText?: string;
+  windowsVirtualKeyCode?: number;
+  nativeVirtualKeyCode?: number;
+  autoRepeat?: boolean;
+  isKeypad?: boolean;
+  location?: number;
+  modifiers?: IControllerBrowserModifierState;
+}
+
+export type TControllerBrowserViewOperation =
+  | { type: 'acknowledgeFrame'; acknowledgement: IControllerBrowserFrameAcknowledgement }
+  | { type: 'setViewport'; viewport: IControllerBrowserViewport }
+  | { type: 'dispatchMouse'; input: IControllerBrowserMouseInput }
+  | { type: 'dispatchWheel'; input: IControllerBrowserWheelInput }
+  | { type: 'dispatchKey'; input: IControllerBrowserKeyInput }
+  | { type: 'insertText'; input: IControllerBrowserInputBase & { text: string } }
+  | { type: 'navigate'; url: string; tabId?: string; timeoutMs?: number }
+  | { type: 'createTab'; url?: string; activate?: boolean }
+  | { type: 'activateTab'; tabId: string }
+  | { type: 'closeTab'; tabId: string }
+  | { type: 'back' | 'forward' | 'reload'; tabId?: string };
+
+export interface IControllerPathSuggestion {
+  /**
+   * Path usable directly for project registration: relative to the projects
+   * root, or absolute when the query that produced it was absolute.
+   */
+  path: string;
+  /** Last path segment, for display. */
+  name: string;
+}
+
+export interface IControllerOpenCodeModelChoice {
+  harnessId: 'opencode';
+  providerID: string;
+  modelID: string;
+  /** Reasoning-effort variant name as advertised by the model (e.g. 'high'). */
+  variant?: string;
+}
+
+export interface IControllerFlexModelChoice {
+  harnessId: 'flex';
+  providerConnectionId: string;
+  providerID: string;
+  modelID: string;
+  /** Reasoning-effort variant name as advertised by the model (e.g. 'high'). */
+  variant?: string;
+}
+
+export type TControllerModelChoice =
+  | IControllerOpenCodeModelChoice
+  | IControllerFlexModelChoice;
+
+export interface IControllerOpenCodeModelOption extends IControllerOpenCodeModelChoice {
+  providerName: string;
+  modelName: string;
+  /** Available reasoning-effort variant names, in catalog order. Empty when the model has none. */
+  variants: string[];
+}
+
+export interface IControllerFlexModelOption extends IControllerFlexModelChoice {
+  providerName: string;
+  modelName: string;
+  /** Available reasoning-effort variant names, in catalog order. Empty when the model has none. */
+  variants: string[];
+  /** Provider-advertised default for this exact account catalog. */
+  isDefault: boolean;
+}
+
+export type TControllerModelOption =
+  | IControllerOpenCodeModelOption
+  | IControllerFlexModelOption;
+
+export interface IControllerSettings {
+  /** At most one default per session harness. */
+  defaultModels: TControllerModelChoice[];
+  /** When true, the controller replies 'once' to every pending permission request automatically. */
+  autoAcceptPermissions?: boolean;
+}
+
+export interface IControllerSession {
+  id: IControllerRuntimeId;
+  title: string;
+  parentId?: IControllerRuntimeId;
+  createdAt: number;
+  updatedAt: number;
+  /** Unix milliseconds when the session was archived in OpenCode; absent for active sessions. */
+  archivedAt?: number;
+  status: TControllerSessionStatus;
+  /** True while OpenCode has a pending permission or question for this session. */
+  attention?: boolean;
+}
+
+export interface IControllerReasoningPart {
+  id: IControllerRuntimeId;
+  text: string;
+  startedAt?: number;
+  endedAt?: number;
+}
+
+export interface IControllerToolCall {
+  id: IControllerRuntimeId;
+  name: string;
+  status: TControllerToolStatus;
+  input?: unknown;
+  output?: unknown;
+  /** Process exit code when output is one combined stream. */
+  exitCode?: number;
+  errorText?: string;
+  /** Session spawned by this call (subagent/task tools). */
+  childSessionId?: IControllerRuntimeId;
+  /** "providerID/modelID" the spawned session runs on (subagent/task tools). */
+  model?: string;
+  startedAt?: number;
+  finishedAt?: number;
+}
+
+/** Replace-only live snapshot for one harness tool execution. */
+export interface IControllerToolExecution {
+  sessionId: IControllerRuntimeId;
+  messageId: IControllerRuntimeId;
+  partId: IControllerRuntimeId;
+  callId: IControllerRuntimeId;
+  toolName: string;
+  status: TControllerToolStatus;
+  input?: unknown;
+  output?: unknown;
+  exitCode?: number;
+  errorText?: string;
+  childSessionId?: IControllerRuntimeId;
+  model?: string;
+  startedAt?: number;
+  finishedAt?: number;
+  /** Authoritative source coordinates; required for Flex and absent for OpenCode. */
+  order?: IControllerTranscriptOrder;
+  /** Harness tool-state timestamp used to reject delayed state regressions. */
+  sourceUpdatedAt: number;
+  /** Controller-process monotonic ordering for delivered snapshots. */
+  revision: number;
+  /** Changes whenever the controller observes a new event stream for this harness. */
+  streamEpoch: number;
+}
+
+/** Replace-only live Assistant reasoning snapshot from either session harness. */
+export interface IControllerReasoningUpdate {
+  sessionId: IControllerRuntimeId;
+  messageId: IControllerRuntimeId;
+  partId: IControllerRuntimeId;
+  text: string;
+  status: 'running' | 'completed' | 'cancelled';
+  /** Authoritative source coordinates; required for Flex and absent for OpenCode. */
+  order?: IControllerTranscriptOrder;
+  sourceUpdatedAt: number;
+  revision: number;
+  streamEpoch: number;
+}
+
+/** Replace-only live Assistant text snapshot from either session harness. */
+export interface IControllerTextUpdate {
+  sessionId: IControllerRuntimeId;
+  messageId: IControllerRuntimeId;
+  partId: IControllerRuntimeId;
+  text: string;
+  status: 'running' | 'completed';
+  /** Authoritative source coordinates; required for Flex and absent for OpenCode. */
+  order?: IControllerTranscriptOrder;
+  sourceUpdatedAt: number;
+  revision: number;
+  streamEpoch: number;
+}
+
+export interface IControllerToolStreamCursor {
+  streamEpoch: number;
+  revision: number;
+}
+
+export interface IControllerMessageStreamCursor {
+  streamEpoch: number;
+  revision: number;
+}
+
+export interface IControllerUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+  totalTokens?: number;
+  cacheReadTokens?: number;
+  cacheWriteTokens?: number;
+}
+
+export interface IControllerTranscriptOrder {
+  messageIndex: number;
+  partIndex: number;
+}
+
+export interface IControllerDraftAttachment {
+  id: string;
+  name: string;
+  mediaType: string;
+  size: number;
+  kind: 'image' | 'text' | 'binary';
+  dataBase64: string;
+}
+
+/** Controller-memory-only composer state for one exact session. */
+export interface IControllerSessionDraft {
+  text: string;
+  attachments: IControllerDraftAttachment[];
+  revision: number;
+}
+
+/** Authoritative replacement fields changed by one draft mutation. */
+export interface IControllerSessionDraftUpdate {
+  revision: number;
+  text?: string;
+  attachments?: IControllerDraftAttachment[];
+}
+
+/** Controller-memory projection of a harness-accepted prompt not yet present in transcript hydration. */
+export interface IControllerPendingPrompt {
+  id: IControllerRuntimeId;
+  text: string;
+  attachments: Array<Omit<IControllerDraftAttachment, 'dataBase64'>>;
+  createdAt: number;
+}
+
+/** Session-level token facts. Metrics that cannot be proven stay absent. */
+export interface IControllerSessionMetrics {
+  lifetimeUsedTokens?: number;
+  compactionCount?: number;
+  tokensBeforeLatestCompaction?: number;
+  maxContextTokens?: number;
+  currentContextTokens?: number;
+}
+
+export type TControllerScratchpadUpdater = 'user' | 'intelligence' | 'agent' | 'application';
+
+export interface IControllerSessionScratchpad {
+  /** Stable controller/project/qualified-session identity. */
+  id: string;
+  text: string;
+  revision: number;
+  updatedAt?: number;
+  updatedBy?: TControllerScratchpadUpdater;
+}
+
+export type TControllerIntelligenceStatus = 'running' | 'completed' | 'error';
+
+export interface IControllerIntelligenceExchange {
+  id: string;
+  question: string;
+  status: TControllerIntelligenceStatus;
+  answer?: string;
+  error?: string;
+  model?: string;
+  /** Luna answered, but a newer user scratchpad revision won the write race. */
+  scratchpadConflict?: true;
+  createdAt: number;
+  completedAt?: number;
+}
+
+export interface IControllerMessage {
+  id: IControllerRuntimeId;
+  role: TControllerMessageRole;
+  text: string;
+  createdAt: number;
+  /** Authoritative source chronology when the harness exposes ordered messages and parts. */
+  order?: IControllerTranscriptOrder;
+  updatedAt?: number;
+  streaming?: boolean;
+  reasoning?: IControllerReasoningPart[];
+  toolCall?: IControllerToolCall;
+  usage?: IControllerUsage;
+  error?: string;
+  /** "providerID/modelID" that produced this assistant message. */
+  model?: string;
+  /** Model variant (reasoning effort) this message ran with. */
+  effort?: string;
+}
+
+export interface IControllerPermission {
+  id: IControllerRuntimeId;
+  sessionId: IControllerRuntimeId;
+  title: string;
+  type: string;
+  patterns: string[];
+  metadata: Record<string, unknown>;
+  createdAt?: number;
+}
+
+export interface IControllerTodo {
+  id?: IControllerRuntimeId;
+  content: string;
+  status: TControllerTodoStatus;
+}
+
+export interface IControllerQuestionOption {
+  /** Short display text. */
+  label: string;
+  /** Explanation of the choice. */
+  description: string;
+}
+
+export interface IControllerQuestionItem {
+  /** Complete question text. */
+  question: string;
+  /** Very short label for the question, as advertised by OpenCode. */
+  header: string;
+  options: IControllerQuestionOption[];
+  /** Multiple answers may be selected. */
+  multiple?: boolean;
+  /** A free-text answer is accepted besides the listed options. */
+  custom?: boolean;
+}
+
+export interface IControllerQuestion {
+  id: IControllerRuntimeId;
+  sessionId: IControllerRuntimeId;
+  questions: IControllerQuestionItem[];
+  /** Tool call that raised the ask; links the request to its transcript entry. */
+  toolCallId?: IControllerRuntimeId;
+}
+
+export interface IControllerTerminal {
+  /** Controller-generated opaque PTY identifier. */
+  id: TControllerTerminalId;
+  title: string;
+  command: string;
+  cwd: string;
+}
+
+export interface IControllerSessionGroup {
+  /** Client-generated stable identifier. */
+  id: string;
+  name: string;
+  /** Historical field name: conversation and live-terminal IDs in display order. */
+  sessionIds: TControllerSessionId[];
+}
+
+export interface IControllerSessionLayout {
+  groups: IControllerSessionGroup[];
+  /** Historical field name: explicit display order for ungrouped layout items. */
+  ungroupedSessionIds: TControllerSessionId[];
+  /** Monotonic persistence revision used to reject stale browser updates. */
+  revision: number;
+}
+
+export interface IControllerSessionDetail {
+  session: IControllerSession;
+  messagePage: IControllerMessagePage;
+  pendingPrompts: IControllerPendingPrompt[];
+  permissions: IControllerPermission[];
+  questions: IControllerQuestion[];
+  todos: IControllerTodo[];
+  scratchpad: IControllerSessionScratchpad;
+  intelligenceExchanges: IControllerIntelligenceExchange[];
+  /** Effective auto-accept state for this chat: its own yolo switch or the global setting. */
+  autoAcceptPermissions?: boolean;
+  /** Durable per-session choice; the harness default applies when absent. */
+  modelChoice?: TControllerModelChoice;
+  /** "providerID/modelID" that answered most recently in this chat. */
+  model?: string;
+  /** Model variant (reasoning effort) of the most recent answer. */
+  effort?: string;
+  /** Latest live-tool cursor covered by this authoritative harness snapshot. */
+  toolStreamCursor: IControllerToolStreamCursor;
+  /** Latest live Assistant text/reasoning cursor covered by this snapshot. */
+  messageStreamCursor: IControllerMessageStreamCursor;
+}
+
+/** One source message and all normalized transcript entries derived from it. */
+export interface IControllerMessageBundle {
+  sourceMessageId: IControllerRuntimeId;
+  structuralDigest: string;
+  messages: IControllerMessage[];
+}
+
+export interface IControllerMessagePage {
+  bundles: IControllerMessageBundle[];
+  /** Opaque harness cursor for the next older page. */
+  nextCursor?: string;
+  /** The harness retained only a bounded subset of the source transcript. */
+  truncated?: boolean;
+  /** The controller omitted source bundles or payloads to enforce its transfer budget. */
+  historyLimited?: boolean;
+}
+
+export interface IControllerSessionAuxiliary {
+  sessionMetrics: IControllerSessionMetrics;
+  sessionIntelligenceEnabled: boolean;
+}
+
+export type TControllerProviderLoginFlow = 'device';
+export type TControllerProviderLoginStatus = 'pending' | 'succeeded' | 'cancelled' | 'failed';
+export type TControllerProviderConnectionStatus = 'active' | 'reauthRequired';
+export type TControllerModelRefreshJobStatus =
+  | 'pending'
+  | 'running'
+  | 'completed'
+  | 'failed'
+  | 'cancelled';
+
+export interface IControllerProvider {
+  id: string;
+  name: string;
+  loginFlows: TControllerProviderLoginFlow[];
+}
+
+export interface IControllerProviderAccountSummary {
+  accountId?: string;
+  email?: string;
+  plan?: string;
+}
+
+export interface IControllerProviderConnection {
+  /** Controller-owned opaque stable identifier. */
+  id: string;
+  providerID: string;
+  status: TControllerProviderConnectionStatus;
+  account: IControllerProviderAccountSummary;
+  /** True when this account currently authenticates the controller-owned OpenCode runtime. */
+  selectedForOpenCode?: true;
+}
+
+export interface IControllerProviderRateLimitWindow {
+  usedPercent: number;
+  limitWindowSeconds: number;
+  resetAfterSeconds: number;
+  /** Unix timestamp in seconds. */
+  resetsAt: number;
+}
+
+export interface IControllerProviderRateLimitDetails {
+  allowed: boolean;
+  limitReached: boolean;
+  primaryWindow?: IControllerProviderRateLimitWindow;
+  secondaryWindow?: IControllerProviderRateLimitWindow;
+}
+
+export interface IControllerProviderAdditionalRateLimit {
+  limitName: string;
+  meteredFeature: string;
+  rateLimit?: IControllerProviderRateLimitDetails;
+}
+
+/** Public metadata-only account quota snapshot. Credentials and raw provider responses stay private. */
+export interface IControllerProviderAccountRateLimits {
+  providerConnectionId: string;
+  providerID: 'openai';
+  plan: string;
+  observedAt: string;
+  rateLimit?: IControllerProviderRateLimitDetails;
+  additionalRateLimits: IControllerProviderAdditionalRateLimit[];
+  rateLimitReachedType?: string;
+  rateLimitResetCreditsAvailableCount?: number;
+}
+
+/** Public device-login state. Provider credentials and provider responses never cross this boundary. */
+export interface IControllerProviderLogin {
+  id: IControllerRuntimeId;
+  verificationUrl: string;
+  userCode: string;
+  status: TControllerProviderLoginStatus;
+  account?: IControllerProviderAccountSummary;
+}
+
+export interface IControllerModelRefreshJob {
+  id: IControllerRuntimeId;
+  providerConnectionId: string;
+  status: TControllerModelRefreshJobStatus;
+  modelCount?: number;
+}
+
+/**
+ * Single source of the controller event vocabulary: the browser socket
+ * client validates incoming events against this list at runtime, so a type
+ * added here is automatically deliverable — the two cannot drift apart.
+ */
+export const controllerEventTypes = [
+  'sessions.changed',
+  'session.changed',
+  'session.draft.changed',
+  'session.history.changed',
+  'session.tool.updated',
+  'session.reasoning.updated',
+  'session.text.updated',
+  'permissions.changed',
+  'harness.changed',
+  'projects.changed',
+  'settings.changed',
+  'sessiongroups.changed',
+  'resources.changed',
+  'terminals.changed',
+  'upgrade.changed',
+] as const;
+export type TControllerEventType = (typeof controllerEventTypes)[number];
+
+export interface IControllerEvent {
+  type: TControllerEventType;
+  harnessId?: TControllerSessionHarnessId;
+  projectId?: string;
+  sessionId?: IControllerRuntimeId;
+  /** Authoritative status carried by harness session status/idle events. */
+  sessionStatus?: TControllerSessionStatus;
+  /** Literal marker carried only by a session.changed event from session.error. */
+  sessionError?: true;
+  /** Present only on live OpenCode or Flex tool snapshots. */
+  toolExecution?: IControllerToolExecution;
+  /** Present only on a live OpenCode or Flex reasoning snapshot. */
+  reasoningUpdate?: IControllerReasoningUpdate;
+  /** Present only on a live OpenCode or Flex text snapshot. */
+  textUpdate?: IControllerTextUpdate;
+  /** Present only on a session.draft.changed event. */
+  sessionDraftUpdate?: IControllerSessionDraftUpdate;
+  /** Ordered harness stream barrier carried by harness.changed. */
+  toolStreamEpoch?: number;
+  /** Ordered Assistant message stream barrier carried by harness.changed. */
+  messageStreamEpoch?: number;
+  /** Sanitized upgrade metadata; present only on upgrade.changed. */
+  upgrade?: IControllerUpgradeStatus;
+  timestamp: number;
+}