export type RuntimeCapability =
  | 'session.list'
  | 'session.tree'
  | 'session.stream'
  | 'session.send'
  | 'session.attach'
  | 'session.terminate';
export type RuntimeSessionState = 'starting' | 'active' | 'idle' | 'stopped' | 'failed';

/** Transitional capability inventory is normalized; provider legacy vocabularies never enter core. */
export type TransitionalRuntimeCapability = 'kanban' | 'skills' | 'memory' | 'tools' | 'cron';
export type TransitionalCapabilityStatus = 'supported' | 'unsupported';
export interface TransitionalCapabilityInventoryEntry {
  capability: TransitionalRuntimeCapability;
  status: TransitionalCapabilityStatus;
}
/** Optional extension for transitional adapters; not every runtime has Hermes inventory. */
export interface TransitionalCapabilityInventoryProvider {
  transitionalCapabilityMatrix(
    scope: RuntimeScope,
  ): Promise<TransitionalCapabilityInventoryEntry[]>;
  assertTransitionalCapability(
    capability: TransitionalRuntimeCapability,
    scope: RuntimeScope,
  ): Promise<void>;
}
export type RuntimeAttachMode = 'read' | 'control';

/** Server-derived immutable authority context. Client identity fields are intentionally absent. */
export interface RuntimeScope {
  readonly actorId: string;
  readonly tenantId: string;
  readonly channelId: string;
  readonly correlationId: string;
}
export interface RuntimeSession {
  id: string;
  providerId: string;
  runtimeId: string;
  parentSessionId?: string;
  state: RuntimeSessionState;
  createdAt: string;
  updatedAt: string;
}
export interface RuntimeSessionTree {
  session: RuntimeSession;
  children: RuntimeSessionTree[];
}
export interface RuntimeCapabilitySet {
  supported: RuntimeCapability[];
}
export interface RuntimeHealth {
  status: 'healthy' | 'degraded' | 'down';
  checkedAt: string;
  detail?: string;
}
export interface RuntimeMessage {
  content: string;
  idempotencyKey: string;
}
export interface RuntimeAttachHandle {
  attachmentId: string;
  sessionId: string;
  mode: RuntimeAttachMode;
  expiresAt: string;
}
export interface RuntimeError {
  code:
    | 'capability_unsupported'
    | 'not_found'
    | 'forbidden'
    | 'conflict'
    | 'unavailable'
    | 'invalid_request';
  message: string;
  retryable: boolean;
}
export type RuntimeStreamEvent =
  | {
      type: 'session.state';
      sessionId: string;
      cursor: string;
      occurredAt: string;
      state: RuntimeSessionState;
    }
  | {
      type: 'message.delta';
      sessionId: string;
      cursor: string;
      occurredAt: string;
      content: string;
    }
  | {
      type: 'message.complete';
      sessionId: string;
      cursor: string;
      occurredAt: string;
      messageId: string;
    }
  | {
      type: 'runtime.error';
      sessionId: string;
      cursor: string;
      occurredAt: string;
      error: RuntimeError;
    };

/** Runtime-neutral boundary; implementations fail closed for unsupported operations. */
export interface AgentRuntimeProvider {
  readonly id: string;
  capabilities(scope: RuntimeScope): Promise<RuntimeCapabilitySet>;
  health(scope: RuntimeScope): Promise<RuntimeHealth>;
  listSessions(scope: RuntimeScope): Promise<RuntimeSession[]>;
  getSessionTree(scope: RuntimeScope): Promise<RuntimeSessionTree[]>;
  streamSession(
    sessionId: string,
    cursor: string | undefined,
    scope: RuntimeScope,
  ): AsyncIterable<RuntimeStreamEvent>;
  sendMessage(sessionId: string, message: RuntimeMessage, scope: RuntimeScope): Promise<void>;
  attach(
    sessionId: string,
    mode: RuntimeAttachMode,
    scope: RuntimeScope,
  ): Promise<RuntimeAttachHandle>;
  detach(attachmentId: string, scope: RuntimeScope): Promise<void>;
  terminate(sessionId: string, approvalRef: string, scope: RuntimeScope): Promise<void>;
}
