/**
 * Platform-agnostic host adapter contract (WP-01).
 * Implementations live under hosts/* in later WPs — this file is types only.
 */

import type { HostDescriptor } from "./HostDescriptor.ts";
import type { HostEventEnvelope } from "./HostEvent.ts";
import type { HostFailure } from "./HostFailure.ts";
import type {
  HostRunInspectionState,
  HostRunRef,
  StartRunInput,
} from "./HostRun.ts";
import type {
  HostSessionRef,
  HostSessionState,
  PrepareSessionInput,
  PreparedHostSession,
} from "./HostSession.ts";
import type { HostCapabilityLevel } from "./HostCapabilities.ts";

export interface AgentHostAdapter {
  readonly hostId: string;

  describe(): Promise<HostDescriptor>;

  prepareSession(input: PrepareSessionInput): Promise<PreparedHostSession>;

  inspectSession(reference: HostSessionRef): Promise<HostSessionState>;

  startRun(session: HostSessionRef, input: StartRunInput): Promise<HostRunRef>;

  streamEvents(run: HostRunRef): AsyncIterable<HostEventEnvelope>;

  cancelRun(run: HostRunRef, reason: string): Promise<void>;

  closeSession?(reference: HostSessionRef): Promise<void>;

  classifyError(error: unknown): HostFailure;
}

export interface QueueCapableHost {
  enqueueRun(session: HostSessionRef, input: StartRunInput): Promise<void>;
}

export interface SteerCapableHost {
  steerRun(run: HostRunRef, instruction: string): Promise<void>;
}

export interface InterruptCapableHost {
  interruptRun(run: HostRunRef, reason: string): Promise<void>;
}

export interface ForkCapableHost {
  forkSession(reference: HostSessionRef): Promise<HostSessionRef>;
}

export interface RunInspectionCapableHost {
  inspectRun(run: HostRunRef): Promise<HostRunInspectionState>;
}

export interface AgentHostRegistryContract {
  register(adapter: AgentHostAdapter): void;
  unregister(hostId: string): void;
  get(hostId: string): AgentHostAdapter;
  has(hostId: string): boolean;
  list(): AgentHostAdapter[];
  describeAll(): Promise<HostDescriptor[]>;
  assertConformance(
    hostId: string,
    minimumLevel: HostCapabilityLevel,
  ): Promise<HostDescriptor>;
}
