Skip to content
Python
2.9 KB
Raw Blame
/** Wire contract validated against Core context_models.py / OpenAPI schema v1. */
export type ContextKind = "raw" | "memory";
export type ContextLimit =
  | "count_budget"
  | "character_budget"
  | "timeout_budget"
  | "metadata_budget";
export type ContextReason =
  | "not_requested"
  | "permission_required"
  | "source_revoked"
  | "read_unavailable"
  | "timeout_budget"
  | "evidence_changed"
  | "memory_changed"
  | "lexical_only";

export interface ContextSearchRequest {
  query: string;
  kinds?: ContextKind[];
  /** Narrows raw results only; never grants a source or changes memory scope. */
  raw_source_ids?: string[] | null;
  limit?: number;
  character_budget?: number;
  timeout_ms?: number;
}

export interface ContextMessage {
  evidence_id: string;
  revision: number;
  role: string;
  written_by: string;
  created_at: string | null;
  text: string;
  truncated: boolean;
}

export interface RawContextItem {
  kind: "raw";
  source_id: string;
  conversation_id: string;
  anchor_evidence_id: string;
  messages: ContextMessage[];
  truncated: boolean;
}

export interface MemoryContextItem {
  kind: "memory";
  memory_id: string;
  revision: number;
  content: string;
  memory_kind: string;
  updated_at: string;
  evidence_ids: string[];
  matched_by: readonly ("lexical" | "governed_semantic")[];
  truncated: boolean;
}

export type ContextItem = RawContextItem | MemoryContextItem;

export interface ContextPath {
  status:
    | "ok"
    | "empty"
    | "not_requested"
    | "not_authorized"
    | "unavailable"
    | "degraded";
  reason: ContextReason | null;
  elapsed_ms: number;
  returned_count: number;
  truncated: boolean;
  truncated_by: ContextLimit[];
}

export interface ContextSearchResponse {
  schema_version: 1;
  request_id: string;
  state: "grounded" | "empty" | "partial" | "unavailable";
  paths: { raw: ContextPath; memory: ContextPath };
  items: ContextItem[];
  used_characters: number;
  truncated: boolean;
  total_ms: number;
  adoption: "unknown";
}

export interface SdkRawContextItem {
  kind: "raw";
  raw_id: string;
  content: string;
  source: string;
  session_id: string;
  memory_at: string | null;
  score: number;
  truncated: boolean;
}

export interface SdkMemoryContextItem {
  kind: "memory";
  memory_id: string;
  content: string;
  layer: string;
  status: string;
  source: string | null;
  updated_at: string | null;
  score: number;
  truncated: boolean;
}

export type SdkContextItem = SdkRawContextItem | SdkMemoryContextItem;

export interface SdkContextSearchResponse {
  schema_version: 2;
  request_id: string;
  state: "grounded" | "empty" | "partial" | "unavailable";
  items: SdkContextItem[];
  used_characters: number;
  truncated: boolean;
  total_ms: number;
}

/** Native Host Bridge wire response. Schemas stay distinct and are never adapted. */
export type HostContextSearchResponse =
  | ContextSearchResponse
  | SdkContextSearchResponse;