// ============================================================================
// H33 Agent SDK — TypeScript types matching the Rust API surface
// ============================================================================

// ── Enums ──────────────────────────────────────────────────────────────────

/** Agent classification */
export type AgentType =
  | 'autonomous'
  | 'supervised'
  | 'tool_only'
  | 'sub_agent'
  | 'human_in_loop';

/** How much of the action payload is recorded vs. redacted */
export type RedactionLevel =
  | 'full'
  | 'metadata_only'
  | 'hash_only'
  | 'redacted';

/** Outcome of a tool call */
export type ToolCallStatus =
  | 'success'
  | 'failure'
  | 'timeout'
  | 'denied'
  | 'pending';

/** Result of an exposure check */
export type ExposureStatus =
  | 'clean'
  | 'exposed'
  | 'quarantined'
  | 'unknown';

/** Status of the PQ signature on a receipt */
export type SignatureStatus =
  | 'valid'
  | 'invalid'
  | 'unsigned'
  | 'expired';

/** Status of the H33-74 attestation (74-byte compact proof) */
export type H3374Status =
  | 'anchored'
  | 'pending'
  | 'unavailable';

// ── Receipt (universal response) ───────────────────────────────────────────

/** The universal receipt returned by every mutating endpoint */
export interface AgentReceipt {
  /** Unique receipt / DAG node ID */
  node_id: string;
  /** Agent that performed the action */
  agent_id: string;
  /** Session this action belongs to (null for register) */
  session_id: string | null;
  /** ISO-8601 timestamp */
  timestamp: string;
  /** What kind of action was attested */
  action_type: string;
  /** Human-readable summary of what happened */
  action_summary: string;
  /** SHA-256 hash of the input payload */
  input_hash: string;
  /** SHA-256 hash of the output payload */
  output_hash: string;
  /** Hash of the previous node in this session's chain */
  parent_hash: string | null;
  /** PQ signature verification status */
  signature_status: SignatureStatus;
  /** H33-74 compact attestation status */
  h33_74_status: H3374Status;
  /** Public verification URL */
  verification_url: string;
}

// ── Request types ──────────────────────────────────────────────────────────

/** POST /api/v1/agents/register */
export interface RegisterAgentRequest {
  /** Human-friendly name */
  display_name: string;
  /** Globally unique canonical name (dot-separated) */
  canonical_name: string;
  /** Agent classification */
  agent_type: AgentType;
  /** List of capability strings */
  capabilities: string[];
  /** Tenant/organization identifier */
  tenant_id: string;
  /** Optional metadata key-value pairs */
  metadata?: Record<string, string>;
}

/** POST /api/v1/agents/sessions/start */
export interface StartSessionRequest {
  /** Agent ID from registration */
  agent_id: string;
  /** Session duration in seconds */
  duration_secs: number;
  /** Canonical names of tools allowed in this session */
  allowed_tools?: string[];
  /** Data classification labels that must not be accessed */
  forbidden_data_classes?: string[];
  /** Optional parent session ID for sub-agent delegation */
  parent_session_id?: string;
  /** Optional metadata key-value pairs */
  metadata?: Record<string, string>;
}

/** POST /api/v1/agents/actions/attest */
export interface AttestActionRequest {
  /** Session ID */
  session_id: string;
  /** Action type label (e.g. 'database_query', 'api_call') */
  action_type: string;
  /** Human-readable description */
  action_summary: string;
  /** SHA-256 of the action input */
  input_hash: string;
  /** SHA-256 of the action output (omit if not yet known) */
  output_hash?: string;
  /** How much detail to record */
  redaction_level?: RedactionLevel;
  /** Optional metadata key-value pairs */
  metadata?: Record<string, string>;
}

/** POST /api/v1/agents/tools/attest */
export interface AttestToolRequest {
  /** Session ID */
  session_id: string;
  /** Canonical tool name */
  tool_name: string;
  /** SHA-256 hash of the tool request payload */
  request_hash: string;
  /** SHA-256 hash of the tool response payload (omit if pending) */
  response_hash?: string;
  /** Tool call outcome */
  status?: ToolCallStatus;
  /** Latency in milliseconds */
  latency_ms?: number;
  /** Optional metadata key-value pairs */
  metadata?: Record<string, string>;
}

/** POST /api/v1/agents/memory/checkpoint */
export interface MemoryCheckpointRequest {
  /** Session ID */
  session_id: string;
  /** SHA-256 hash of the full memory state */
  memory_hash: string;
  /** SHA-256 hash of the current context window */
  context_hash: string;
  /** Size of the memory state in bytes */
  size_bytes: number;
  /** Optional metadata key-value pairs */
  metadata?: Record<string, string>;
}

