// Agent message roles
export type AgentMessageRole = "user" | "assistant" | "system" | "tool";

// A single message in an agent conversation
export interface AgentMessage {
  id: string;
  sessionId: string;
  role: AgentMessageRole;
  content: string;
  timestamp: Date;
  metadata?: Record<string, unknown>;
}

// Session lifecycle status
export type AgentSessionStatus = "active" | "paused" | "completed" | "failed" | "idle";

// An agent session (conversation thread)
export interface AgentSession {
  id: string;
  providerId: string; // which provider owns this session
  providerType: string; // "internal" | "openclaw" | etc.
  label?: string;
  status: AgentSessionStatus;
  parentSessionId?: string; // for subagent trees
  createdAt: Date;
  updatedAt: Date;
  metadata?: Record<string, unknown>;
}

// Result of listing sessions
export interface AgentSessionList {
  sessions: AgentSession[];
  total: number;
  cursor?: string;
}

// Result of injecting a message
export interface InjectResult {
  accepted: boolean;
  messageId?: string;
}

// The IAgentProvider interface — every provider (internal, OpenClaw, future) implements this
export interface IAgentProvider {
  readonly providerId: string;
  readonly providerType: string;
  readonly displayName: string;

  // Session management
  listSessions(cursor?: string, limit?: number): Promise<AgentSessionList>;
  getSession(sessionId: string): Promise<AgentSession | null>;
  getMessages(sessionId: string, limit?: number, before?: string): Promise<AgentMessage[]>;

  // Control operations
  injectMessage(sessionId: string, content: string): Promise<InjectResult>;
  pauseSession(sessionId: string): Promise<void>;
  resumeSession(sessionId: string): Promise<void>;
  killSession(sessionId: string, force?: boolean): Promise<void>;

  // SSE streaming — returns an AsyncIterable of AgentMessage events
  streamMessages(sessionId: string): AsyncIterable<AgentMessage>;

  // Health
  isAvailable(): Promise<boolean>;
}

// Provider configuration stored in DB (AgentProviderConfig model from P0 schema)
export interface AgentProviderConfig {
  id: string;
  providerId: string;
  providerType: string;
  displayName: string;
  baseUrl?: string;
  apiToken?: string;
  enabled: boolean;
  createdAt: Date;
  updatedAt: Date;
}
