import type { TerminalAttachment } from './substrate/tmux-stream.js';
import type { NativeSessionIdleProof } from './substrate/native-host.js';
import type { TerminalInputDelivery, TmuxCommand, TmuxWindowSize } from './substrate/tmux.js';
import type { SessionDescriptor } from '@volter-ai-dev/supercode-harness-sdk';

export type TerminalAttachmentGrant = Readonly<{
  expiresAt: number;
  id: string;
  mode: 'observe' | 'control';
}>;

export type EmbeddedTerminalAttachmentGrant = TerminalAttachmentGrant & Readonly<{
  baseUrl: string;
}>;

export type TerminalSession = Readonly<{
  activeCommand: string | null;
  /** Opaque application context association; never a native harness or tmux handle. */
  contextKey: string | null;
  cwd: string | null;
  id: string;
  label: string;
  owned: boolean;
  /** The pane's root process (its shell), for finding what runs beneath it. */
  rootPid: number | null;
  size: Readonly<{ columns: number; rows: number }> | null;
}>;

export type StructuredLaunch = Readonly<{
  arguments: string[];
  env: Readonly<Record<string, string>>;
  program: string;
}>;

export type TmuxTerminalHostOptions = {
  allowUnownedControl?: boolean;
  attachmentTtlMs?: number;
  contextOption?: string;
  ownerId?: string;
  ownerOption?: string;
  openLocalTerminal?: (launch: StructuredLaunch) => Promise<void>;
  socket?: string;
};

export class TmuxTerminalHost {
  constructor(options?: TmuxTerminalHostOptions);
  listSessions(): Promise<TerminalSession[]>;
  createSession(input: {
    command: TmuxCommand;
    contextKey?: string;
    cwd?: string;
    env?: Record<string, string>;
    name?: string;
  }): Promise<TerminalSession>;
  capture(sessionId: string, options?: { lines?: number; preserveEscapes?: boolean }): string;
  sendInput(
    sessionId: string,
    data: string,
    options?: { deadlineMs?: number; submitMode?: 'retry' | 'single' },
  ): Promise<TerminalInputDelivery>;
  /** Persist an opaque application context association on a session owned by this host. */
  bindContext(sessionId: string, contextKey: string): Promise<TerminalSession>;
  issueAttachment(sessionId: string, options?: { mode?: 'observe' | 'control' }): TerminalAttachmentGrant;
  attachSocket(
    attachmentId: string,
    socket: unknown,
    size?: { cols?: number; rows?: number },
  ): Promise<TerminalAttachment>;
  localAttachLaunch(sessionId: string): StructuredLaunch;
  openLocalTerminal(sessionId: string): Promise<void>;
  closeSession(sessionId: string): void;
  dispose(): void;
}

export class TerminalWebSocketBridge {
  constructor(options: {
    host: Pick<TmuxTerminalHost, 'issueAttachment' | 'attachSocket'>;
    allowedOrigins: string | readonly string[];
  });
  readonly baseUrl: string;
  start(): Promise<string>;
  issueAttachment(sessionId: string, options?: { mode?: 'observe' | 'control' }): EmbeddedTerminalAttachmentGrant;
  stop(): Promise<void>;
}

export type SupercodeTerminalHarness = 'claude-code' | 'codex' | 'gemini' | 'grok';

export type SupercodeTerminalLaunch = Readonly<{
  arguments?: readonly string[];
  cwd: string;
  env?: Readonly<Record<string, string>>;
  program: string;
}>;

export type SupercodeTerminalAttachment = EmbeddedTerminalAttachmentGrant & Readonly<{
  conversationKey: string | null;
  sessionId: string;
}>;

export type SupercodeTerminalSnapshot = Readonly<{
  attachment: SupercodeTerminalAttachment | null;
  available: boolean;
  bindings: readonly Readonly<{ conversationKey: string; sessionId: string }>[];
  canOpenLocal: boolean;
  error: string | null;
  sessions: readonly TerminalSession[];
}>;

export type SupercodeTerminalControllerOptions = Readonly<{
  allowedOrigins: string | readonly string[];
  formatCwd?: (cwd: string) => string | null | undefined;
  host?: TmuxTerminalHostOptions;
  nativeHost?: { socket?: string; home?: string; claudeConfigDir?: string };
  sessionNamePrefix?: string;
}>;

export class SupercodeTerminalController {
  constructor(options: SupercodeTerminalControllerOptions);
  start(): Promise<void>;
  snapshot(): Promise<SupercodeTerminalSnapshot>;
  create(harness: SupercodeTerminalHarness, cwd: string): Promise<SupercodeTerminalSnapshot>;
  launchSession(
    harness: string,
    launch: SupercodeTerminalLaunch,
    conversationKey?: string | null,
    initialInput?: string,
    options?: Readonly<{
      conversationDiscovery?: Readonly<{
        knownConversationKeys: readonly string[];
        prompt: string;
        startedAtMs?: number;
      }>;
    }>,
  ): Promise<SupercodeTerminalSnapshot>;
  attach(sessionId: string, mode: 'observe' | 'control'): Promise<SupercodeTerminalSnapshot>;
  bindContext(sessionId: string, conversationKey: string): Promise<SupercodeTerminalSnapshot>;
  reconcileConversationBindings(
    descriptors: readonly SessionDescriptor[],
    keyForDescriptor: (descriptor: SessionDescriptor) => string,
    options?: Readonly<{ now?: number }>,
  ): Promise<Readonly<{
    bindings: readonly Readonly<{ conversationKey: string; sessionId: string }>[];
    snapshot: SupercodeTerminalSnapshot;
  }>>;
  close(sessionId: string): Promise<SupercodeTerminalSnapshot>;
  openLocal(sessionId: string): Promise<SupercodeTerminalSnapshot>;
  dismiss(): Promise<SupercodeTerminalSnapshot>;
  refreshNativeSessions(): Promise<void>;
  canMoveSession(harness: string, sessionId: string, cwd: string): boolean;
  prepareMoveSession(
    harness: string,
    sessionId: string,
    cwd: string,
    proof: NativeSessionIdleProof | null,
  ): Promise<NativeSessionIdleProof | null>;
  moveSession(
    harness: string,
    sessionId: string,
    launch: SupercodeTerminalLaunch,
    conversationKey: string,
    proof: NativeSessionIdleProof,
  ): Promise<SupercodeTerminalSnapshot>;
  stop(): Promise<void>;
}

export class TerminalHostError extends Error {
  readonly code: string;
  constructor(code: string, message: string);
}

/**
 * Is the program of this kind showing its idle composer on this captured screen?
 * `null` means this package has no composer pattern for that kind — never read
 * it as "not ready yet".
 */
export function composerReadyForInput(kind: string, screen: string | undefined): boolean | null;
/** Does the composer hold a typed draft? `screen` is a capture with escapes; null when no composer is on screen. */
export function composerHoldsDraft(kind: string, screen: string | undefined): boolean | null;

export { classifyAttentionSignal, observeLifecycle, gatherLifecycleObservation, createLifecycleStore, snapshotProcessTree, snapshotProcessTreeAsync } from './substrate/session-lifecycle.js';
export type {
  LifecycleSnapshot,
  LifecycleStore,
  PaneLifecycle,
  PaneProcessLifecycle,
  PaneProcessObservation,
  SessionAttentionSignal,
  SessionDerivation,
  DerivationConfidence,
  DerivationSource,
  SessionLifecycle,
  SessionLifecycleState,
} from './substrate/session-lifecycle.js';

export type { TerminalInputDelivery, TmuxCommand, TmuxWindowSize };