/** POST /api/v1/agents/sessions/end */
export interface EndSessionRequest {
  /** Session ID to end */
  session_id: string;
  /** Optional closing summary */
  summary?: string;
}

/** POST /api/v1/agents/delegate */
export interface DelegateRequest {
  /** Parent session ID */
  session_id: string;
  /** Agent ID of the delegate (sub-agent) */
  delegate_agent_id: string;
  /** Capabilities being delegated */
  delegated_capabilities: string[];
  /** Tools the delegate is allowed to use */
  allowed_tools?: string[];
  /** Maximum delegation depth (default 1) */
  max_depth?: number;
  /** Duration in seconds for the delegated session */
  duration_secs?: number;
  /** Optional metadata key-value pairs */
  metadata?: Record<string, string>;
}

/** POST /api/v1/agents/policy/evaluate */
export interface PolicyEvaluateRequest {
  /** Session ID */
  session_id: string;
  /** Action type to evaluate */
  action_type: string;
  /** Target resource or entity */
  target: string;
  /** Additional parameters for policy evaluation */
  params?: Record<string, unknown>;
}

/** POST /api/v1/agents/exposure/check */
export interface ExposureCheckRequest {
  /** Session ID */
  session_id: string;
  /** Data classification label */
  data_class: string;
  /** Operation being attempted */
  operation: string;
  /** SHA-256 hash of the data in question */
  data_hash?: string;
  /** Optional metadata key-value pairs */
  metadata?: Record<string, string>;
}

/** POST /api/v1/agents/approval/request */
export interface ApprovalRequest {
  /** Session ID */
  session_id: string;
  /** Action type requiring approval */
  action_type: string;
  /** Human-readable reason for the request */
  reason: string;
  /** Urgency level */
  urgency?: 'low' | 'medium' | 'high' | 'critical';
  /** Timeout in seconds before auto-deny */
  timeout_secs?: number;
  /** Optional metadata key-value pairs */
  metadata?: Record<string, string>;
}

/** POST /api/v1/agents/replay */
export interface ReplayRequest {
  /** Session ID to replay */
  session_id: string;
  /** Start from this node ID (inclusive) */
  from_node_id?: string;
  /** End at this node ID (inclusive) */
  to_node_id?: string;
  /** Maximum number of nodes to return */
  limit?: number;
}

/** POST /api/v1/agents/replay/fork */
export interface ReplayForkRequest {
  /** Session ID to fork from */
  session_id: string;
  /** Node ID to fork at */
  fork_at_node_id: string;
  /** New agent ID for the forked session */
  new_agent_id?: string;
}

/** POST /api/v1/agents/lineage/query */
export interface LineageQueryRequest {
  /** Node ID to query lineage for */
  node_id: string;
  /** Direction of traversal */
  direction?: 'ancestors' | 'descendants' | 'both';
  /** Maximum depth to traverse */
  max_depth?: number;
}

// ── Response types ─────────────────────────────────────────────────────────

/** Policy evaluation decision */
export interface PolicyDecision {
  /** Whether the action is allowed */
  allowed: boolean;
  /** Reason for the decision */
  reason: string;
  /** Policy that was evaluated */
  policy_id: string;
  /** Conditions or caveats */
  conditions?: string[];
}

/** GET /api/v1/agents/proof/:node_id (PUBLIC) */
export interface ProofResponse {
  /** The node ID this proof is for */
  node_id: string;
  /** Full receipt data */
  receipt: AgentReceipt;
  /** Merkle proof path */
  proof_path: string[];
  /** Whether the proof validates */
  valid: boolean;
  /** H33-74 compact attestation bytes (hex-encoded) */
  h33_74_attestation: string | null;
}

/** Response from replay endpoints */
export interface ReplayResponse {
  /** Session ID */
  session_id: string;
  /** Ordered list of receipts in the replay window */
  nodes: AgentReceipt[];
  /** Total nodes in the session */
  total_nodes: number;
  /** Whether the chain integrity is intact */
  chain_intact: boolean;
}

/** Response from lineage queries */
export interface LineageResponse {
  /** Root node ID */
  root_node_id: string;
  /** Lineage nodes (ordered by depth) */
  nodes: AgentReceipt[];
  /** Depth of the lineage tree */
  depth: number;
  /** Sessions involved in the lineage */
  sessions: string[];
}

/** Error response from the API */
export interface H33Error {
  /** HTTP status code */
  status: number;
  /** Error code */
  code: string;
  /** Human-readable error message */
  message: string;
  /** Request ID for debugging */
  request_id?: string;
}