Skip to content

AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).

227 KB
Raw Blame
import type { AlertApproval } from "@/lib/approvals";
import type { AnswerSources } from "@/lib/answerSources";
import type { DirectoryListing, DirectoryOption } from "@/lib/chatDirectory";
import type { HistoryNote, HistoryState } from "@/lib/history";
import type { NotificationSettings, NotificationSettingsUpdate } from "@/lib/notifications";
import type { SetupStatus } from "@/lib/setupStatus";

const API_BASE = "/api/backend";

export type CommitteePhase = "drafting" | "reviewing" | "finalizing";

// Inline action chip surfaced when the Executive fires a side-effecting
// tool (DM, schedule, workflow, roster mutation, alert, etc). Read-only
// tools never produce one. See backend `action_chips.SIDE_EFFECTING_TOOLS`
// for the canonical instrumented set; chip metadata is freezing once the
// `done` event arrives. Not persisted across sessions yet — see the
// `chat:` block in architecture-facts.yaml for the deferred persistence
// limitation.
export interface ActionTaken {
  type: "action_taken";
  tool: string;
  summary: string;
  target?: string | null;
  link?: string | null;
  iteration?: number;
  // An approval card's id (propose_actions): the chat shows the card itself
  // under the message.
  decision_id?: number;
  // A draft written as you (ghostwrite_email): the chat shows it under the
  // message with a Send button.
  draft?: ChatDraft;
}

export interface ChatDraft {
  row: number;
  to: string[];
  cc: string[];
  subject: string;
  // The start of the draft's text, as saved.
  preview: string;
}

// Names the round of tool calls currently in flight, so the progress line can
// say what is actually happening. One event per tool-use iteration, emitted
// immediately before `thinking`. Ephemeral — unlike ActionTaken it is never
// persisted with the assistant message. Real specialist fan-out is
// deliberately generic ("Consulting specialists…"); individual specialist
// names are never surfaced. See backend `orchestrator/activity_labels.py`.
// Shown when a tool round is in flight but no `activity` event named it —
// an older backend, or the agent loop's defensive fallback when the labeller
// itself failed. Deliberately worded the same as the backend's own
// `FALLBACK_LABEL` in orchestrator/activity_labels.py: both mean "something is
// running that we can't name". Nothing enforces that across the language
// boundary, so change the two together.
export const FALLBACK_ACTIVITY_LABEL = "Working…";

export interface Activity {
  type: "activity";
  // Present-progressive and already ends in an ellipsis — render verbatim.
  label: string;
  // Canonical tool behind the label; for MCP this is the underlying tool name.
  tool: string;
  iteration?: number;
}

export interface ChatChunk {
  type:
    | "chunk"
    | "done"
    | "error"
    | "thinking"
    | "phase"
    | "committee_critique"
    // The user pressed Stop. Always followed by `done` over the same still-open
    // stream, so the consumer's state machine still reaches a clean end.
    | "stopped";
  content?: string;
  session_id?: string;
  // On `done`: row id of the persisted assistant reply, used to attach 👍/👎.
  message_id?: number;
  message?: string;
  // committee fields (when type === "phase" or "committee_critique")
  phase?: CommitteePhase;
  reviewer?: string;
  severity?: "low" | "medium" | "high";
}

export type DebugEventKind =
  | "knowledge_retrieved"
  | "routing_decision"
  | "specialist_start"
  | "specialist_done"
  | "synthesis_start"
  | "synthesis_done"
  | "skill_invocation"
  | "script_run"
  | "turn_complete"
  | "turn_error"
  | "committee_review_start"
  | "committee_review_done"
  | "committee_revision_start";

export interface DebugEvent {
  type: "debug_event";
  kind: DebugEventKind;
  ts: number;
  data: Record<string, unknown>;
  turn_id?: string | null;
}

// ---- Ask OE page context (panel-only) ----
// Sent with panel turns so the Executive knows what page/form the user is
// looking at. Mirrors PageContext / PageFormDescriptor in the backend's
// api/models.py. The backend renders it into the USER turn (cache-safe).

export interface PageFormField {
  name: string;
  label: string;
  type: "text" | "textarea" | "number" | "boolean" | "select" | "json";
  description?: string;
  options?: string[];
  value?: unknown;
  required?: boolean;
}

export interface PageFormDescriptor {
  form_id: string;
  title: string;
  description?: string;
  fields: PageFormField[];
}

export interface PageContext {
  route: string;
  title: string;
  guide_section_id?: string | null;
  summary?: string;
  form?: PageFormDescriptor | null;
}

// Emitted when the Executive calls propose_form_values: suggested values
// for the form named in the page context. The panel applies them into the
// registered form as highlighted suggestions — never auto-submitted.
export interface FormPatch {
  type: "form_patch";
  form_id: string;
  fields: Record<string, unknown>;
  rationale?: string;
  iteration?: number;
}

// Sent once after the reply: what it looked at, and which part of the
// analysis it had to leave out (see lib/answerSources.ts).
export interface SourcesEvent extends AnswerSources {
  type: "sources";
  session_id?: string;
}

// The running turn took messages the user sent while it worked (POST
// /chat/add), named by the ids the client gave them.
export interface MessageAdded {
  type: "message_added";
  ids: string[];
}

// The turn held steps after reading something from outside: they wait on the
// person's go, offered as Approve / Not now under the reply.
export interface HeldStepsEvent {
  type: "held_steps";
  session_id?: string;
  steps: string[];
}

// What the content check flagged this turn, in plain words: shown under the
// reply (orchestrator/outside_content.py `pending_flags`).
export interface FlagsEvent {
  type: "flags";
  session_id?: string;
  flags: string[];
}

export type StreamItem =
  | ChatChunk
  | DebugEvent
  | ActionTaken
  | FormPatch
  | Activity
  | SourcesEvent
  | MessageAdded
  | HeldStepsEvent
  | FlagsEvent;

export interface StreamChatOptions {
  committeeReview?: boolean;
  // Files to attach to this turn. When non-empty, the request switches to
  // the multipart /chat/upload route; documents are auto-indexed into
  // Company Resources and images are forwarded as vision blocks.
  files?: File[];
  // Ask OE panel only — what page/form the user is looking at. Ignored on
  // the multipart route (the panel doesn't support attachments).
  pageContext?: PageContext;
  // Client-minted id for this turn, so it can be addressed by `stopChat`.
  // Omit it and the turn simply isn't stoppable.
  clientTurnId?: string;
  // What peer memory records as the user's words for this turn, when
  // `message` carries text they did not write (a briefing handoff seeds the
  // Executive's own card body). JSON route only; the multipart route derives
  // its own from the typed text and filenames.
  memoryText?: string;
  // Safety net only. The normal stop path leaves the stream open and lets the
  // server wind down and send `stopped` + `done`; this aborts the fetch
  // outright if that never arrives.
  signal?: AbortSignal;
}

export async function* streamChat(
  message: string,
  sessionId?: string,
  opts?: StreamChatOptions
): AsyncGenerator<StreamItem> {
  const files = opts?.files ?? [];
  const committeeReview = opts?.committeeReview ?? false;

  let response: Response;
  if (files.length > 0) {
    const form = new FormData();
    form.append("message", message);
    if (sessionId) form.append("session_id", sessionId);
    form.append("committee_review", String(committeeReview));
    if (opts?.clientTurnId) form.append("client_turn_id", opts.clientTurnId);
    for (const file of files) form.append("files", file, file.name);
    response = await fetch(`${API_BASE}/chat/upload`, {
      method: "POST",
      body: form,
      signal: opts?.signal,
    });
  } else {
    response = await fetch(`${API_BASE}/chat`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        message,
        session_id: sessionId,
        committee_review: committeeReview,
        page_context: opts?.pageContext ?? undefined,
        client_turn_id: opts?.clientTurnId ?? undefined,
        memory_text: opts?.memoryText ?? undefined,
      }),
      signal: opts?.signal,
    });
  }

  if (!response.ok) {
    let detail = response.statusText;
    try {
      const body = await response.json();
      if (body && typeof body.detail === "string") detail = body.detail;
    } catch {
      // body wasn't JSON — fall through with statusText
    }
    throw new Error(`Chat request failed: ${detail}`);
  }

  yield* sseData<StreamItem>(response);
}

/** Each `data:` line of a server-sent event stream, parsed. */
async function* sseData<T>(response: Response): AsyncGenerator<T> {
  const reader = response.body?.getReader();
  if (!reader) throw new Error("No response body");

  const decoder = new TextDecoder();
  let buffer = "";

  try {
    while (true) {
      const { done, value } = await reader.read();
      if (done) break;

      buffer += decoder.decode(value, { stream: true });
      const lines = buffer.split("\n");
      buffer = lines.pop() ?? "";

      for (const line of lines) {
        if (line.startsWith("data: ")) {
          try {
            const data: T = JSON.parse(line.slice(6));
            yield data;
          } catch {
            // skip malformed lines
          }
        }
      }
    }
  } finally {
    // `break`-ing out of the caller's `for await` closes this generator but
    // would otherwise leave the HTTP body open.
    await reader.cancel().catch(() => {});
  }
}

/** Ask the backend to stop an in-flight turn.
 *
 * Best-effort and never throws: a 404 just means the turn already ended, and a
 * network failure is covered by the caller's abort fallback. The SSE stream
 * stays the authority on how the turn actually finished — this only flips the
 * server-side switch. Returns whether the server accepted the stop.
 */
export interface VoiceStatus {
  available: boolean;
  max_seconds: number;
}

// Whether the chat mic can turn speech into words here. Null when the
// backend can't say (an older one): the mic stays hidden.
export async function getVoiceStatus(): Promise<VoiceStatus | null> {
  try {
    const res = await fetch(`${API_BASE}/chat/voice`);
    if (!res.ok) return null;
    return (await res.json()) as VoiceStatus;
  } catch {
    return null;
  }
}

// The words in one recording from the chat mic. Throws with a line fit to
// show under the message box.
export async function transcribeRecording(recording: Blob, filename: string): Promise<string> {
  const form = new FormData();
  form.append("file", recording, filename);
  let res: Response;
  try {
    res = await fetch(`${API_BASE}/chat/transcribe`, { method: "POST", body: form });
  } catch {
    throw new Error("Couldn't reach Open Executive to hear it. Try again.");
  }
  if (!res.ok) {
    let detail = "Couldn't hear it. Try again.";
    try {
      const body = await res.json();
      if (body && typeof body.detail === "string") detail = body.detail;
    } catch {
      // not JSON — keep the plain line
    }
    throw new Error(detail);
  }
  const body = (await res.json()) as { text?: string };
  return body.text ?? "";
}

export async function stopChat(clientTurnId: string): Promise<boolean> {
  try {
    const res = await fetch(`${API_BASE}/chat/stop`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ client_turn_id: clientTurnId }),
    });
    return res.ok;
  } catch {
    return false;
  }
}

// Hand a message to the turn that is still running, so its answer takes it
// into account. False when the turn won't take it (finished, stopped, full):
// the caller then sends it as the next turn.
export async function addChatMessage(
  clientTurnId: string,
  messageId: string,
  message: string,
): Promise<boolean> {
  try {
    const res = await fetch(`${API_BASE}/chat/add`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        client_turn_id: clientTurnId,
        message_id: messageId,
        message,
      }),
    });
    return res.ok;
  } catch {
    return false;
  }
}

export interface OnboardStatus {
  session_id: string;
  // The step's place among the steps this wizard asks (a solo workspace
  // skips the team steps), not an index into the full step list.
  current_step: number;
  total_steps: number;
  current_question: string | null;
  progress_percent: number;
  completed: boolean;
  // Whether the current step can be skipped. Absent from older backends.
  optional?: boolean;
}

export async function startOnboarding(): Promise<OnboardStatus> {
  const res = await fetch(`${API_BASE}/onboard/start`);
  if (!res.ok) throw new Error("Failed to start onboarding");
  return res.json();
}

export async function submitOnboardAnswer(
  sessionId: string,
  answer: string
): Promise<OnboardStatus> {
  const res = await fetch(`${API_BASE}/onboard/answer`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ session_id: sessionId, answer }),
  });
  if (!res.ok) throw new Error("Failed to submit answer");
  return res.json();
}

// ── conversational onboarding (/onboard/interview/*) ─────────────────────────
// The step-by-step wizard above stays as a fallback; this is the default flow.

export interface OnboardPersonDraft {
  full_name: string;
  role: string;
  is_principal: boolean;
}

export interface OnboardDepartmentDraft {
  title: string;
  mission: string;
  head_person_name: string;
  authority_level: string;
}

/** One of this year's goals. owner_name is a drafted person's name (blank =
 * the owner of the workspace); department_title names a drafted department. */
export interface OnboardGoalDraft {
  title: string;
  target: string;
  owner_name: string;
  department_title: string;
}

export interface OnboardTurn {
  session_id: string;
  phase: "question" | "draft";
  questions_asked: number;
  max_questions: number;
  question: string | null;
  question_hint: string | null;
  /** Suggested answers, shown as buttons to tap. */
  question_options: string[];
  draft: CompanyProfile | null;
  draft_people: OnboardPersonDraft[];
  draft_departments: OnboardDepartmentDraft[];
  draft_goals: OnboardGoalDraft[];
  confidence_notes: string[];
  summary: string | null;
  /** The website pages read for this setup (e.g. "example.com/team"), on the
   * opening turn only. Empty with a website given: it couldn't be read. */
  website_pages?: string[];
}

export interface OnboardTranscriptTurn {
  role: "user" | "assistant";
  text: string;
}

export interface OnboardSession extends OnboardTurn {
  turns: OnboardTranscriptTurn[];
  saved: boolean;
}

/** Pulls the backend's `detail` when there is one, so the user sees the real
 * reason (file too large, message too long) rather than a generic failure. */
async function onboardError(res: Response, fallback: string): Promise<Error> {
  const body = (await res.json().catch(() => ({}))) as { detail?: unknown };
  return new Error(typeof body.detail === "string" ? body.detail : fallback);
}

export async function startOnboardInterview(
  description: string,
  files: File[] = [],
  website = ""
): Promise<OnboardTurn> {
  const form = new FormData();
  form.append("description", description);
  if (website.trim()) form.append("website", website.trim());
  for (const file of files) form.append("files", file);
  const res = await fetch(`${API_BASE}/onboard/interview/start`, {
    method: "POST",
    body: form,
  });
  if (!res.ok) throw await onboardError(res, "Could not start setup");
  return res.json();
}

// What the first free-text description already says. Every field is null when
// the text does not say; the interview asks for what matters.
export interface OnboardUnderstanding {
  mode: WorkspaceMode | null;
  role_kind: RoleKind | null;
  role_title: string | null;
  reports_to: string | null;
  company: string | null;
  focus: string | null;
}

export async function understandOnboarding(
  description: string,
  files: File[] = [],
  website = ""
): Promise<OnboardUnderstanding> {
  const form = new FormData();
  form.append("description", description);
  if (website.trim()) form.append("website", website.trim());
  for (const file of files) form.append("files", file);
  const res = await fetch(`${API_BASE}/onboard/interview/understand`, {
    method: "POST",
    body: form,
  });
  if (!res.ok) throw await onboardError(res, "Could not read that");
  return res.json();
}

export async function sendOnboardMessage(
  sessionId: string,
  message: string
): Promise<OnboardTurn> {
  const res = await fetch(`${API_BASE}/onboard/interview/message`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ session_id: sessionId, message }),
  });
  if (!res.ok) throw await onboardError(res, "Could not send that message");
  return res.json();
}

export async function forceOnboardDraft(sessionId: string): Promise<OnboardTurn> {
  const res = await fetch(`${API_BASE}/onboard/interview/draft`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ session_id: sessionId }),
  });
  if (!res.ok) throw await onboardError(res, "Could not draft your profile");
  return res.json();
}

/** Change one of the person's earlier answers (0 = the description) and carry on from there. */
export async function reviseOnboardAnswer(
  sessionId: string,
  answer: number,
  message: string
): Promise<OnboardTurn> {
  const res = await fetch(`${API_BASE}/onboard/interview/revise`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ session_id: sessionId, answer, message }),
  });
  if (!res.ok) throw await onboardError(res, "Could not change that answer");
  return res.json();
}

/** Start over: the setup session is forgotten on the server at once. */
export async function discardOnboardInterview(sessionId: string): Promise<void> {
  const res = await fetch(`${API_BASE}/onboard/interview/${sessionId}`, { method: "DELETE" });
  if (!res.ok && res.status !== 404) throw new Error(`${res.status}`);
}

export async function getOnboardInterview(sessionId: string): Promise<OnboardSession> {
  const res = await fetch(`${API_BASE}/onboard/interview/${sessionId}`);
  if (!res.ok) throw new Error(`${res.status}`);
  return res.json();
}

export async function commitOnboardDraft(
  sessionId: string,
  profile: CompanyProfile,
  people: OnboardPersonDraft[],
  departments: OnboardDepartmentDraft[],
  goals: OnboardGoalDraft[],
  /** The principal's sign-in email, confirmed on the review screen. Blank = don't set one. */
  ownerEmail = ""
): Promise<CompanyProfile> {
  const res = await fetch(`${API_BASE}/onboard/interview/commit`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      session_id: sessionId,
      profile,
      people,
      departments,
      goals,
      owner_email: ownerEmail.trim() || null,
    }),
  });
  if (!res.ok) throw await onboardError(res, "Could not save your profile");
  return res.json();
}

export interface CompanyProfile {
  name: string;
  /** The company's own site, as setup read it. Absent from older servers. */
  website?: string;
  industry: string;
  stage: string;
  founding_year: number | null;
  headcount: number | null;
  annual_revenue_arr: number | null;
  mission: string;
  vision: string;
  target_customer: { profile: string; pain_points: string[] };
  competitive_landscape: { primary_competitors: string[]; competitive_advantages: string[] };
  org_structure: { departments: string[]; leadership_team: string[] };
  strategic_priorities: { current_year: string[]; north_star_metric: string };
  culture: { values: string[]; operating_principles: string[] };
  financials: { burn_rate_monthly: number | null; runway_months: number | null; key_metrics: Record<string, unknown> };
  /** External dependencies the research watch policy treats as company data. */
  vendors: string[];
  tickers: string[];
}

export async function getCompanyProfile(): Promise<CompanyProfile> {
  const res = await fetch(`${API_BASE}/company-profile`);
  if (!res.ok) throw new Error(`${res.status}`);
  return res.json();
}

export async function updateCompanyProfile(patch: Partial<CompanyProfile>): Promise<CompanyProfile> {
  const res = await fetch(`${API_BASE}/company-profile`, {
    method: "PATCH",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(patch),
  });
  if (!res.ok) throw new Error("Failed to update profile");
  return res.json();
}

export async function uploadDocument(
  file: File,
  domain = "general"
): Promise<{ filename: string; chunks_indexed: number; domain: string }> {
  const formData = new FormData();
  formData.append("file", file);
  formData.append("domain", domain);

  const res = await fetch(`${API_BASE}/documents`, {
    method: "POST",
    body: formData,
  });
  if (!res.ok) {
    let detail = "";
    try {
      const data = await res.json();
      if (typeof data?.detail === "string") detail = data.detail;
    } catch {
      // not JSON
    }
    throw new Error(detail || `Failed to upload ${file.name}`);
  }
  return res.json();
}

export interface CompanyDoc {
  filename: string;
  size_bytes: number;
  modified_at: number;
  source?: "upload";
  /** The domain the upload was indexed under ("general" when untagged). */
  domain?: string | null;
}

export async function listDocuments(): Promise<CompanyDoc[]> {
  const res = await fetch(`${API_BASE}/documents`);
  if (!res.ok) throw new Error("Failed to list documents");
  const data = await res.json();
  return data.documents;
}

export async function deleteDocument(filename: string): Promise<void> {
  const res = await fetch(`${API_BASE}/documents/${encodeURIComponent(filename)}`, {
    method: "DELETE",
  });
  if (!res.ok) throw new Error("Failed to delete document");
}

export interface CompanyDocContent {
  filename: string;
  content: string;
}

export async function getDocument(filename: string): Promise<CompanyDocContent> {
  const res = await fetch(`${API_BASE}/documents/${encodeURIComponent(filename)}`);
  if (!res.ok) throw new Error("Failed to fetch document content");
  return res.json();
}

// --- Connected sources (Google Drive, OneDrive, Notion) ----------------------

export type SyncedSourceId = "drive" | "onedrive" | "notion";

export interface SyncedDoc {
  id: string;
  name: string;
  url: string | null;
  modified_at: string | null;
  synced_at: string | null;
  indexed: boolean;
  /** Why a file has no readable text, when the sync knows (Drive only). */
  unreadable_reason?: string | null;
}

export interface SyncedDocList {
  enabled: boolean;
  last_run: string | null;
  last_error: string | null;
  files: SyncedDoc[];
}

export interface SyncedDocContent {
  id: string;
  name: string;
  url: string | null;
  content: string;
}

export interface SyncSourceStatus {
  id: SyncedSourceId;
  label: string;
  enabled: boolean;
  syncing: boolean;
  last_run: string | null;
  last_error: string | null;
  interval_minutes: number;
  file_count: number;
}

export async function listSyncSources(): Promise<SyncSourceStatus[]> {
  const res = await fetch(`${API_BASE}/documents/sources`);
  if (!res.ok) throw new Error("Failed to load connected sources");
  const data = await res.json();
  return data.sources;
}

export async function listSyncedDocuments(source: SyncedSourceId): Promise<SyncedDocList> {
  const res = await fetch(`${API_BASE}/documents/${source}`);
  if (!res.ok) throw new Error("Failed to list synced documents");
  return res.json();
}

export async function getSyncedDocument(
  source: SyncedSourceId,
  id: string
): Promise<SyncedDocContent> {
  const res = await fetch(`${API_BASE}/documents/${source}/${encodeURIComponent(id)}`);
  if (!res.ok) throw new Error("Failed to fetch document content");
  return res.json();
}

/** Start one sync now. Resolves to an error message the page can show, or null. */
export async function syncSourceNow(source: SyncedSourceId): Promise<string | null> {
  const res = await fetch(`${API_BASE}/documents/sources/${source}/sync`, { method: "POST" });
  if (res.ok) return null;
  try {
    const data = await res.json();
    if (typeof data?.detail === "string") return data.detail;
  } catch {
    // fall through
  }
  return "Could not start a sync";
}

export interface BuiltinFileMeta {
  domain: string;
  filename: string;
  size_bytes: number;
}

export interface BuiltinFileContent {
  domain: string;
  filename: string;
  content: string;
}

export async function listBuiltinFiles(): Promise<BuiltinFileMeta[]> {
  const res = await fetch(`${API_BASE}/knowledge/builtin`);
  if (!res.ok) throw new Error("Failed to fetch built-in files");
  const data = await res.json();
  return data.files;
}

export async function getBuiltinFile(
  domain: string,
  filename: string
): Promise<BuiltinFileContent> {
  const res = await fetch(`${API_BASE}/knowledge/builtin/${domain}/${filename}`);
  if (!res.ok) throw new Error("Failed to fetch file content");
  return res.json();
}

export async function createBuiltinFile(
  domain: string,
  filename: string,
  content: string
): Promise<{ chunks_indexed: number }> {
  const res = await fetch(`${API_BASE}/knowledge/builtin`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ domain, filename, content }),
  });
  if (!res.ok) {
    const err = await res.json().catch(() => ({}));
    throw new Error((err as { detail?: string }).detail ?? "Failed to create file");
  }
  return res.json();
}

export async function updateBuiltinFile(
  domain: string,
  filename: string,
  content: string
): Promise<{ chunks_indexed: number }> {
  const res = await fetch(`${API_BASE}/knowledge/builtin/${domain}/${filename}`, {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ domain, filename, content }),
  });
  if (!res.ok) throw new Error("Failed to save file");
  return res.json();
}

export async function deleteBuiltinFile(domain: string, filename: string): Promise<void> {
  const res = await fetch(`${API_BASE}/knowledge/builtin/${domain}/${filename}`, {
    method: "DELETE",
  });
  if (!res.ok) throw new Error("Failed to delete file");
}

// ---------------------------------------------------------------------------
// Failures (negative learnings) — same shape as builtin, separate routes.
// ---------------------------------------------------------------------------

export async function listFailureFiles(): Promise<BuiltinFileMeta[]> {
  const res = await fetch(`${API_BASE}/knowledge/failures`);
  if (!res.ok) throw new Error("Failed to fetch failure files");
  const data = await res.json();
  return data.files;
}

export async function getFailureFile(
  domain: string,
  filename: string
): Promise<BuiltinFileContent> {
  const res = await fetch(`${API_BASE}/knowledge/failures/${domain}/${filename}`);
  if (!res.ok) throw new Error("Failed to fetch failure content");
  return res.json();
}

export async function createFailureFile(
  domain: string,
  filename: string,
  content: string
): Promise<{ chunks_indexed: number }> {
  const res = await fetch(`${API_BASE}/knowledge/failures`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ domain, filename, content }),
  });
  if (!res.ok) {
    const err = await res.json().catch(() => ({}));
    throw new Error((err as { detail?: string }).detail ?? "Failed to create failure file");
  }
  return res.json();
}

export async function updateFailureFile(
  domain: string,
  filename: string,
  content: string
): Promise<{ chunks_indexed: number }> {
  const res = await fetch(`${API_BASE}/knowledge/failures/${domain}/${filename}`, {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ domain, filename, content }),
  });
  if (!res.ok) throw new Error("Failed to save failure file");
  return res.json();
}

export async function deleteFailureFile(domain: string, filename: string): Promise<void> {
  const res = await fetch(`${API_BASE}/knowledge/failures/${domain}/${filename}`, {
    method: "DELETE",
  });
  if (!res.ok) throw new Error("Failed to delete failure file");
}

// ---------------------------------------------------------------------------
// Knowledge search — "what would RAG retrieve" diagnostic
// ---------------------------------------------------------------------------

export type KnowledgeSourceType = "builtin" | "company" | "failures" | "external";

export interface KnowledgeSearchRequest {
  query: string;
  domain_filter?: string[];
  specialist?: string;
  n_builtin?: number;
  n_company?: number;
  n_failures?: number;
  n_external?: number;
  include?: KnowledgeSourceType[];
}

export interface KnowledgeSearchHit {
  filename: string;
  domain: string;
  source: string | null;
  source_id: string | null;
  source_url: string | null;
  license: string | null;
  publisher: string | null;
  chunk_index: number | null;
  distance: number;
  text: string;
}

export interface KnowledgeSearchResponse {
  query: string;
  effective_domains: string[] | null;
  specialists_that_would_see_this: string[];
  builtin: KnowledgeSearchHit[];
  company: KnowledgeSearchHit[];
  failures: KnowledgeSearchHit[];
  external: KnowledgeSearchHit[];
}

export async function searchKnowledge(
  body: KnowledgeSearchRequest
): Promise<KnowledgeSearchResponse> {
  const res = await fetch(`${API_BASE}/knowledge/search`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });
  if (!res.ok) {
    const err = await res.json().catch(() => ({}));
    throw new Error((err as { detail?: string }).detail ?? "Knowledge search failed");
  }
  return res.json();
}

// ---------------------------------------------------------------------------
// External / OER reference library (read-only)
// ---------------------------------------------------------------------------

export interface ExternalSourceInfo {
  id: string;
  title: string;
  publisher: string;
  license: string;
  phase: number;
  domains: string[];
  type: string;
  url: string;
  slug: string | null;
  chunks: number;
  files: number;
  is_ingested: boolean;
  last_fetched_at: number | null;
}

export interface ExternalSourcesResponse {
  sources: ExternalSourceInfo[];
  total_chunks: number;
}

export interface ExternalPeekChunk {
  domain: string;
  filename: string;
  chunk_index: number;
  text: string;
}

export interface ExternalPeekResponse {
  source_id: string;
  chunks: ExternalPeekChunk[];
}

export async function listExternalSources(): Promise<ExternalSourcesResponse> {
  const res = await fetch(`${API_BASE}/knowledge/external`);
  if (!res.ok) throw new Error("Failed to list reference sources");
  return res.json();
}

export async function peekExternalSource(
  sourceId: string,
  limit = 5
): Promise<ExternalPeekResponse> {
  const res = await fetch(
    `${API_BASE}/knowledge/external/${encodeURIComponent(sourceId)}/peek?limit=${limit}`
  );
  if (!res.ok) throw new Error("Failed to peek source");
  return res.json();
}

export interface SkillMeta {
  name: string;
  category: string;
  description: string;
  when_to_use: string;
  source: "builtin" | "company";
  filename: string;
  /** A company skill that replaces a built-in of the same name. */
  customized: boolean;
  /** A built-in hidden for this company (only listed with includeHidden). */
  hidden: boolean;
  /** Workflows whose steps follow this playbook (switched-off custom ones too). */
  used_by: { name: string; title: string; is_custom: boolean }[];
}

export interface SkillDetail extends SkillMeta {
  body: string;
}

export interface SkillInput {
  name: string;
  category: string;
  description: string;
  when_to_use: string;
  body: string;
}

/** What DELETE did: removed, reverted a customization, or hid a built-in. */
export type SkillDeleteOutcome = "deleted" | "reverted" | "hidden";

async function skillError(res: Response, fallback: string): Promise<Error> {
  const err = await res.json().catch(() => ({}));
  const detail = (err as { detail?: unknown }).detail;
  return new Error(typeof detail === "string" ? detail : fallback);
}

export async function listSkills(includeHidden = false): Promise<SkillMeta[]> {
  const qs = includeHidden ? "?include_hidden=true" : "";
  const res = await fetch(`${API_BASE}/skills${qs}`);
  if (!res.ok) throw new Error("Failed to list playbooks");
  const data = await res.json();
  return data.skills;
}

export async function getSkill(name: string): Promise<SkillDetail> {
  const res = await fetch(`${API_BASE}/skills/${encodeURIComponent(name)}`);
  if (!res.ok) throw await skillError(res, "Failed to load playbook");
  return res.json();
}

/** Full replace. On a built-in this saves a customized copy. */
export async function updateSkill(input: SkillInput): Promise<SkillDetail> {
  const res = await fetch(`${API_BASE}/skills/${encodeURIComponent(input.name)}`, {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(input),
  });
  if (!res.ok) throw await skillError(res, "Failed to save playbook");
  return res.json();
}

export async function deleteSkill(name: string): Promise<SkillDeleteOutcome> {
  const res = await fetch(`${API_BASE}/skills/${encodeURIComponent(name)}`, {
    method: "DELETE",
  });
  if (!res.ok) throw await skillError(res, "Failed to delete playbook");
  const data = (await res.json()) as { outcome: SkillDeleteOutcome };
  return data.outcome;
}

export interface SessionSummary {
  session_id: string;
  title: string;
  created_at: string;
  updated_at: string;
  message_count: number;
  /** Search results only: messages containing the words (0 = title match). */
  match_count?: number;
  /** Search results only: the newest matching message around the match. */
  snippet?: string;
  /** Set only while the owner has it pinned; pinned chats list first. */
  pinned_at?: string;
  /** A chat someone else shared with the caller: they write in it with its
   * owner, who alone renames, pins, shares or deletes it. */
  shared_with_you?: boolean;
  /** Shared chats only: the owner's name. */
  shared_by?: string;
  /** Shared-with-me list only: when it was shared. */
  shared_at?: string;
  /** The owner's topic this chat is filed under; absent when none. */
  topic_id?: number;
}

/** One of the caller's chat topics (the Topic view on Chats). */
export interface ChatTopic {
  id: number;
  name: string;
  chat_count: number;
  /** The owner named, pinned or filed a chat under it: shown even with one chat. */
  kept: boolean;
  pinned_at?: string;
  /** The broader matter it shares with related topics, shown as one heading over them. */
  area?: string;
  /** When its newest chat was last active. */
  updated_at?: string;
}

/** The caller's topics; `organizing` while older chats are still being filed. */
export async function listChatTopics(): Promise<{ topics: ChatTopic[]; organizing: boolean }> {
  const res = await fetch(`${API_BASE}/sessions/topics`);
  if (!res.ok) throw new Error("Failed to list topics");
  return res.json();
}

/** Rename and / or pin a topic. Renaming to another topic's name merges them. */
export async function updateChatTopic(
  topicId: number,
  patch: { name?: string; pinned?: boolean },
): Promise<ChatTopic> {
  const res = await fetch(`${API_BASE}/sessions/topics/${topicId}`, {
    method: "PATCH",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(patch),
  });
  if (!res.ok) throw await sessionError(res, "Couldn't update this topic.");
  return res.json();
}

/** Move every chat under one topic to another. */
export async function mergeChatTopic(topicId: number, intoId: number): Promise<void> {
  const res = await fetch(`${API_BASE}/sessions/topics/${topicId}/merge`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ into_id: intoId }),
  });
  if (!res.ok) throw await sessionError(res, "Couldn't merge these topics.");
}

/** Drop a topic; its chats stay, under no topic. */
export async function ungroupChatTopic(topicId: number): Promise<void> {
  const res = await fetch(`${API_BASE}/sessions/topics/${topicId}`, { method: "DELETE" });
  if (!res.ok) throw await sessionError(res, "Couldn't ungroup this topic.");
}

/** Rename one of the caller's areas; another area's name joins the two. */
export async function renameTopicArea(area: string, name: string): Promise<void> {
  const res = await fetch(`${API_BASE}/sessions/topic-areas/rename`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ area, name }),
  });
  if (!res.ok) throw await sessionError(res, "Couldn't rename this area.");
}

/** Drop an area; its topics stand on their own. */
export async function ungroupTopicArea(area: string): Promise<void> {
  const res = await fetch(`${API_BASE}/sessions/topic-areas/ungroup`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ area }),
  });
  if (!res.ok) throw await sessionError(res, "Couldn't ungroup this area.");
}

export async function listSessions(): Promise<SessionSummary[]> {
  const res = await fetch(`${API_BASE}/sessions`);
  if (!res.ok) throw new Error("Failed to list sessions");
  return res.json();
}

/** The caller's own chats whose title or messages contain `query`. */
export async function searchSessions(query: string, signal?: AbortSignal): Promise<SessionSummary[]> {
  const res = await fetch(`${API_BASE}/sessions?q=${encodeURIComponent(query)}`, { signal });
  if (!res.ok) throw new Error("Failed to search sessions");
  return res.json();
}

export async function getSessionMessages(sessionId: string): Promise<ChatMessage[]> {
  const res = await fetch(`${API_BASE}/sessions/${encodeURIComponent(sessionId)}/messages`);
  if (!res.ok) throw new Error("Failed to load session messages");
  return res.json();
}

export async function deleteSession(sessionId: string): Promise<void> {
  const res = await fetch(`${API_BASE}/sessions/${encodeURIComponent(sessionId)}`, {
    method: "DELETE",
  });
  if (!res.ok) throw new Error("Failed to delete session");
}

// The session routes' `detail` (a string for 409s, a list for 422s), or `fallback`.
async function sessionError(res: Response, fallback: string): Promise<Error> {
  const body = (await res.json().catch(() => ({}))) as { detail?: unknown };
  if (typeof body.detail === "string") return new Error(body.detail);
  const first = Array.isArray(body.detail) ? (body.detail[0] as { msg?: unknown }) : undefined;
  return new Error(typeof first?.msg === "string" ? first.msg : fallback);
}

/** One chat, as its owner or as someone it was shared with (`shared_with_you`). */
export async function getSession(sessionId: string): Promise<SessionSummary> {
  const res = await fetch(`${API_BASE}/sessions/${encodeURIComponent(sessionId)}`);
  if (res.status === 404) throw new Error("not_found");
  if (!res.ok) throw new Error("Failed to load session");
  return res.json();
}

/** Chats other people shared with the caller. */
export async function listSharedSessions(): Promise<SessionSummary[]> {
  const res = await fetch(`${API_BASE}/sessions/shared-with-me`);
  if (!res.ok) throw new Error("Failed to list shared chats");
  return res.json();
}

/** Rename, pin and / or file the caller's own chat. A renamed chat keeps its
 * name; `topic_id: null` files it under no topic, `topic_name` under that
 * topic (made if new). */
export async function updateSession(
  sessionId: string,
  patch: { title?: string; pinned?: boolean; topic_id?: number | null; topic_name?: string },
): Promise<SessionSummary> {
  const res = await fetch(`${API_BASE}/sessions/${encodeURIComponent(sessionId)}`, {
    method: "PATCH",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(patch),
  });
  if (!res.ok) throw await sessionError(res, "Couldn't update this chat.");
  return res.json();
}

/** Someone in a shared chat; the owner is listed first. */
export interface ChatPerson {
  person_id: number;
  full_name: string;
  owner: boolean;
}

/** Who is in a chat. `people` is empty while nobody else is in it. */
export interface ChatPeople {
  you: number | null;
  people: ChatPerson[];
}

export async function getSessionPeople(sessionId: string, signal?: AbortSignal): Promise<ChatPeople> {
  const res = await fetch(`${API_BASE}/sessions/${encodeURIComponent(sessionId)}/people`, { signal });
  if (res.status === 404) throw new Error("not_found");
  if (!res.ok) throw new Error("Failed to load who is in this chat");
  return res.json();
}

/** Tell the others in a shared chat the caller is writing. Never throws. */
export async function sendTyping(sessionId: string): Promise<void> {
  try {
    await fetch(`${API_BASE}/sessions/${encodeURIComponent(sessionId)}/typing`, { method: "POST" });
  } catch {
    // Only a hint: a lost one changes nothing.
  }
}

/** Leave a chat someone shared with the caller. */
export async function leaveSharedChat(sessionId: string): Promise<void> {
  const res = await fetch(`${API_BASE}/sessions/${encodeURIComponent(sessionId)}/shares/me`, {
    method: "DELETE",
  });
  if (!res.ok) throw await sessionError(res, "Couldn't leave this chat.");
}

/** A turn running in a shared chat, as `ready` hands it to a page that opens
 * while it runs. */
export interface LiveTurnSnapshot {
  turn_key: string;
  sender_person_id: number | null;
  sender_name: string;
  content: string;
  reply: string;
  actions: ActionTaken[];
}

/** What GET /sessions/{id}/live sends (`api/chat_live.py`). */
export type LiveChatEvent =
  | { type: "ready"; turn: LiveTurnSnapshot | null }
  | {
      type: "turn_started";
      turn_key: string;
      sender_person_id: number | null;
      sender_name: string;
      content: string;
    }
  | { type: "chunk"; turn_key: string; content: string }
  | { type: "thinking"; turn_key: string }
  | { type: "activity"; turn_key: string; label: string }
  | ({ turn_key: string } & ActionTaken)
  | { type: "phase"; turn_key: string; phase: CommitteePhase }
  | { type: "turn_ended"; turn_key: string }
  | { type: "typing"; person_id: number; name: string }
  | { type: "people" | "removed" | "deleted" | "resync" };

/** Follow a shared chat as it happens. Ends when the server ends the stream
 * (`removed`, `deleted`, `resync` come last) or `signal` aborts. Throws
 * "not_found" when the caller isn't in the chat. */
export async function* followChat(sessionId: string, signal: AbortSignal): AsyncGenerator<LiveChatEvent> {
  const res = await fetch(`${API_BASE}/sessions/${encodeURIComponent(sessionId)}/live`, { signal });
  if (res.status === 404) throw new Error("not_found");
  if (!res.ok) throw new Error("Couldn't follow this chat");
  yield* sseData<LiveChatEvent>(res);
}

export interface SessionShare {
  person_id: number;
  full_name: string;
  shared_at: string;
}

/** Who the owner shared this chat with. */
export async function getSessionShares(sessionId: string): Promise<SessionShare[]> {
  const res = await fetch(`${API_BASE}/sessions/${encodeURIComponent(sessionId)}/shares`);
  if (!res.ok) throw await sessionError(res, "Couldn't load who this chat is shared with.");
  return res.json();
}

/** Shares the chat with exactly these team members (anyone left out is
 * unshared). Throws the server's reason, e.g. a chat that read the owner's
 * own mail stays private. */
export async function setSessionShares(sessionId: string, personIds: number[]): Promise<SessionShare[]> {
  const res = await fetch(`${API_BASE}/sessions/${encodeURIComponent(sessionId)}/shares`, {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ person_ids: personIds }),
  });
  if (!res.ok) throw await sessionError(res, "Couldn't share this chat.");
  return res.json();
}

/** The filename in a Content-Disposition header, or null. */
export function dispositionFilename(header: string | null): string | null {
  if (!header) return null;
  const star = /filename\*=(?:UTF-8'')?([^;]+)/i.exec(header);
  if (star) {
    try {
      return decodeURIComponent(star[1].trim().replace(/^"|"$/g, ""));
    } catch {
      // Malformed encoding: fall through to the plain filename.
    }
  }
  const plain = /filename="?([^";]+)"?/i.exec(header);
  return plain ? plain[1].trim() : null;
}

/** The whole chat as Markdown, with the file name the server chose. */
export async function exportSession(sessionId: string): Promise<{ text: string; filename: string }> {
  const res = await fetch(`${API_BASE}/sessions/${encodeURIComponent(sessionId)}/export`);
  if (!res.ok) throw await sessionError(res, "Couldn't download this chat.");
  const text = await res.text();
  return { text, filename: dispositionFilename(res.headers.get("Content-Disposition")) ?? "chat.md" };
}

/** Takes back the chat's last turn (`lastMessageId` must still be its last
 * reply) and returns the words it answered, to send again. Throws the
 * server's reason on a 409 (still answering, moved on, not a web chat). */
export async function rewindSession(sessionId: string, lastMessageId: number): Promise<string> {
  const res = await fetch(`${API_BASE}/sessions/${encodeURIComponent(sessionId)}/rewind`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ last_message_id: lastMessageId }),
  });
  if (!res.ok) throw await sessionError(res, "Couldn't redo that answer.");
  const data = (await res.json()) as { message: string };
  return data.message;
}

export interface SuggestedPromptsResponse {
  prompts: string[];
  subtitle: string;
  context_quality: "rich" | "thin" | "empty";
}

export async function getSuggestedPrompts(
  signal?: AbortSignal,
): Promise<SuggestedPromptsResponse> {
  const res = await fetch(`${API_BASE}/chat/suggested-prompts`, { signal });
  if (!res.ok) throw new Error("Failed to load suggested prompts");
  return res.json();
}

// One suggested next message for the chat composer, grounded in the tail of
// the session. Resolves to null on any non-OK response — the composer then
// keeps its static placeholder — but rejects on abort so callers can tell a
// cancelled fetch apart from "no suggestion".
export async function getFollowupSuggestion(
  sessionId: string,
  signal?: AbortSignal,
): Promise<string | null> {
  const res = await fetch(
    `${API_BASE}/sessions/${encodeURIComponent(sessionId)}/followup`,
    { signal },
  );
  if (!res.ok) return null;
  const body: { suggestion?: unknown } = await res.json();
  return typeof body.suggestion === "string" && body.suggestion.trim()
    ? body.suggestion.trim()
    : null;
}

export interface ChatMessage {
  role: "user" | "assistant";
  content: string;
  // Inline action chips for assistant messages — populated from
  // `action_taken` SSE events during the live turn, and persisted to
  // `chat_messages.action_chips` so reopening a saved session restores
  // them (the backend re-attaches them here via load_messages).
  actions?: ActionTaken[];
  // True when the user stopped this reply mid-stream. Persisted to
  // `chat_messages.stopped`, so the marker survives a reload rather than
  // letting a truncated reply read as a complete one.
  stopped?: boolean;
  // Assistant rows only: what the reply looked at and which part of the
  // analysis it left out — from the stream's `sources` event, and persisted
  // to `chat_messages.sources` so a reloaded chat still shows it.
  sources?: AnswerSources;
  // Assistant rows only: the persisted row id (from the stream's `done`
  // event, or from a reloaded session) and any 👍/👎 on it. The id is what
  // lets the reply be rated.
  id?: number;
  feedback?: "up" | "down" | null;
  // User rows of a shared chat only: who wrote it.
  sender_person_id?: number;
  sender_name?: string;
  // The last reply only: steps its turn held after reading something from
  // outside, still waiting on the person's go. From the stream's
  // `held_steps` event, or re-attached when the chat is reloaded. Shown as
  // Approve / Not now buttons; Approve sends the go as their next message.
  held_steps?: string[];
  // The last reply only: what the content check flagged in what its turn
  // read, from the stream's `flags` event or re-attached on reload.
  flags?: string[];
}

export interface Decision {
  id: number;
  timestamp: string;
  domain: string;
  summary: string;
  rationale: string;
  outcome: string;
  tags: string;
}

export interface Initiative {
  id: number;
  title: string;
  status: string;
  created_at: string;
  updated_at: string;
  summary: string;
}

export interface Advice {
  id: number;
  timestamp: string;
  domain: string;
  query_summary: string;
  advice_summary: string;
}

// Peer memory — what the Executive has learned about each person, derived
// server-side and read-only here (no edit/delete: it is not the Executive's
// own record the way decisions and advice are).
export interface PersonConclusion {
  content: string;
  created_at: string;
}

export interface PersonMemory {
  person_id: number;
  full_name: string;
  is_principal: boolean;
  card: string[];
  conclusion_count: number;
  last_observed_at: string | null;
  recent: PersonConclusion[];
  error: string | null;
}

export interface PeopleMemory {
  status: "ok" | "disabled" | "error";
  people: PersonMemory[];
  conclusion_total: number;
}

export async function listDecisions(): Promise<Decision[]> {
  const res = await fetch(`${API_BASE}/memories/decisions`);
  if (!res.ok) throw new Error("Failed to list decisions");
  return res.json();
}

export async function updateDecision(id: number, patch: Partial<Omit<Decision, "id" | "timestamp">>): Promise<Decision> {
  const res = await fetch(`${API_BASE}/memories/decisions/${id}`, {
    method: "PATCH",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(patch),
  });
  if (!res.ok) throw new Error("Failed to update decision");
  return res.json();
}

export async function deleteDecision(id: number): Promise<void> {
  const res = await fetch(`${API_BASE}/memories/decisions/${id}`, { method: "DELETE" });
  if (!res.ok) throw new Error("Failed to delete decision");
}

/** A standing fact or correction the principal or a teammate asked the
 * Executive to keep (`memory/facts.py`). Every prompt that produces output
 * reads the active ones — a teammate's attributed "(per <name>)"; `proposed`
 * ones wait for the principal's approval and are never used until then.
 * `profile` rows record a company-profile field changed from chat. */
export interface StandingFact {
  id: number;
  kind: "fact" | "correction" | "profile";
  subject: string;
  statement: string;
  previous_statement: string;
  /** The speaker's own words; shown to the principal, and to a teammate for
   * their own facts only. */
  source_quote: string;
  source_channel: string;
  session_id: string | null;
  turn_id: string | null;
  recorded_by_person_id: number | null;
  created_at: string;
  status: "active" | "superseded" | "retired" | "proposed" | "declined";
  superseded_by: number | null;
  retired_at: string | null;
  retired_reason: string;
  recorded_by_role: "principal" | "teammate";
  /** The teammate's name when they recorded it; empty for the principal's. */
  recorded_by_name: string;
  /** A proposal: the active fact it replaces once approved. */
  replaces_fact_id: number | null;
}

export interface StandingFactsPage {
  facts: StandingFact[];
  can_retire: boolean;
  /** The facts this caller may retire (a teammate: their own). */
  retirable_ids: number[];
  /** The principal: approves teammates' proposals and sets who needs approval. */
  can_review: boolean;
}

/** One teammate and whether the principal approves their facts first. */
export interface FactApprovalRule {
  person_id: number;
  full_name: string;
  needs_approval: boolean;
}

export async function listStandingFacts(): Promise<StandingFactsPage> {
  const res = await fetch(`${API_BASE}/memories/facts`);
  if (!res.ok) throw new Error("Failed to list standing facts");
  return res.json();
}

export async function retireStandingFact(id: number, reason = ""): Promise<StandingFact> {
  const res = await fetch(`${API_BASE}/memories/facts/${id}/retire`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ reason }),
  });
  if (!res.ok) throw new Error("Failed to retire standing fact");
  return res.json();
}

export async function reviewStandingFact(
  id: number,
  decision: "approve" | "decline",
): Promise<StandingFact> {
  const res = await fetch(`${API_BASE}/memories/facts/${id}/${decision}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({}),
  });
  if (!res.ok) throw new Error(`Failed to ${decision} standing fact`);
  return res.json();
}

export async function listFactApprovalRules(): Promise<FactApprovalRule[]> {
  const res = await fetch(`${API_BASE}/memories/facts/approval`);
  if (!res.ok) throw new Error("Failed to list who needs approval");
  return res.json();
}

export async function setFactApprovalRule(
  personId: number,
  needsApproval: boolean,
): Promise<FactApprovalRule> {
  const res = await fetch(`${API_BASE}/memories/facts/approval/${personId}`, {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ needs_approval: needsApproval }),
  });
  if (!res.ok) throw new Error("Failed to change who needs approval");
  return res.json();
}

export async function listInitiatives(): Promise<Initiative[]> {
  const res = await fetch(`${API_BASE}/memories/initiatives`);
  if (!res.ok) throw new Error("Failed to list initiatives");
  return res.json();
}

export async function updateInitiative(id: number, patch: Partial<Omit<Initiative, "id" | "created_at" | "updated_at">>): Promise<Initiative> {
  const res = await fetch(`${API_BASE}/memories/initiatives/${id}`, {
    method: "PATCH",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(patch),
  });
  if (!res.ok) throw new Error("Failed to update initiative");
  return res.json();
}

export async function deleteInitiative(id: number): Promise<void> {
  const res = await fetch(`${API_BASE}/memories/initiatives/${id}`, { method: "DELETE" });
  if (!res.ok) throw new Error("Failed to delete initiative");
}

export async function listAdvice(): Promise<Advice[]> {
  const res = await fetch(`${API_BASE}/memories/advice`);
  if (!res.ok) throw new Error("Failed to list advice");
  return res.json();
}

export async function updateAdvice(id: number, patch: Partial<Omit<Advice, "id" | "timestamp">>): Promise<Advice> {
  const res = await fetch(`${API_BASE}/memories/advice/${id}`, {
    method: "PATCH",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(patch),
  });
  if (!res.ok) throw new Error("Failed to update advice");
  return res.json();
}

export async function deleteAdvice(id: number): Promise<void> {
  const res = await fetch(`${API_BASE}/memories/advice/${id}`, { method: "DELETE" });
  if (!res.ok) throw new Error("Failed to delete advice");
}

// Settings → About you reads this on mount; behind it are one Honcho listing
// plus two reads per person, so mounts close together (a remount, a quick
// revisit) share one in-flight request instead of repeating that fan-out.
const PEOPLE_MEMORY_SHARE_MS = 5_000;
// `settledAt` is null while the request is still running: a pending request is
// always shared, however long it has run (the backend bounds it, not us), and a
// resolved one for five seconds after it settled.
let peopleMemoryShared: {
  recent: number;
  promise: Promise<PeopleMemory>;
  settledAt: number | null;
} | null = null;

export function listPeopleMemory(recent = 5): Promise<PeopleMemory> {
  const shared = peopleMemoryShared;
  if (
    shared &&
    shared.recent === recent &&
    (shared.settledAt === null || Date.now() - shared.settledAt < PEOPLE_MEMORY_SHARE_MS)
  ) {
    return shared.promise;
  }
  const promise = (async () => {
    const res = await fetch(`${API_BASE}/memories/people?recent=${recent}`);
    if (!res.ok) throw new Error("Failed to list people memory");
    return (await res.json()) as PeopleMemory;
  })();
  const entry = { recent, promise, settledAt: null as number | null };
  peopleMemoryShared = entry;
  promise.then(
    () => {
      entry.settledAt = Date.now();
    },
    () => {
      // A failure must not be served to the next caller.
      if (peopleMemoryShared === entry) peopleMemoryShared = null;
    },
  );
  return promise;
}

export interface PersonConclusionsPage {
  status: "ok" | "disabled" | "error";
  person_id: number;
  items: PersonConclusion[];
  page: number;
  size: number;
  total: number | null;
  has_more: boolean;
}

// Every conclusion about one person, newest first, one page at a time — the
// "show all" notes pane in Settings → About you. The overview above carries only the newest few.
export async function listPersonConclusions(
  personId: number,
  page: number,
  size = 50,
): Promise<PersonConclusionsPage> {
  const res = await fetch(
    `${API_BASE}/memories/people/${personId}/conclusions?page=${page}&size=${size}`,
  );
  if (!res.ok) throw new Error("Failed to list person conclusions");
  return res.json();
}

export interface ScheduledAction {
  id: number;
  created_at: string;
  run_at: string;
  channel: string;
  channel_ref: string;
  intent_text: string;
  originating_session_id: string | null;
  status: string;
  attempts: number;
  last_error: string;
  // `kind` distinguishes recurring rhythms (principal_brief_morning,
  // executive_reflection, dept_cadence, …) from one-off follow-ups (ad_hoc)
  // and internal heartbeats (nudge_scan, external_monitor_scan). Always on
  // the wire from GET /scheduled — the Pulse page groups rows by it.
  kind: string;
  department: string;
  assigned_to_person_id: number | null;
  awaiting_response_since: string | null;
  scope_key: string | null;
}

export async function listScheduledActions(
  status: string = "pending",
  limit: number = 100,
  signal?: AbortSignal,
  order: "asc" | "desc" = "asc",
): Promise<ScheduledAction[]> {
  const params = new URLSearchParams({ status, limit: String(limit), order });
  const res = await fetch(`${API_BASE}/scheduled?${params.toString()}`, { signal });
  if (!res.ok) throw new Error("Failed to list scheduled actions");
  return res.json();
}

export async function cancelScheduledAction(id: number): Promise<ScheduledAction> {
  const res = await fetch(`${API_BASE}/scheduled/${id}`, { method: "DELETE" });
  if (res.status === 409) {
    throw new Error("Action is no longer pending — can't cancel.");
  }
  if (res.status === 401 || res.status === 503) {
    // Signed-in users can cancel once the API and the UI share
    // BACKEND_SHARED_SECRET (every internet-reachable deploy sets it).
    throw new Error(
      "Cancel isn't enabled on this server yet. Ask your administrator to set the same BACKEND_SHARED_SECRET on the API and the UI.",
    );
  }
  if (!res.ok) throw new Error("Failed to cancel scheduled action");
  return res.json();
}

// ----------------------------------------------------------------------------
// Executive pause switch — holds all autonomous work (scheduler, inbox,
// workflow timers); chat and direct messages keep working.
// ----------------------------------------------------------------------------

export interface ExecutiveStatus {
  paused: boolean;
  paused_at: string | null;
  paused_by: string | null;
  reason: string | null;
  // Pending scheduled actions already due — they fire on resume.
  held_actions: number;
  // Whether the signed-in viewer may resume (principal-only once one exists).
  can_resume: boolean;
  // What the Executive calls itself (EXEC_DISPLAY_NAME).
  name?: string;
}

export async function getExecutiveStatus(signal?: AbortSignal): Promise<ExecutiveStatus> {
  const res = await fetch(`${API_BASE}/executive/status`, { signal });
  if (!res.ok) throw new Error("Failed to load executive status");
  return res.json();
}

// Settings → Setup status. The API tests each part of the install live, so
// this can take a few seconds; see api/setup_checks.py.
export async function getSetupStatus(signal?: AbortSignal): Promise<SetupStatus> {
  const res = await fetch(`${API_BASE}/setup/status`, { signal, cache: "no-store" });
  if (!res.ok) throw new Error(`Setup status request failed (HTTP ${res.status})`);
  return res.json();
}

// Settings → Your Executive → When should I check with you?: the safety
// level, "ask" (Careful), "outsiders" (Balanced) or "trust" (Hands-off), and
// the channels set apart from it (orchestrator/outside_mode.py).
export type OutsideContentMode = "ask" | "outsiders" | "trust";

export interface OutsideContentSetting {
  mode: OutsideContentMode;
  // Channel id → its own level; a channel not listed follows `mode`.
  channels: Record<string, OutsideContentMode>;
  // The channels a level can be set on, in order.
  channel_ids: string[];
  can_change: boolean;
}

export async function getOutsideContent(signal?: AbortSignal): Promise<OutsideContentSetting> {
  const res = await fetch(`${API_BASE}/executive/outside-content`, { signal, cache: "no-store" });
  if (!res.ok) throw new Error("Couldn't load this setting");
  return res.json();
}

// `channels`: a level sets that channel apart, null makes it follow `mode`
// again; channels left out keep what they have.
export async function setOutsideContent(
  mode: OutsideContentMode,
  channels?: Record<string, OutsideContentMode | null>,
): Promise<OutsideContentSetting> {
  const res = await fetch(`${API_BASE}/executive/outside-content`, {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(channels ? { mode, channels } : { mode }),
  });
  if (res.status === 403) throw new Error("Only the account owner can change this.");
  if (!res.ok) throw new Error("Couldn't save that. Try again.");
  return res.json();
}

export async function pauseExecutive(reason?: string): Promise<ExecutiveStatus> {
  const res = await fetch(`${API_BASE}/executive/pause`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ reason: reason?.trim() || null }),
  });
  if (!res.ok) throw new Error("Failed to pause the Executive");
  delegationChanged();
  return res.json();
}

export async function resumeExecutive(): Promise<ExecutiveStatus> {
  const res = await fetch(`${API_BASE}/executive/resume`, { method: "POST" });
  if (res.status === 403) throw new Error("Only the principal can resume the Executive.");
  if (!res.ok) throw new Error("Failed to resume the Executive");
  delegationChanged();
  return res.json();
}

// ----------------------------------------------------------------------------
// Workspace settings — solo / team mode, the user's time zone, and the
// principal's role.
// ----------------------------------------------------------------------------

// "solo": one person using Open Executive just for themselves (no department
// check-ins). "team": a company with departments and people (the default).
export type WorkspaceMode = "solo" | "team";

// How the principal relates to the organisation in their profile: they own
// it, they work inside one they don't own, they serve clients independently,
// or something else.
export type RoleKind = "owner" | "in_house" | "independent" | "other";

// What the principal does. Solo mode tells the Executive and its specialists;
// every field is null until set.
export interface PrincipalRole {
  role_kind: RoleKind | null;
  role_title: string | null;
  reports_to: string | null;
  remit: string | null;
  measured_on: string | null;
}

export interface WorkspaceSettings extends PrincipalRole {
  mode: WorkspaceMode;
  // IANA zone the user set, or null when none is set.
  timezone: string | null;
  // The zone in effect: `timezone`, else the server's USER_TIMEZONE, else UTC.
  effective_timezone: string;
  // The company's own email domains (principal only): on one of them an
  // address matches a teammate by its local part. Derived from the
  // principal's addresses unless `company_domains_custom`.
  company_domains?: string[];
  company_domains_custom?: boolean;
  // Whether any department exists; the Departments tab shows only then.
  // Optional so an older API build reads as "yes" (the tab stays).
  has_departments?: boolean;
}

// Partial update: only the fields present change. `timezone: null` (or "")
// clears the stored zone; the role fields clear the same way.
export interface WorkspaceUpdate extends Partial<PrincipalRole> {
  mode?: WorkspaceMode;
  timezone?: string | null;
  // null goes back to deriving them from the principal's addresses.
  company_domains?: string[] | null;
}

/** GET /version: the running version and, unless turned off, the latest release. */
export interface VersionInfo {
  current: string;
  latest: string | null;
  update_available: boolean;
  release_url: string | null;
  check_enabled: boolean;
}

export async function getVersion(signal?: AbortSignal): Promise<VersionInfo> {
  const res = await fetch(`${API_BASE}/version`, { signal });
  if (!res.ok) throw new Error("Failed to load version");
  return res.json();
}

export async function getWorkspace(signal?: AbortSignal): Promise<WorkspaceSettings> {
  const res = await fetch(`${API_BASE}/workspace`, { signal });
  if (!res.ok) throw new Error("Failed to load workspace settings");
  return res.json();
}

export async function updateWorkspace(update: WorkspaceUpdate): Promise<WorkspaceSettings> {
  const res = await fetch(`${API_BASE}/workspace`, {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(update),
  });
  if (res.status === 403) throw new Error("Only the principal can change workspace settings.");
  if (res.status === 422) {
    // FastAPI validation errors: `detail` is a list of {msg}; surface the
    // first one ("timezone 'Mars/Base' is not a known IANA zone",
    // "remit must be at most 500 characters").
    const body = (await res.json().catch(() => ({}))) as { detail?: unknown };
    const first = Array.isArray(body.detail) ? (body.detail[0] as { msg?: unknown }) : undefined;
    const msg = typeof first?.msg === "string" ? first.msg.replace(/^Value error, /, "") : null;
    throw new Error(msg ?? "Invalid workspace settings");
  }
  if (!res.ok) throw new Error("Failed to update workspace settings");
  return res.json();
}

// ----------------------------------------------------------------------------
// Act as me — the Executive drafts email AS you, in your own Drafts (Gmail or Outlook),
// when you ask it to or (with Drafts for my inbox or above) for mail that
// needs you. It sends only a reply card's draft, when you tap Send. The owner
// can have it, and team members too once the owner lets them.
// ----------------------------------------------------------------------------
export type DelegationGmailStatus =
  | "connected"
  | "not_configured"
  | "needs_reconnect"
  | "mismatch"
  | "no_email"
  | "shared_mailbox"
  | "error";

export interface DelegationSettings {
  enabled: boolean;
  gmail: {
    status: DelegationGmailStatus;
    message: string;
    email: string | null;
    // How to connect your own Gmail or Outlook (the token is minted locally).
    connect_command: string;
    // Absent on a backend that predates Outlook.
    outlook_connect_command?: string;
    // Which mailbox the saved sign-in opens.
    provider?: "google" | "microsoft";
  };
  // Absent on a backend that predates the inbox watcher.
  inbox?: InboxWatch;
  // Absent (or null) on a backend that predates Handle it for me.
  handle_it?: HandleIt | null;
  // Absent (or null) on a backend that predates per-setting training.
  training?: Training | null;
  // Absent (or null) on a backend that predates the AI line on replies.
  disclosure?: ReplyDisclosure | null;
  // Absent (or null) on a backend that predates Read my calendar.
  calendar?: ReadMyCalendar | null;
  // The owner's "Let team members use Act as me", while the install allows
  // it; null (or absent) for everyone else.
  team?: DelegationTeam | null;
}

// Each team member's use, as the owner sees it: counts only, never what they
// wrote or to whom.
export interface DelegationTeamMember {
  person_id: number;
  name: string;
  enabled: boolean;
  inbox: boolean;
  drafts_30d: number;
  sent_30d: number;
}

export interface DelegationTeam {
  enabled: boolean;
  members: DelegationTeamMember[];
}

// "Draft replies to my inbox": the Executive watches your own inbox and, for
// mail that needs you, saves a first reply in your Gmail Drafts; each waits
// on a card on Today (GET /delegation/replies).
export interface InboxWatch {
  enabled: boolean;
  // off, waiting, ok, checking, daily_limit, backlog_full, act_as_me_off,
  // client_slot, rate_limited, error, or why your Gmail can't be read.
  status: string;
  // The status in plain words, from the backend.
  message: string;
  watch_since: string | null;
  last_poll_at: string | null;
  checking: boolean;
  // Also save each reply in your mailbox's Drafts (off: on its card alone).
  mailbox_drafts?: boolean;
}

// Handle it for me: the inbox watcher sends some replies on its own,
// decided by plain code (delegation/handle_it.py). Each kind of reply has a
// level; "ask" leaves a card as before.
// How much Handle it for me sends on its own (delegation/handle_it.py RULES).
export type HandleItMode = "careful" | "balanced" | "bold";

// Act as me's settings that can each be in training (delegation/training.py).
export type TrainingSetting = "replies" | "follow_ups" | "actions" | "drafts";

// Something Act as me learned in training, yours alone (DELETE
// /delegation/learned/{id}): a person replies or follow-ups may go to, an
// action allowed with Approve + allow, or how you write to someone.
export interface TrainingLearned {
  id: number;
  label: string;
  setting: TrainingSetting;
  // What you sent after changing a draft, kept as an example ("").
  example: string;
  uses: number;
  created_at: string;
}

export interface Training {
  replies: boolean;
  follow_ups: boolean;
  actions: boolean;
  drafts: boolean;
  // Suggested actions On: carried out with no tick (false while in training).
  actions_on?: boolean;
  learned: TrainingLearned[];
}

// Read my calendar (delegation/calendar.py): your own calendar, read-only,
// through the same sign-in as your mailbox when it was connected with
// --calendar (connect_command). `granted`: whether that sign-in includes the
// calendar; null (or absent, on an older backend) when it isn't known.
export interface ReadMyCalendar {
  enabled: boolean;
  granted?: boolean | null;
  connect_command: string;
}

// The AI line on replies sent as you (delegation/disclosure.py): on replies
// Handle it for me sends on its own, and on drafts you send. `enabled` is the
// install's AI_DISCLOSURE; when it's off neither line is added.
export interface ReplyDisclosure {
  enabled: boolean;
  handle_it: boolean;
  approved_sends: boolean;
  line: string;
}

export interface HandleIt {
  enabled: boolean;
  mode: HandleItMode;
  // Whether this server can tie the switch to you (signed sign-ins or local
  // login); without it nothing is sent on its own.
  available: boolean;
  sent_today: number;
  // Take the lead as you: the setting gives way to your rules. Only the
  // owner can have it for now (lead_available).
  lead?: boolean;
  lead_available?: boolean;
}

// One reply sent on its own, yours alone (GET /delegation/handled).
export interface HandledReply {
  decision_id: number;
  sent_at: string;
  to_name: string;
  to_email: string;
  subject: string;
  body: string;
  open_questions: string[];
  gmail_link: string;
  // "follow_up": a follow-up to your own unanswered email; "invite": a
  // meeting invite it accepted on its own.
  source?: string;
  // One line for an invite: "Accepted Dana's Pilot review, Wed 21 Oct, 14:30".
  summary?: string;
}

// One reply the inbox watcher drafted: a `delegation_reply` decision, yours
// alone. Send approves it (POST /decisions/{id}/approve); Dismiss rejects it
// (POST /decisions/{id}/reject). `status` is "executing" while a send Gmail
// didn't confirm is being checked.
export interface ReplyTurn {
  kind: "news" | "asked" | "note" | string;
  text: string;
  from_name?: string;
  from_email?: string;
  at?: string;
}

export interface ReplyCard {
  decision_id: number;
  status: string;
  created_at: string;
  thread_id: string;
  from_name: string;
  from_email: string;
  // team, contact, correspondent (you've written to them) or stranger.
  relation: string;
  sender_verified: boolean;
  subject: string;
  received_at: string;
  // Their new words, quoted replies stripped.
  they_wrote: string;
  draft_to: string[];
  draft_subject: string;
  draft_body: string;
  // What the draft leaves for you to decide.
  open_questions: string[];
  flags: string[];
  // Opens the draft in your own mailbox (the thread, in Gmail).
  gmail_link: string;
  // Why Handle it for me left it for you; absent or "" when it didn't decide.
  waited_because?: string;
  // "follow_up": the draft chases your own unanswered email.
  source?: string;
  // In training: Send + allow is offered (replies, or a follow-up's people,
  // aren't allowed yet).
  can_allow?: boolean;
  // Drafts in training: "Do it like this next time" keeps your changed draft.
  learns_style?: boolean;
  // Also saved in your mailbox's Drafts; false when it waits on this card
  // alone until you send it.
  in_mailbox?: boolean;
  // Which of your mailboxes it sends from: "Gmail" or "Outlook".
  mailbox?: string;
  // The open questions with answers to tap; absent on an older backend,
  // and a card made before choices has none.
  questions?: ReplyQuestion[];
  // You changed the words by hand: what is left open no longer holds Send.
  questions_settled?: boolean;
  // Only from answering: the sentences the rewrite added or changed.
  changed_sentences?: string[];
  // Everyone else the email went to: Reply to: Everyone adds them. Empty or
  // absent when there is no choice to make.
  reply_others?: string[];
  // What the email asks and what the draft says, in a line or two, for the
  // card's closed view; empty or absent on a card drafted before it.
  gist?: string;
  // Since the draft was written: newer email in the conversation ("news"),
  // what you asked to change ("asked") and what the Executive changed
  // ("note"), in order. Absent on an older backend.
  conversation?: ReplyTurn[];
  // When the reply was last brought up to date with newer mail; Send passes
  // it back, so a version you never saw asks again.
  caught_up_at?: string;
}

// One thing a reply leaves you to decide (GET /delegation/replies).
export interface ReplyQuestion {
  text: string;
  // 2 to 4 short answers to tap, or none.
  choices: string[];
  // Where they came from ("I checked your calendar: these are free."), or "".
  source: string;
  // The answer you gave on the card, "" while it is open.
  answer: string;
}

// "How I write": learned from your own sent mail; you can edit and lock it.
export interface VoiceProfile {
  greetings: Record<string, string>;
  sign_off: string;
  signature: string;
  length: string;
  formality: string;
  habits: string[];
  avoid: string[];
  exemplars: string[];
  locked: boolean;
  learned_at: string | null;
  sample_count: number;
  updated_at: string | null;
  // "learn" when the last change was a learn pass, else who changed it.
  updated_by?: string | null;
}

// A style written from the person's own words (POST /delegation/voice/describe):
// not saved until they save it with updateVoiceProfile.
export interface DescribedVoice {
  greetings: Record<string, string>;
  sign_off: string;
  length: string;
  formality: string;
  habits: string[];
  avoid: string[];
  sample_reply: string;
}

export interface VoiceUpdate {
  greetings?: Record<string, string>;
  sign_off?: string;
  length?: string;
  formality?: string;
  habits?: string[];
  avoid?: string[];
  locked?: boolean;
  clear_exemplars?: boolean;
  clear_signature?: boolean;
}

// The route's errors carry `detail: {code, message}` (or FastAPI's list).
async function delegationError(res: Response, fallback: string): Promise<Error> {
  const body = (await res.json().catch(() => ({}))) as { detail?: unknown };
  const detail = body.detail;
  if (typeof detail === "string") return new Error(detail);
  if (detail && typeof detail === "object" && !Array.isArray(detail)) {
    const message = (detail as { message?: unknown }).message;
    if (typeof message === "string") return new Error(message);
  }
  return new Error(fallback);
}

// null when this viewer can't have it (403) or the backend predates it (404).
export async function getDelegation(signal?: AbortSignal): Promise<DelegationSettings | null> {
  const res = await fetch(`${API_BASE}/delegation`, { signal });
  if (res.status === 403 || res.status === 404) return null;
  if (!res.ok) throw await delegationError(res, "Couldn't load Act as me.");
  return res.json();
}

// ---------------------------------------------------------------------------
// Settings → Notifications: the caller's own quiet hours, digest or instant,
// and urgent things through (/notifications/settings).
// ---------------------------------------------------------------------------

export type {
  Delivery,
  NotificationSettings,
  NotificationSettingsUpdate,
  QuietDays,
  QuietHours,
} from "@/lib/notifications";

// null when this viewer has none to set (403: not signed in or not on the
// People list) or the backend predates it (404).
export async function getNotificationSettings(signal?: AbortSignal): Promise<NotificationSettings | null> {
  const res = await fetch(`${API_BASE}/notifications/settings`, { signal });
  if (res.status === 403 || res.status === 404) return null;
  if (!res.ok) throw await delegationError(res, "Couldn't load your notification settings.");
  return res.json();
}

export async function updateNotificationSettings(
  update: NotificationSettingsUpdate,
): Promise<NotificationSettings> {
  const res = await fetch(`${API_BASE}/notifications/settings`, {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(update),
  });
  if (!res.ok) throw await delegationError(res, "Couldn't save your notification settings.");
  return res.json();
}

// ---------------------------------------------------------------------------
// Always in the loop: the caller's own notes (/memories/history). Each person
// sees and changes only their own; the company retention is the owner's.
// ---------------------------------------------------------------------------

export type { HistoryNote, HistoryState } from "@/lib/history";

// null when this viewer has no notes to see (403: not signed in or not on the
// People list) or the backend predates it (404).
export async function getHistory(query?: string, signal?: AbortSignal): Promise<HistoryState | null> {
  const q = query?.trim() ? `?q=${encodeURIComponent(query.trim())}` : "";
  const res = await fetch(`${API_BASE}/memories/history${q}`, { signal });
  if (res.status === 403 || res.status === 404) return null;
  if (!res.ok) throw await delegationError(res, "Couldn't load your notes.");
  return res.json();
}

export async function updateHistorySettings(patch: {
  reply_notes?: boolean;
  retention_days?: number | null;
  company_retention_days?: number | null;
  share_work_style?: boolean;
}): Promise<HistoryState> {
  const res = await fetch(`${API_BASE}/memories/history/settings`, {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(patch),
  });
  if (!res.ok) throw await delegationError(res, "Couldn't save the setting.");
  return res.json();
}

/** Pin or unpin, or correct it ("" clears the correction). */
export async function updateHistoryNote(
  id: number,
  patch: { pinned?: boolean; correction?: string },
): Promise<HistoryNote> {
  const res = await fetch(`${API_BASE}/memories/history/${id}`, {
    method: "PATCH",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(patch),
  });
  if (!res.ok) throw await delegationError(res, "Couldn't change the note.");
  return res.json();
}

export async function forgetHistoryNote(id: number): Promise<void> {
  const res = await fetch(`${API_BASE}/memories/history/${id}`, { method: "DELETE" });
  if (!res.ok) throw await delegationError(res, "Couldn't forget the note.");
}

/** "Don't remember this": forgets every note from that note's conversation,
 * and nothing from it is noted again. Answers how many were forgotten. */
export async function forgetHistoryConversation(id: number): Promise<number> {
  const res = await fetch(`${API_BASE}/memories/history/${id}/forget-conversation`, { method: "POST" });
  if (!res.ok) throw await delegationError(res, "Couldn't forget the conversation.");
  const body = (await res.json()) as { forgotten?: number };
  return body.forgotten ?? 0;
}

// --- Reflection (the Learning screen): memory/chat_review grading --------

export interface ReflectionMiss {
  id: number;
  session_id: string;
  /** The saved reply's message id, when it is still in the chat. */
  message_id: number | null;
  person_id: number;
  person_name: string;
  created_at: string;
  /** The person's own words that turn. */
  message: string;
  reply: string;
  tools: string[];
  /** What they wanted instead, in the Executive's words, backed by theirs. */
  wanted: string;
  /** `company`: something only this workspace knows would have fixed it;
   * `product`: it couldn't have done it with what it has. */
  kind: "company" | "product";
  /** The finer reason within the kind: `term`, `fact`, `preference`,
   * `specialist`, `do_it` (company) or `tool`, `cant` (product); null on a
   * miss graded before causes, or when the grader gave none. */
  cause: string | null;
  signals: string[];
  /** How its nightly replays went: "open" until one passes, "closed" (it
   * would go right today), "evidence" (depends on what that day held). */
  replay_state: "open" | "closed" | "evidence";
  replayed_at: string | null;
  closed_at: string | null;
  replay_notes: string;
}

/** "Of the N things that went wrong in the last 30 days, M would go right today." */
export interface ReflectionReplay {
  misses: number;
  would_pass: number;
  evidence: number;
  last_run_at: string | null;
}

export interface ReflectionWeek {
  /** ISO week, e.g. "2026-W42". */
  week: string;
  graded: number;
  misses: number;
}

/** One thing the workspace asked for differently, learned from a miss. */
export interface ReflectionLesson {
  id: number;
  person_id: number;
  person_name: string;
  text: string;
  /** The person's words it came from. */
  quote: string;
  session_id: string;
  /** Learned in a channel or group chat: the owner's shared lessons reach everyone's chats. */
  shared: boolean;
  created_at: string;
  retired_at: string | null;
  /** "unhelpful" (the turns it reached went worse), "forgotten", "room", or
   * "replay" (its miss still failed when replayed, or it broke a turn that was fine). */
  retired_reason: "unhelpful" | "forgotten" | "room" | "replay" | null;
  /** How many turns it reached, and how those were then graded. */
  shown: number;
  fine_after: number;
  miss_after: number;
}

export interface ReflectionState {
  misses: ReflectionMiss[];
  /** Live lessons first, newest first, then the retired ones. */
  lessons: ReflectionLesson[];
  /** Newest week first. */
  weeks: ReflectionWeek[];
  replay: ReflectionReplay;
  /** The principal also sees shared chats' misses; a teammate their own only. */
  sees_everyone: boolean;
}

/** The caller's misses and weekly counts; null when there is nothing for
 * them here (not signed in, not on the roster). */
export async function getReflection(signal?: AbortSignal): Promise<ReflectionState | null> {
  const res = await fetch(`${API_BASE}/memories/reflection`, { signal });
  if (res.status === 403 || res.status === 404) return null;
  if (!res.ok) throw await delegationError(res, "Couldn't load Learning.");
  return res.json();
}

/** `keepalive` lets the request finish while the page is closing. */
export async function forgetReflectionMiss(id: number, opts: { keepalive?: boolean } = {}): Promise<void> {
  const res = await fetch(`${API_BASE}/memories/reflection/misses/${id}`, {
    method: "DELETE",
    keepalive: opts.keepalive,
  });
  if (!res.ok) throw await delegationError(res, "Couldn't forget it.");
}

/** `keepalive` lets the request finish while the page is closing. */
export async function forgetReflectionLesson(id: number, opts: { keepalive?: boolean } = {}): Promise<void> {
  const res = await fetch(`${API_BASE}/memories/reflection/lessons/${id}`, {
    method: "DELETE",
    keepalive: opts.keepalive,
  });
  if (!res.ok) throw await delegationError(res, "Couldn't forget it.");
}

export async function setDelegationEnabled(enabled: boolean): Promise<DelegationSettings> {
  const res = await fetch(`${API_BASE}/delegation`, {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ enabled }),
  });
  if (!res.ok) throw await delegationError(res, "Couldn't change Act as me.");
  delegationChanged();
  return res.json();
}

export async function setDelegationTeam(enabled: boolean): Promise<DelegationSettings> {
  const res = await fetch(`${API_BASE}/delegation/team`, {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ enabled }),
  });
  if (!res.ok) throw await delegationError(res, "Couldn't change Act as me for your team.");
  delegationChanged();
  return res.json();
}

export async function setInboxWatch(
  update: { enabled?: boolean; mailbox_drafts?: boolean },
): Promise<DelegationSettings> {
  const res = await fetch(`${API_BASE}/delegation/inbox`, {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(update),
  });
  if (!res.ok) throw await delegationError(res, "Couldn't change Draft replies to my inbox.");
  delegationChanged();
  return res.json();
}

// Change a waiting reply's words before Send: on its card, and in your
// mailbox's Drafts when it's there too. Sends nothing.
export async function editReplyText(id: number, text: string): Promise<ReplyCard> {
  const res = await fetch(`${API_BASE}/delegation/replies/${id}/text`, {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ text }),
  });
  if (!res.ok) throw await delegationError(res, "Couldn't save your change.");
  return (await res.json()) as ReplyCard;
}

// Send a waiting reply to the sender only, or to everyone the email went
// to: on its card, and in your mailbox's Drafts when it's there too.
export async function setReplyRecipients(id: number, everyone: boolean): Promise<ReplyCard> {
  const res = await fetch(`${API_BASE}/delegation/replies/${id}/recipients`, {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ everyone }),
  });
  if (!res.ok) throw await delegationError(res, "Couldn't change who it goes to.");
  return (await res.json()) as ReplyCard;
}

// Answer what a reply left you to decide: the draft is rewritten with it
// in your voice and saved on its card (and in your Drafts when it's there).
export async function answerReplyQuestions(
  id: number,
  answers: { question_index: number; answer_text: string }[],
): Promise<ReplyCard> {
  const res = await fetch(`${API_BASE}/delegation/replies/${id}/answer`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ answers }),
  });
  if (!res.ok) throw await delegationError(res, "Couldn't add that to your reply.");
  return (await res.json()) as ReplyCard;
}

// Change the reply the way you say, in your own words: the Executive
// rewrites it and says what it changed (POST .../change). Sends nothing.
export async function changeReply(id: number, text: string): Promise<ReplyCard> {
  const res = await fetch(`${API_BASE}/delegation/replies/${id}/change`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ text }),
  });
  if (!res.ok) throw await delegationError(res, "Couldn't change your reply.");
  return (await res.json()) as ReplyCard;
}

// Forget one thing it learned in training: it asks again from now on.
export async function removeTrainingLearned(id: number): Promise<DelegationSettings> {
  const res = await fetch(`${API_BASE}/delegation/learned/${id}`, { method: "DELETE" });
  if (!res.ok) throw await delegationError(res, "Couldn't remove that.");
  delegationChanged();
  return (await res.json()) as DelegationSettings;
}

// Put Act as me's settings in or out of training.
export async function setTraining(
  update: Partial<Record<TrainingSetting | "actions_on", boolean>>,
): Promise<DelegationSettings> {
  const res = await fetch(`${API_BASE}/delegation/training`, {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(update),
  });
  if (!res.ok) throw await delegationError(res, "Couldn't change training.");
  delegationChanged();
  return (await res.json()) as DelegationSettings;
}

export async function setReadMyCalendar(enabled: boolean): Promise<DelegationSettings> {
  const res = await fetch(`${API_BASE}/delegation/calendar`, {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ enabled }),
  });
  if (!res.ok) throw await delegationError(res, "Couldn't change Read my calendar.");
  return res.json();
}

export async function setReplyDisclosure(update: {
  handle_it?: boolean;
  approved_sends?: boolean;
}): Promise<DelegationSettings> {
  const res = await fetch(`${API_BASE}/delegation/disclosure`, {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(update),
  });
  if (!res.ok) throw await delegationError(res, "Couldn't change the AI line on your replies.");
  return res.json();
}

export async function setHandleIt(update: {
  enabled?: boolean;
  mode?: HandleItMode;
}): Promise<DelegationSettings> {
  const res = await fetch(`${API_BASE}/delegation/handle-it`, {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(update),
  });
  if (!res.ok) throw await delegationError(res, "Couldn't change Handle it for me.");
  delegationChanged();
  return res.json();
}

// null when this viewer has none to see (403) or the backend predates it (404).
export async function getHandledReplies(signal?: AbortSignal): Promise<HandledReply[] | null> {
  const res = await fetch(`${API_BASE}/delegation/handled`, { signal });
  if (res.status === 403 || res.status === 404) return null;
  if (!res.ok) throw await delegationError(res, "Couldn't load what it handled for you.");
  const body = (await res.json()) as { replies: HandledReply[] };
  return body.replies;
}

// Starts a check of your inbox; GET /delegation says when it is done.
export async function checkInboxNow(): Promise<InboxWatch> {
  const res = await fetch(`${API_BASE}/delegation/inbox/check`, { method: "POST" });
  if (!res.ok) throw await delegationError(res, "Couldn't check your inbox.");
  return res.json();
}

// null when this viewer has none to see (403) or the backend predates them (404).
export async function getReplyCards(signal?: AbortSignal): Promise<ReplyCard[] | null> {
  const res = await fetch(`${API_BASE}/delegation/replies`, { signal });
  if (res.status === 403 || res.status === 404) return null;
  if (!res.ok) throw await delegationError(res, "Couldn't load the replies waiting for you.");
  const body = (await res.json()) as { cards: ReplyCard[] };
  return body.cards;
}

// One email in your own mailbox, as Right now opens it (GET /delegation/mail).
export interface MailView {
  thread_id: string;
  message_id: string;
  subject: string;
  from_name: string;
  from_email: string;
  to: string[];
  cc: string[];
  received_at: string;
  text: string;
  attachments: { name: string; mime_type: string; size: number }[];
  has_attachments: boolean;
  their_last_words: string;
  link: string;
  reply_card_id: number | null;
}

export async function getMail(threadId: string, messageId: string, signal?: AbortSignal): Promise<MailView> {
  const q = new URLSearchParams({ thread_id: threadId, message_id: messageId });
  const res = await fetch(`${API_BASE}/delegation/mail?${q}`, { signal });
  if (!res.ok) throw await delegationError(res, "Couldn't open that email.");
  return (await res.json()) as MailView;
}

// A reply to one email, on a card for you (the conversation's open card
// when there is one). Sends nothing.
export async function replyToMail(threadId: string, messageId: string): Promise<number> {
  const res = await fetch(`${API_BASE}/delegation/mail/reply`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ thread_id: threadId, message_id: messageId }),
  });
  if (!res.ok) throw await delegationError(res, "Couldn't write that reply.");
  return ((await res.json()) as { decision_id: number }).decision_id;
}

// Why a Send didn't go: the backend's code (draft_gone, you_replied,
// already_handled, send_unconfirmed, caller_signing_required, …) and what to
// tell you.
export class ReplySendError extends Error {
  code: string;
  constructor(message: string, code: string) {
    super(message);
    this.code = code;
  }
}

export type SendReplyResult =
  | { status: "sent" }
  // Something changed since the card was made: send again with what you
  // were shown to go ahead.
  | { status: "confirm"; message: string; reasons: string[]; recipients: string[] };

function strings(value: unknown): string[] {
  return Array.isArray(value) ? value.filter((v): v is string => typeof v === "string") : [];
}

// Send the reply's draft from your Gmail, exactly as it is there (POST
// /decisions/{id}/approve). `confirm` is your second yes: the recipients you
// were shown, and that a newer message in the thread is fine.
// `allow` is Send + allow in training: replies to this sender (follow-ups to
// these people) go on their own from now on; `example` keeps your sent
// version when you changed the draft (Drafts in training).
export async function sendReplyCard(
  id: number,
  confirm?: {
    recipients: string[];
    thread_moved_on?: boolean;
    allow?: boolean;
    example?: boolean;
    // The card's caught_up_at as shown: brought up to date since asks again.
    seen_caught_up_at?: string;
  },
): Promise<SendReplyResult> {
  const res = await fetch(`${API_BASE}/decisions/${id}/approve`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ edits: confirm ?? null }),
  });
  if (res.ok) return { status: "sent" };
  const body = (await res.json().catch(() => ({}))) as { detail?: unknown };
  const detail = (body.detail && typeof body.detail === "object" ? body.detail : {}) as Record<string, unknown>;
  const message = typeof detail.message === "string" ? detail.message : "Couldn't send that reply.";
  const code = typeof detail.code === "string" ? detail.code : res.status === 404 ? "draft_gone" : "error";
  if (res.status === 409 && code === "confirm") {
    return { status: "confirm", message, reasons: strings(detail.reasons), recipients: strings(detail.recipients) };
  }
  throw new ReplySendError(message, code);
}

// Send a draft the chat wrote as you, exactly as it was written (POST
// /delegation/drafts/{row}/send). `threadMovedOn` is your second yes when a
// newer message arrived in that conversation.
export async function sendChatDraft(row: number, threadMovedOn = false): Promise<SendReplyResult> {
  const res = await fetch(`${API_BASE}/delegation/drafts/${row}/send`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ thread_moved_on: threadMovedOn }),
  });
  if (res.ok) return { status: "sent" };
  const body = (await res.json().catch(() => ({}))) as { detail?: unknown };
  const detail = (body.detail && typeof body.detail === "object" ? body.detail : {}) as Record<string, unknown>;
  const message = typeof detail.message === "string" ? detail.message : "Couldn't send that email.";
  const code = typeof detail.code === "string" ? detail.code : "error";
  if (res.status === 409 && code === "confirm") {
    return { status: "confirm", message, reasons: strings(detail.reasons), recipients: strings(detail.recipients) };
  }
  throw new ReplySendError(message, code);
}

// A card of actions the Executive suggested from your email (Act as me),
// yours alone. Nothing on it happens until you approve it here: Approve
// (POST /decisions/{id}/approve) does the ticked actions exactly as shown;
// Dismiss (POST /decisions/{id}/reject) drops it.
export interface ActionCardAction {
  index: number;
  // invite, message, add_contact or drive_files.
  kind: string;
  summary: string;
  // A message's text as it will be sent, or a meeting's description.
  text: string;
}

export interface ActionCard {
  decision_id: number;
  status: string;
  created_at: string;
  why: string;
  actions: ActionCardAction[];
  // In training: Approve + allow is offered.
  can_allow?: boolean;
}

// What happened to one action: done, waiting (sent to whoever approves
// meetings), failed or skipped (you unticked it).
export interface ActionCardResult {
  index: number;
  status: string;
  detail: string;
}

// null when this viewer has none to see (403) or the backend predates them (404).
export async function getActionCards(signal?: AbortSignal): Promise<ActionCard[] | null> {
  const res = await fetch(`${API_BASE}/delegation/actions`, { signal });
  if (res.status === 403 || res.status === 404) return null;
  if (!res.ok) throw await delegationError(res, "Couldn't load the cards waiting for you.");
  const body = (await res.json()) as { cards: ActionCard[] };
  return body.cards;
}

// Do the ticked actions (`only`, by index) of an action card. Returns what
// happened to each. `allow` is Approve + allow (Suggested actions in
// training): the same kind, with the same people, happens on its own from now on.
export async function approveActionCard(id: number, only: number[], allow = false): Promise<ActionCardResult[]> {
  const res = await fetch(`${API_BASE}/decisions/${id}/approve`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ edits: allow ? { only, allow: true } : { only } }),
  });
  if (!res.ok) throw await delegationError(res, "Couldn't do that.");
  const body = (await res.json()) as { final_payload_json?: string | null };
  try {
    const payload = JSON.parse(body.final_payload_json ?? "{}") as { results?: ActionCardResult[] };
    return Array.isArray(payload.results) ? payload.results : [];
  } catch {
    return [];
  }
}

// A meeting invite from someone you know (Act as me, with Read my calendar
// on), yours alone. Accept and Decline answer it in your own calendar
// (POST /decisions/{id}/approve with edits.answer); Dismiss
// (POST /decisions/{id}/reject) answers nothing.
export interface InviteCard {
  decision_id: number;
  status: string;
  created_at: string;
  from_name: string;
  from_email: string;
  relation: string;
  title: string;
  // "Wed 21 Oct, 14:30–15:00", in your time zone.
  when: string;
  start: string;
  end: string;
  all_day: boolean;
  // Busy times on your calendar that overlap it; times only.
  clashes: string[];
  clash_checked: boolean;
  // false: your calendar sign-in can read but not answer invites yet.
  can_answer: boolean;
  // Replies in training: the "Accept from them on its own next time" tick.
  can_allow: boolean;
  // Why Handle it for me left it for you ("" when it was off).
  waited_because: string;
  connect_command: string;
}

// null when this viewer has none to see (403) or the backend predates them (404).
export async function getInviteCards(signal?: AbortSignal): Promise<InviteCard[] | null> {
  const res = await fetch(`${API_BASE}/delegation/invites`, { signal });
  if (res.status === 403 || res.status === 404) return null;
  if (!res.ok) throw await delegationError(res, "Couldn't load the invites waiting for you.");
  const body = (await res.json()) as { cards: InviteCard[] };
  return body.cards;
}

// Accept or decline an invite in your own calendar. `allow` (accept, Replies
// in training): their invites are accepted on their own from now on.
export async function answerInviteCard(id: number, answer: "accept" | "decline", allow = false): Promise<void> {
  const res = await fetch(`${API_BASE}/decisions/${id}/approve`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ edits: allow ? { answer, allow: true } : { answer } }),
  });
  if (!res.ok) throw await delegationError(res, "Couldn't answer that invite.");
}

export async function dismissInviteCard(id: number): Promise<void> {
  const res = await fetch(`${API_BASE}/decisions/${id}/reject`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ reason: "" }),
  });
  if (res.status === 404 || res.status === 409) return; // already gone or answered
  if (!res.ok) throw await delegationError(res, "Couldn't dismiss that invite.");
}

export async function dismissActionCard(id: number): Promise<void> {
  const res = await fetch(`${API_BASE}/decisions/${id}/reject`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ reason: "" }),
  });
  if (res.status === 404 || res.status === 409) return; // already gone or handled
  if (!res.ok) throw await delegationError(res, "Couldn't dismiss that card.");
}

// Dismiss a reply card. Its draft is deleted from your Gmail unless you
// edited it there.
export async function dismissReplyCard(id: number): Promise<void> {
  const res = await fetch(`${API_BASE}/decisions/${id}/reject`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ reason: "" }),
  });
  if (res.status === 404 || res.status === 409) return; // already gone or handled
  if (!res.ok) throw await delegationError(res, "Couldn't dismiss that reply.");
}

export async function getVoiceProfile(signal?: AbortSignal): Promise<VoiceProfile> {
  const res = await fetch(`${API_BASE}/delegation/voice`, { signal });
  if (!res.ok) throw await delegationError(res, "Couldn't load how you write.");
  return res.json();
}

export async function learnVoiceProfile(): Promise<VoiceProfile> {
  const res = await fetch(`${API_BASE}/delegation/voice/learn`, { method: "POST" });
  if (!res.ok) throw await delegationError(res, "Couldn't learn how you write.");
  return res.json();
}

export async function updateVoiceProfile(update: VoiceUpdate): Promise<VoiceProfile> {
  const res = await fetch(`${API_BASE}/delegation/voice`, {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(update),
  });
  if (!res.ok) throw await delegationError(res, "Couldn't save how you write.");
  return res.json();
}

export async function describeVoiceProfile(description: string): Promise<DescribedVoice> {
  const res = await fetch(`${API_BASE}/delegation/voice/describe`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ description }),
  });
  if (!res.ok) throw await delegationError(res, "Couldn't write your style. Try again.");
  return res.json();
}

// Takes the signature from your Gmail settings again; nothing else changes.
export async function refreshVoiceSignature(): Promise<VoiceProfile> {
  const res = await fetch(`${API_BASE}/delegation/voice/signature`, { method: "POST" });
  if (!res.ok) throw await delegationError(res, "Couldn't read your Gmail signature.");
  return res.json();
}

export async function resetVoiceProfile(): Promise<VoiceProfile> {
  const res = await fetch(`${API_BASE}/delegation/voice`, { method: "DELETE" });
  if (!res.ok) throw await delegationError(res, "Couldn't reset how you write.");
  return res.json();
}

// ----------------------------------------------------------------------------
// Decision classes — whether the Executive acts on a class of decision on its
// own ("auto_execute") or proposes it for approval first ("propose").
// ----------------------------------------------------------------------------

export type DecisionClassMode = "propose" | "auto_execute";

export interface DecisionClassSetting {
  decision_class: string;
  mode: DecisionClassMode;
}

// The class behind "Meetings asked for in chat" in Take the lead's Always asks first.
export const MEETING_SCHEDULING_CLASS = "meeting_scheduling";

/** The class's mode, or null when this backend has no setting for it (404). */
export async function getDecisionClassMode(
  decisionClass: string,
  signal?: AbortSignal,
): Promise<DecisionClassSetting | null> {
  const res = await fetch(
    `${API_BASE}/decisions/classes/${encodeURIComponent(decisionClass)}`,
    { signal },
  );
  if (res.status === 404) return null;
  if (!res.ok) throw new Error("Failed to load the setting");
  return res.json();
}

export async function setDecisionClassMode(
  decisionClass: string,
  mode: DecisionClassMode,
): Promise<DecisionClassSetting> {
  const res = await fetch(`${API_BASE}/decisions/classes/${encodeURIComponent(decisionClass)}`, {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ mode }),
  });
  if (res.status === 403) throw new Error("Only the principal can change this setting.");
  // 409: auto-booking can't be turned on before a principal exists; the
  // backend's detail says so in plain words.
  if (res.status === 409) throw await onboardError(res, "This setting can't be turned on yet.");
  if (!res.ok) throw new Error("Failed to save the setting");
  return res.json();
}

// ----------------------------------------------------------------------------
// Workflows
// ----------------------------------------------------------------------------

export interface WorkflowStepDef {
  id: string;
  title: string;
  description: string;
}

export interface WorkflowInputFieldSchema {
  type?: string;
  title?: string;
  description?: string;
  default?: unknown;
  examples?: unknown[];
  minLength?: number;
  enum?: string[];
}

export interface WorkflowJsonSchema {
  title?: string;
  type?: string;
  properties?: Record<string, WorkflowInputFieldSchema>;
  required?: string[];
}

export type WorkflowSection =
  | "Board"
  | "Capital & Investors"
  | "Growth & GTM"
  | "Product"
  | "People"
  | "Risk, Legal & Crisis"
  | "Operating Cadence";

export interface WorkflowMeta {
  name: string;
  title: string;
  description: string;
  section: WorkflowSection;
  estimated_minutes: number;
  input_schema: WorkflowJsonSchema;
  steps: WorkflowStepDef[];
  is_custom?: boolean;
  // Run by the system itself (scheduler, onboarding, reflection); the catalog
  // files these under "System".
  background?: boolean;
  /** Playbooks (skills) this workflow's steps follow: its "How it's done". */
  playbooks?: string[];
  /** One field, one document drafted by following a playbook nothing else follows. */
  quick?: boolean;
}

// ---- User-created (dynamic) workflows ----

export interface DynamicInputField {
  name: string;
  label: string;
  description?: string;
  required: boolean;
  multiline: boolean;
}

export type DynamicStep =
  | {
      kind: "specialist";
      id: string;
      title: string;
      description?: string;
      specialist: string;
      goal: string;
      rag_query?: string;
      /** Name of a playbook (skill) the step follows. */
      playbook?: string;
    }
  | {
      kind: "approval_gate";
      id: string;
      title: string;
      description?: string;
      person_id: number;
      question: string;
      timeout_hours?: number;
      on_timeout?: "escalate" | "auto_proceed" | "fail";
      // Anything but approve_reject is a question, not permission: the run
      // continues whatever the answer.
      expected_reply_shape?: "approve_reject" | "free_text" | "numeric" | "document";
    }
  | {
      kind: "synthesis";
      id: string;
      title: string;
      description?: string;
      instructions?: string;
      specialist?: string;
    }
  | {
      // Gets something done with tools. `tools` is the exact allowlist the
      // user approves when they create the workflow (or turn it on).
      kind: "action";
      id: string;
      title: string;
      description?: string;
      goal: string;
      tools: string[];
      max_tool_calls?: number;
    };

export interface DynamicWorkflowDef {
  name: string;
  title: string;
  description?: string;
  section: WorkflowSection;
  estimated_minutes: number;
  input_fields: DynamicInputField[];
  steps: DynamicStep[];
  cadence?: string | null;
  cadence_person_id?: number | null;
  is_active?: boolean;
  created_at?: string;
  updated_at?: string;
  // Who created it (server-managed; echoing it back in a body has no effect).
  // Asked to approve the workflow's first write to a new target.
  owner_person_id?: number | null;
}

// The specialists a dynamic step may consult (matches SPECIALIST_REGISTRY,
// excluding the internal `triage` router).
export const DYNAMIC_SPECIALISTS = [
  "cso",
  "cfo",
  "chro",
  "gc",
  "coo",
  "cmo",
  "cpo",
  "sales",
  "board_comms",
] as const;

export async function listCustomWorkflows(): Promise<DynamicWorkflowDef[]> {
  const res = await fetch(`${API_BASE}/workflows/custom`);
  if (!res.ok) throw new Error("Failed to list custom workflows");
  const data = await res.json();
  return data.definitions;
}

export async function getCustomWorkflow(name: string): Promise<DynamicWorkflowDef> {
  const res = await fetch(`${API_BASE}/workflows/custom/${encodeURIComponent(name)}`);
  if (!res.ok) throw new Error("Failed to load custom workflow");
  return res.json();
}

/** An error from the custom-workflow endpoints, carrying the HTTP status. */
export class CustomWorkflowError extends Error {
  constructor(message: string, readonly status: number) {
    super(message);
  }
}

/** The server's error detail; a 422's validation-error array is joined. */
async function _customError(res: Response): Promise<CustomWorkflowError> {
  let detail: unknown = res.statusText;
  try {
    detail = (await res.json()).detail;
  } catch {
    /* keep statusText */
  }
  const msg = Array.isArray(detail) ? detail.join("; ") : String(detail);
  return new CustomWorkflowError(msg, res.status);
}

/** Returns the server's validation errors (array) when the response is 422. */
async function _writeCustom(
  url: string,
  method: "POST" | "PUT",
  def: DynamicWorkflowDef
): Promise<DynamicWorkflowDef> {
  const res = await fetch(url, {
    method,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(def),
  });
  if (!res.ok) throw await _customError(res);
  return res.json();
}

export function createCustomWorkflow(def: DynamicWorkflowDef): Promise<DynamicWorkflowDef> {
  return _writeCustom(`${API_BASE}/workflows/custom`, "POST", def);
}

export function updateCustomWorkflow(
  name: string,
  def: DynamicWorkflowDef
): Promise<DynamicWorkflowDef> {
  return _writeCustom(`${API_BASE}/workflows/custom/${encodeURIComponent(name)}`, "PUT", def);
}

/**
 * Turn a custom workflow on — the approval for one chat saved switched off.
 * `reviewed` is the definition the user was shown; the server refuses (409)
 * if the stored one has changed since, so only what was seen gets switched on.
 */
export async function activateCustomWorkflow(
  reviewed: DynamicWorkflowDef
): Promise<DynamicWorkflowDef> {
  const res = await fetch(
    `${API_BASE}/workflows/custom/${encodeURIComponent(reviewed.name)}/activate`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ is_active: true, definition: reviewed }),
    }
  );
  if (!res.ok) throw await _customError(res);
  return res.json();
}

/**
 * Save the draft of a conversation that edits a saved workflow. The server
 * saves its own copy of the draft, and only if it is `reviewed` (the draft on
 * screen) and the workflow has not changed since the conversation opened
 * (409 otherwise).
 */
export async function saveWorkflowDesignerEdit(
  sessionId: string,
  reviewed: DynamicWorkflowDef
): Promise<DynamicWorkflowDef> {
  const name = reviewed.name;
  const res = await fetch(
    `${API_BASE}/workflows/custom/${encodeURIComponent(name)}/save-edit`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ session_id: sessionId, definition: reviewed }),
    }
  );
  if (!res.ok) throw await _customError(res);
  return res.json();
}

/** A target a workflow's tool steps may write to without asking again. */
export interface ApprovedTarget {
  value: string;
  key: string;
  approved_at: string;
  run_id: string;
}

export async function listApprovedTargets(name: string): Promise<ApprovedTarget[]> {
  const res = await fetch(`${API_BASE}/workflows/custom/${encodeURIComponent(name)}/targets`);
  if (!res.ok) throw await _customError(res);
  return (await res.json()).targets;
}

export async function forgetApprovedTarget(name: string, value: string): Promise<void> {
  const res = await fetch(
    `${API_BASE}/workflows/custom/${encodeURIComponent(name)}/targets?value=${encodeURIComponent(value)}`,
    { method: "DELETE" }
  );
  if (!res.ok) throw await _customError(res);
}

export async function deleteCustomWorkflow(name: string): Promise<void> {
  const res = await fetch(`${API_BASE}/workflows/custom/${encodeURIComponent(name)}`, {
    method: "DELETE",
  });
  if (!res.ok) throw new Error("Failed to delete custom workflow");
}

// ---- Tools a workflow action step can use ----

export interface WorkflowToolInfo {
  name: string;
  description: string;
  // true = only reads; null = may change something (can't tell from the name)
  read_only: boolean | null;
  source: "mcp" | "builtin";
}

export async function searchWorkflowTools(q: string): Promise<WorkflowToolInfo[]> {
  const res = await fetch(
    `${API_BASE}/workflows/tools/search?q=${encodeURIComponent(q)}`
  );
  if (!res.ok) throw new Error("Tool search failed");
  return (await res.json()).tools;
}

export async function describeWorkflowTools(
  names: string[]
): Promise<WorkflowToolInfo[]> {
  if (names.length === 0) return [];
  const res = await fetch(
    `${API_BASE}/workflows/tools/describe?names=${encodeURIComponent(names.join(","))}`
  );
  if (!res.ok) throw new Error("Tool lookup failed");
  return (await res.json()).tools;
}

// ---- Conversational workflow designer (/jobs/new wizard) ----

export interface WorkflowDesignerDraft {
  // Exactly the body POST /workflows/custom takes.
  definition: DynamicWorkflowDef;
  summary: string;
  assumptions: string[];
}

export interface WorkflowDesignerTurn {
  session_id: string;
  phase: "question" | "draft";
  questions_asked: number;
  max_questions: number;
  question: string | null;
  hint: string | null;
  options: string[];
  draft: WorkflowDesignerDraft | null;
  transcript: { role: "user" | "assistant"; text: string }[];
  // Set when the session changes a saved workflow: its name, and the saved
  // version the draft is compared with. Save with updateCustomWorkflow.
  editing?: string | null;
  original?: DynamicWorkflowDef | null;
}

async function _designerPost(
  path: string,
  body: Record<string, string>,
  fallback: string
): Promise<WorkflowDesignerTurn> {
  const res = await fetch(`${API_BASE}/workflows/designer/${path}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });
  if (!res.ok) throw await onboardError(res, fallback);
  return res.json();
}

export function startWorkflowDesigner(message: string): Promise<WorkflowDesignerTurn> {
  return _designerPost("start", { message }, "Could not start the workflow assistant");
}

/** Open the designer on a saved workflow, to change it by conversation. */
export function editWorkflowWithDesigner(name: string): Promise<WorkflowDesignerTurn> {
  return _designerPost("edit", { name }, "Could not open that workflow");
}

export function sendWorkflowDesignerMessage(
  sessionId: string,
  message: string
): Promise<WorkflowDesignerTurn> {
  return _designerPost(
    "message",
    { session_id: sessionId, message },
    "Could not send that message"
  );
}

export function forceWorkflowDesignerDraft(sessionId: string): Promise<WorkflowDesignerTurn> {
  return _designerPost("draft", { session_id: sessionId }, "Could not draft the workflow");
}

export async function getWorkflowDesignerSession(
  sessionId: string
): Promise<WorkflowDesignerTurn> {
  const res = await fetch(
    `${API_BASE}/workflows/designer/${encodeURIComponent(sessionId)}`
  );
  if (!res.ok) throw await onboardError(res, "That workflow draft has expired");
  return res.json();
}

export interface WorkflowSample {
  workflow: string;
  inputs: Record<string, unknown>;
}

/** Every status `workflow_runs.status` can hold. `awaiting_human`, `resolved`
 *  and `timed_out` have been served for a while; the union only ever listed
 *  three, so the others reached the UI as unhandled strings. */
export type WorkflowRunStatus =
  | "running"
  | "done"
  | "error"
  | "awaiting_human"
  | "resolved"
  | "timed_out";

/** Statuses the run will not move on from by itself. Anything else means a
 *  poll is worth repeating: `running` is working, `awaiting_human` is waiting
 *  on a person, and `resolved` is queued for the resumer to pick up. */
export const TERMINAL_RUN_STATUSES: ReadonlySet<WorkflowRunStatus> = new Set([
  "done",
  "error",
  "timed_out",
]);

/** How the gate's question actually reached the approver. Anything other than
 *  `sent` or `self` means nobody was asked, and the UI must not imply
 *  otherwise. */
export type GateDelivery = "self" | "sent" | "suppressed" | "alerted" | "failed";

export interface WorkflowRunSummary {
  run_id: string;
  workflow_name: string;
  title: string;
  status: WorkflowRunStatus;
  created_at: string;
  updated_at: string;
}

/** Which steps a paused run already finished. The server sends this in place
 *  of the raw resume payload, which carries every completed step's full text
 *  and would otherwise ride on every poll. */
export interface ResumeProgress {
  gate_step_id: string;
  completed_step_ids: string[];
}

export interface WorkflowRunDetail extends WorkflowRunSummary {
  inputs: Record<string, unknown>;
  artifact: string | null;
  error: string | null;
  // Checkpoint columns the run record has always carried; the detail route
  // returns the whole row, so these were already on the wire untyped.
  awaiting_person_id?: number | null;
  awaiting_until?: string | null;
  state_json?: string | null;
  resolution_json?: string | null;
  resume_progress?: ResumeProgress | null;
  // A failed scheduled run that Run again can queue.
  rerunnable?: boolean;
}

/** The serialized gate in `state_json`, for rendering what a paused run is
 *  waiting on. Every field is optional: older checkpoints predate some of
 *  them, which is exactly how the server tells legacy rows apart. */
export interface GateState {
  question?: string;
  person_id?: number;
  expected_reply_shape?: string;
  delivery?: GateDelivery;
  channel?: string;
}

export interface WorkflowEvent {
  type:
    | "run_created"
    | "step_start"
    | "step_done"
    // A running step reports activity (an action step using a tool).
    | "progress"
    | "result"
    | "artifact"
    | "done"
    | "error"
    | "awaiting_human";
  run_id?: string;
  title?: string;
  workflow?: string;
  step_id?: string;
  step_title?: string;
  summary?: string;
  content?: string;
  sources?: string[];
  message?: string;
  steps?: WorkflowStepDef[];
  /** `result` events only. */
  data?: Record<string, unknown>;
  // `awaiting_human` only. A paused run emits NO `done` or `error` — this
  // frame is the last one, which `terminal` says explicitly so a client
  // doesn't sit waiting for an end that never comes.
  person_id?: number;
  question?: string;
  awaiting_until?: string;
  delivery?: GateDelivery;
  resumable?: boolean;
  terminal?: boolean;
}

export async function listWorkflows(): Promise<WorkflowMeta[]> {
  const res = await fetch(`${API_BASE}/workflows`);
  if (!res.ok) throw new Error("Failed to list workflows");
  const data = await res.json();
  return data.workflows;
}

export async function getWorkflow(name: string): Promise<WorkflowMeta> {
  const res = await fetch(`${API_BASE}/workflows/${encodeURIComponent(name)}`);
  if (!res.ok) throw new Error("Failed to load workflow");
  return res.json();
}

export async function getWorkflowSample(name: string): Promise<WorkflowSample> {
  const res = await fetch(`${API_BASE}/workflows/${encodeURIComponent(name)}/sample`);
  if (!res.ok) throw new Error("Failed to load workflow sample");
  return res.json();
}

export async function listWorkflowRuns(
  workflowName?: string
): Promise<WorkflowRunSummary[]> {
  const params = new URLSearchParams();
  if (workflowName) params.set("workflow", workflowName);
  const res = await fetch(`${API_BASE}/workflows/runs?${params.toString()}`);
  if (!res.ok) throw new Error("Failed to list workflow runs");
  const data = await res.json();
  return data.runs;
}

/** Answer a run waiting on a yes/no sign-off (the person asked, or the principal). */
export async function decideWorkflowRun(
  runId: string,
  decision: "approve" | "reject"
): Promise<void> {
  const res = await fetch(`${API_BASE}/workflows/runs/${encodeURIComponent(runId)}/decision`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ decision }),
  });
  if (!res.ok) throw await _customError(res);
}

export async function getWorkflowRun(runId: string): Promise<WorkflowRunDetail> {
  const res = await fetch(`${API_BASE}/workflows/runs/${encodeURIComponent(runId)}`);
  if (!res.ok) throw new Error("Failed to load workflow run");
  return res.json();
}

export async function deleteWorkflowRun(runId: string): Promise<void> {
  const res = await fetch(`${API_BASE}/workflows/runs/${encodeURIComponent(runId)}`, {
    method: "DELETE",
  });
  if (!res.ok) throw new Error("Failed to delete workflow run");
}

// ---------------------------------------------------------------------------
// Executive Artifacts — unified read-only view over drafted artifacts
// (alerts, source='artifact') + completed workflow run outputs.
// ---------------------------------------------------------------------------

// Keep in sync with the Pydantic models in
// packages/core/openexecutive/api/routes/artifacts.py (ArtifactSummary / ArtifactDetail).
export interface ArtifactSummary {
  id: string; // composite "alert:<id>" | "run:<hex>"
  kind: "draft" | "workflow";
  title: string;
  source_label: string;
  created_at: string;
  preview: string | null;
  status: string;
  severity: string | null;
  archived_at: string | null; // ISO ts when archived; null = active
  // Registered format — see packages/core/openexecutive/orchestrator/artifact_formats.py.
  format: ArtifactFormat;
  format_label: string;
  // Download targets; the first is the artifact's own file. Empty for links.
  downloads: ArtifactFormat[];
  external_url: string | null;
  link_label: string | null;
  supersedes_id: string | null; // id of the earlier version this revised
  // An installed extension's kind of document, with its own filter
  // (packages/core/openexecutive/orchestrator/extensions.py).
  collection?: string | null;
  collection_label?: string | null;
}

export type ArtifactFormat = "docx" | "html" | "link" | "markdown" | "xlsx";

export const ARTIFACT_EXTENSIONS: Record<ArtifactFormat, string | null> = {
  docx: "docx",
  html: "html",
  link: null,
  markdown: "md",
  xlsx: "xlsx",
};

export interface ArtifactDetail extends ArtifactSummary {
  // Sanitized HTML for "html"; Markdown for every other format.
  body: string;
  rationale: string | null;
}

// Same-origin proxy URL, so a plain <a href> download carries the session.
export function artifactDownloadUrl(id: string, as?: ArtifactFormat): string {
  const qs = as ? `?as=${encodeURIComponent(as)}` : "";
  return `${API_BASE}/artifacts/${encodeURIComponent(id)}/download${qs}`;
}

export async function listArtifacts(
  opts?: { archived?: boolean }
): Promise<ArtifactSummary[]> {
  const qs = opts?.archived ? "?archived=true" : "";
  const res = await fetch(`${API_BASE}/artifacts${qs}`);
  if (!res.ok) throw new Error("Failed to list artifacts");
  const data = await res.json();
  return data.artifacts;
}

export async function getArtifact(id: string): Promise<ArtifactDetail> {
  const res = await fetch(`${API_BASE}/artifacts/${encodeURIComponent(id)}`);
  if (!res.ok) throw new Error("Failed to load artifact");
  return res.json();
}

export async function archiveArtifact(id: string): Promise<void> {
  const res = await fetch(
    `${API_BASE}/artifacts/${encodeURIComponent(id)}/archive`,
    { method: "POST" }
  );
  if (!res.ok) throw new Error("Failed to archive artifact");
}

export async function restoreArtifact(id: string): Promise<void> {
  const res = await fetch(
    `${API_BASE}/artifacts/${encodeURIComponent(id)}/restore`,
    { method: "POST" }
  );
  if (!res.ok) throw new Error("Failed to restore artifact");
}

export async function deleteArtifact(id: string): Promise<void> {
  const res = await fetch(`${API_BASE}/artifacts/${encodeURIComponent(id)}`, {
    method: "DELETE",
  });
  if (!res.ok) throw new Error("Failed to delete artifact");
}

// ---------------------------------------------------------------------------
// SME Knowledge Review
// ---------------------------------------------------------------------------

export type ReviewStatus = "pending" | "approved" | "rejected" | "needs_revision";
// `failure` = shipped or user-authored failure case studies. They have their
// own id namespace (`failure:<domain>:<file>`) so a user upload can never
// collide with a shipped one.
export type ReviewContentType = "builtin" | "external" | "failure";
export type ReviewPriority = "low" | "normal" | "high";

export interface ReviewItem {
  item_id: string;
  content_type: ReviewContentType;
  domain: string;
  filename: string;
  status: ReviewStatus;
  priority: ReviewPriority;
  reviewer_notes: string;
  reviewed_at: string | null;
  /** True only for content that ships with the product, not a user upload. */
  trusted_default: boolean;
  registered_at: string;
  last_modified_at: string;
}

export interface ReviewAnnotation {
  annotation_id: string;
  item_id: string;
  domain: string;
  correction: string;
  is_active: boolean;
  created_at: string;
}

export interface ReviewItemDetail {
  item: ReviewItem;
  annotations: ReviewAnnotation[];
}

export interface ReviewStats {
  pending: number;
  approved: number;
  rejected: number;
  needs_revision: number;
  total: number;
}

export interface ReviewItemPatch {
  status?: ReviewStatus;
  priority?: ReviewPriority;
  reviewer_notes?: string;
}

export async function listReviewItems(params?: {
  status?: ReviewStatus;
  domain?: string;
  content_type?: ReviewContentType;
  limit?: number;
  offset?: number;
}): Promise<ReviewItem[]> {
  const p = new URLSearchParams();
  if (params?.status) p.set("status", params.status);
  if (params?.domain) p.set("domain", params.domain);
  if (params?.content_type) p.set("content_type", params.content_type);
  if (params?.limit != null) p.set("limit", String(params.limit));
  if (params?.offset != null) p.set("offset", String(params.offset));
  const qs = p.toString();
  const res = await fetch(`${API_BASE}/review/items${qs ? `?${qs}` : ""}`);
  if (!res.ok) throw new Error("Failed to list review items");
  return res.json();
}

export async function getReviewItem(itemId: string): Promise<ReviewItemDetail> {
  const res = await fetch(`${API_BASE}/review/items/${encodeURIComponent(itemId)}`);
  if (!res.ok) throw new Error("Failed to get review item");
  return res.json();
}

export async function getReviewStats(): Promise<ReviewStats> {
  const res = await fetch(`${API_BASE}/review/stats`);
  if (!res.ok) throw new Error("Failed to get review stats");
  return res.json();
}

export async function patchReviewItem(itemId: string, patch: ReviewItemPatch): Promise<ReviewItem> {
  const res = await fetch(`${API_BASE}/review/items/${encodeURIComponent(itemId)}`, {
    method: "PATCH",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(patch),
  });
  if (!res.ok) throw new Error("Failed to update review item");
  return res.json();
}

// A bulk approve must always carry a selector — the backend rejects a call
// with none, so clearing the whole queue is an explicit `all_pending` opt-in
// rather than an empty body.
export async function bulkApproveReviewItems(
  domain?: string,
): Promise<{ approved_count: number; item_ids: string[] }> {
  const res = await fetch(`${API_BASE}/review/bulk-approve`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(domain ? { domain } : { all_pending: true }),
  });
  if (!res.ok) throw new Error("Failed to bulk approve");
  return res.json();
}

export async function curateDomain(
  domain: string,
  action: "start" | "stop",
): Promise<{ domain: string; action: "start" | "stop"; affected_count: number }> {
  const res = await fetch(`${API_BASE}/review/curate`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ domain, action }),
  });
  if (!res.ok) throw new Error("Failed to update curation");
  return res.json();
}

/** Domain → count of shipped docs nobody has reviewed yet. */
export async function getTrustedDefaults(): Promise<Record<string, number>> {
  const res = await fetch(`${API_BASE}/review/trusted-defaults`);
  if (!res.ok) throw new Error("Failed to load trusted defaults");
  return res.json();
}

export async function listAllAnnotations(activeOnly = true): Promise<ReviewAnnotation[]> {
  const res = await fetch(`${API_BASE}/review/annotations?active_only=${activeOnly}`);
  if (!res.ok) throw new Error("Failed to list annotations");
  return res.json();
}

export async function listItemAnnotations(itemId: string): Promise<ReviewAnnotation[]> {
  const res = await fetch(`${API_BASE}/review/items/${encodeURIComponent(itemId)}/annotations`);
  if (!res.ok) throw new Error("Failed to list annotations");
  return res.json();
}

export async function addAnnotation(itemId: string, correction: string): Promise<ReviewAnnotation> {
  const res = await fetch(`${API_BASE}/review/items/${encodeURIComponent(itemId)}/annotations`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ correction }),
  });
  if (!res.ok) throw new Error("Failed to add annotation");
  return res.json();
}

export async function patchAnnotation(
  annotationId: string,
  patch: { correction?: string; is_active?: boolean }
): Promise<void> {
  const res = await fetch(`${API_BASE}/review/annotations/${encodeURIComponent(annotationId)}`, {
    method: "PATCH",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(patch),
  });
  if (!res.ok) throw new Error("Failed to update annotation");
}

export async function deleteAnnotation(annotationId: string): Promise<void> {
  const res = await fetch(`${API_BASE}/review/annotations/${encodeURIComponent(annotationId)}`, {
    method: "DELETE",
  });
  if (!res.ok) throw new Error("Failed to delete annotation");
}

export async function* runWorkflow(
  name: string,
  inputs: Record<string, unknown>
): AsyncGenerator<WorkflowEvent> {
  const response = await fetch(
    `${API_BASE}/workflows/${encodeURIComponent(name)}/runs`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(inputs),
    }
  );

  if (!response.ok) {
    let detail = response.statusText;
    let refusal: string | null = null;
    try {
      const body = await response.json();
      detail = JSON.stringify(body.detail ?? body);
      // A 403 ("Only the principal can run this workflow.") is a sentence
      // for the person, so show it as is rather than as a request failure.
      if (response.status === 403 && typeof body.detail === "string") {
        refusal = body.detail;
      }
    } catch {
      // body wasn't JSON
    }
    throw new Error(refusal ?? `Workflow request failed: ${detail}`);
  }

  const reader = response.body?.getReader();
  if (!reader) throw new Error("No response body");

  const decoder = new TextDecoder();
  let buffer = "";

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    buffer += decoder.decode(value, { stream: true });
    const lines = buffer.split("\n");
    buffer = lines.pop() ?? "";

    for (const line of lines) {
      if (line.startsWith("data: ")) {
        try {
          const data: WorkflowEvent = JSON.parse(line.slice(6));
          yield data;
        } catch {
          // skip malformed lines
        }
      }
    }
  }
}

// ---------------------------------------------------------------------------
// Agent Council
// ---------------------------------------------------------------------------

export interface AgentMeta {
  name: string;
  role: string;
  model: string;
  deep_reasoning: boolean;
  domains: string[];
  has_override: boolean;
  // "core": the Executive and the domain specialists (listed in the simple
  // view). "internal": triage and the helper agents.
  visibility: "core" | "internal";
}

export interface AgentDetail {
  name: string;
  role: string;
  role_default: string;
  model: string;
  model_default: string;
  deep_reasoning: boolean;
  deep_reasoning_default: boolean;
  prompt: string;
  prompt_default: string;
  domains: string[];
  has_override: boolean;
  overridden_fields: string[];
  updated_at: string | null;
  voice_persona_slug: string | null;
  research_focus: string | null;
  research_focus_default: string | null;
  instructions: string | null;
  // The Executive only: the model for one answer after pushback ("off" or ""
  // = same as normal answers), and PUSHBACK_MODEL's.
  pushback_model?: string | null;
  pushback_model_default?: string | null;
}

export interface AgentHistoryEntry {
  id: number;
  agent_id: string;
  prompt: string | null;
  model: string | null;
  use_deep_reasoning: boolean | null;
  role: string | null;
  voice_persona_slug: string | null;
  research_focus: string | null;
  instructions: string | null;
  pushback_model?: string | null;
  created_at: string;
}

export interface AgentPatch {
  prompt?: string | null;
  model?: string | null;
  use_deep_reasoning?: boolean | null;
  role?: string | null;
  voice_persona_slug?: string | null;
  research_focus?: string | null;
  instructions?: string | null;
  pushback_model?: string | null;
}

// ---- Voice Personas --------------------------------------------------------

export interface PersonaMeta {
  slug: string;
  display_name: string;
  is_builtin: boolean;
  is_customized: boolean;
  // Hidden from the voice picker but still loadable (named built-in voices).
  is_legacy: boolean;
  // Picker copy from a built-in voice's frontmatter ("" for custom voices).
  description: string;
  sample: string;
}

export interface Persona {
  slug: string;
  display_name: string;
  body: string;
  is_builtin: boolean;
  is_customized: boolean;
  source_notes: string;
  is_legacy: boolean;
  description: string;
  sample: string;
}

export async function listPersonas(): Promise<PersonaMeta[]> {
  const res = await fetch(`${API_BASE}/personas`);
  if (!res.ok) throw new Error("Failed to list personas");
  return res.json();
}

export async function getPersona(slug: string): Promise<Persona> {
  const res = await fetch(`${API_BASE}/personas/${encodeURIComponent(slug)}`);
  if (!res.ok) throw new Error("Failed to load persona");
  return res.json();
}

export async function savePersona(slug: string, displayName: string, body: string): Promise<Persona> {
  const res = await fetch(`${API_BASE}/personas/${encodeURIComponent(slug)}`, {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ display_name: displayName, body }),
  });
  if (!res.ok) {
    const err = await res.json().catch(() => ({}));
    throw new Error((err as { detail?: string }).detail ?? "Failed to save persona");
  }
  return res.json();
}

export async function createPersona(displayName: string, body: string): Promise<Persona> {
  const res = await fetch(`${API_BASE}/personas`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ display_name: displayName, body }),
  });
  if (!res.ok) {
    const err = await res.json().catch(() => ({}));
    throw new Error((err as { detail?: string }).detail ?? "Failed to create persona");
  }
  return res.json();
}

export async function resetPersona(slug: string): Promise<Persona> {
  const res = await fetch(`${API_BASE}/personas/${encodeURIComponent(slug)}/reset`, {
    method: "POST",
  });
  if (!res.ok) {
    const err = await res.json().catch(() => ({}));
    throw new Error((err as { detail?: string }).detail ?? "Failed to reset persona");
  }
  return res.json();
}

export async function deletePersona(slug: string): Promise<void> {
  const res = await fetch(`${API_BASE}/personas/${encodeURIComponent(slug)}`, {
    method: "DELETE",
  });
  if (!res.ok) {
    const err = await res.json().catch(() => ({}));
    throw new Error((err as { detail?: string }).detail ?? "Failed to delete persona");
  }
}

export async function listAgents(): Promise<AgentMeta[]> {
  const res = await fetch(`${API_BASE}/agents`);
  if (!res.ok) throw new Error("Failed to list agents");
  return res.json();
}

export async function getAgentDetail(agentId: string): Promise<AgentDetail> {
  const res = await fetch(`${API_BASE}/agents/${encodeURIComponent(agentId)}`);
  if (!res.ok) throw new Error("Failed to load agent detail");
  return res.json();
}

export async function patchAgent(agentId: string, patch: AgentPatch): Promise<AgentDetail> {
  const res = await fetch(`${API_BASE}/agents/${encodeURIComponent(agentId)}`, {
    method: "PATCH",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(patch),
  });
  if (!res.ok) {
    const err = await res.json().catch(() => ({}));
    throw new Error((err as { detail?: string }).detail ?? "Failed to update agent");
  }
  return res.json();
}

export async function resetAgent(agentId: string): Promise<void> {
  const res = await fetch(`${API_BASE}/agents/${encodeURIComponent(agentId)}/override`, {
    method: "DELETE",
  });
  if (!res.ok) throw new Error("Failed to reset agent");
}

export async function listAgentHistory(agentId: string): Promise<AgentHistoryEntry[]> {
  const res = await fetch(`${API_BASE}/agents/${encodeURIComponent(agentId)}/history`);
  if (!res.ok) throw new Error("Failed to list history");
  return res.json();
}

export async function rollbackAgent(
  agentId: string,
  historyId: number
): Promise<AgentDetail> {
  const res = await fetch(
    `${API_BASE}/agents/${encodeURIComponent(agentId)}/rollback/${historyId}`,
    { method: "POST" }
  );
  if (!res.ok) throw new Error("Failed to roll back");
  return res.json();
}

export async function testAgent(
  agentId: string,
  body: {
    query: string;
    prompt?: string | null;
    instructions?: string | null;
    model?: string | null;
    use_deep_reasoning?: boolean | null;
  }
): Promise<{ response: string }> {
  const res = await fetch(`${API_BASE}/agents/${encodeURIComponent(agentId)}/test`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });
  if (!res.ok) {
    const err = await res.json().catch(() => ({}));
    throw new Error((err as { detail?: string }).detail ?? "Test call failed");
  }
  return res.json();
}

// Quality presets (Fast / Balanced / Thorough). Mirrors QualityPresets in
// api/routes/agents.py. A preset is applied as ordinary per-agent
// overrides, so `active` is null ("Custom") once any agent is changed on
// its own; `custom_agents` lists the agents that differ from `base`.
export type QualityPresetId = "fast" | "balanced" | "thorough";

export interface QualityPreset {
  id: QualityPresetId;
  label: string;
  description: string;
  available: boolean;
  model: string | null;
}

export interface QualityPresets {
  presets: QualityPreset[];
  active: QualityPresetId | null;
  base: QualityPresetId;
  custom_agents: string[];
}

export async function listQualityPresets(): Promise<QualityPresets> {
  const res = await fetch(`${API_BASE}/agents/presets`);
  if (!res.ok) throw new Error("Failed to load quality presets");
  return res.json();
}

export async function applyQualityPreset(id: QualityPresetId): Promise<QualityPresets> {
  const res = await fetch(`${API_BASE}/agents/presets/${encodeURIComponent(id)}`, {
    method: "POST",
  });
  if (!res.ok) {
    const err = await res.json().catch(() => ({}));
    throw new Error((err as { detail?: string }).detail ?? "Failed to apply preset");
  }
  return res.json();
}

// One allowlisted model, grouped for the Council's Provider → Model picker.
// Mirrors ModelOption in api/routes/agents.py. `route` says which backend
// actually serves the id (it mirrors providers.registry.get_provider).
export interface ModelOption {
  id: string;
  provider: string;
  provider_label: string;
  route: "direct" | "openrouter" | "local";
  label: string;
}

export async function listAgentModelOptions(agentId?: string): Promise<ModelOption[]> {
  const qs = agentId ? `?agent_id=${encodeURIComponent(agentId)}` : "";
  const res = await fetch(`${API_BASE}/agents/models/options${qs}`);
  if (!res.ok) throw new Error("Failed to list models");
  return res.json();
}

// ---------------------------------------------------------------------------
// Audit log
// ---------------------------------------------------------------------------

export interface AuditEvent {
  id: number;
  ts: string;
  event_type: string;
  session_id: string | null;
  turn_id: string | null;
  actor: string | null;
  summary: string;
  details: Record<string, unknown>;
}

export interface AuditListResponse {
  items: AuditEvent[];
  total: number;
  limit: number;
  offset: number;
  event_types: string[];
}

export interface AuditQuery {
  event_type?: string;
  session_id?: string;
  actor?: string;
  q?: string;
  since?: string;
  until?: string;
  limit?: number;
  offset?: number;
}

export async function listAuditLogs(params: AuditQuery = {}): Promise<AuditListResponse> {
  const qs = new URLSearchParams();
  for (const [k, v] of Object.entries(params)) {
    if (v !== undefined && v !== null && v !== "") qs.set(k, String(v));
  }
  const res = await fetch(`${API_BASE}/audit/logs?${qs.toString()}`);
  if (!res.ok) throw new Error("Failed to list audit logs");
  return res.json();
}

export interface AuditEventDetail extends AuditEvent {
  // Un-truncated drill-down payload. Null for rows that pre-date the
  // column or for which no extra payload was captured.
  full: Record<string, unknown> | null;
}

export async function getAuditLog(id: number): Promise<AuditEventDetail> {
  const res = await fetch(`${API_BASE}/audit/logs/${id}`);
  if (!res.ok) throw new Error("Failed to load audit event");
  return res.json();
}

// Session-scoped read used by /audit/session/[id] and the drill-down preview
// in /audit. Returns the full ordered timeline plus a server-derived graph
// (nodes + edges) so the UI doesn't re-derive causality client-side.

export interface AuditGraphNode {
  id: string;
  event_id: number;
  event_type: string;
  kind: string; // "inbound" | "memory" | "knowledge" | "specialist" | "tool" | "cache" | "committee" | "response" | "alert" | "scheduled" | fallback to event_type
  label: string;
  actor: string | null;
  turn_id: string | null;
  ts: string;
}

export interface AuditGraphEdge {
  source: string;
  target: string;
  relation: "order" | "cause" | string;
}

export interface AuditGraph {
  nodes: AuditGraphNode[];
  edges: AuditGraphEdge[];
}

export interface TurnCost {
  turn_id: string | null;
  calls: number;
  input_tokens: number;
  cache_read_input_tokens: number;
  cache_creation_input_tokens: number;
  output_tokens: number;
}

export interface CostSummary {
  calls: number;
  input_tokens: number;
  cache_read_input_tokens: number;
  cache_creation_input_tokens: number;
  output_tokens: number;
  per_turn: TurnCost[];
}

export interface Degradation {
  kind: string;
  reason: string;
  count: number;
  turn_ids: string[];
  detail: string | null;
}

export interface AuditSessionResponse {
  session_id: string;
  events: AuditEvent[];
  graph: AuditGraph;
  channel: string | null;
  cost_summary: CostSummary | null;
  degradations: Degradation[];
}

export async function getAuditSession(
  sessionId: string,
): Promise<AuditSessionResponse> {
  const res = await fetch(
    `${API_BASE}/audit/sessions/${encodeURIComponent(sessionId)}`,
  );
  if (!res.ok) {
    if (res.status === 404) {
      throw new Error(`No events found for session ${sessionId}`);
    }
    throw new Error("Failed to load audit session");
  }
  return res.json();
}

// Cross-session token-usage aggregate used by /audit/usage. Totals plus by-day,
// by-model and by-source breakdowns, summed from cache_event rows. `cost_usd` is
// the actual OpenRouter charge captured per call (0 for rows that predate
// capture); `web_search_requests` counts server-side searches the calls made.

export interface UsageTotals {
  calls: number;
  input_tokens: number;
  cache_read_input_tokens: number;
  cache_creation_input_tokens: number;
  output_tokens: number;
  // Absent on rows written before searches were recorded.
  web_search_requests?: number;
  cost_usd: number;
}

export interface UsageByDay extends UsageTotals {
  day: string; // YYYY-MM-DD (UTC)
}

export interface UsageByModel extends UsageTotals {
  model: string;
}

// One row per call source (the audit `actor`): executive, specialist,
// specialist_workflow, specialist_research, research_synthesis,
// research_watchlist, triage, memory_extractor, agent_test, …
export interface UsageBySource extends UsageTotals {
  source: string;
}

export interface UsageSummary {
  since: string | null;
  until: string | null;
  totals: UsageTotals;
  by_day: UsageByDay[];
  by_model: UsageByModel[];
  // Absent on a backend older than the by-source breakdown.
  by_source?: UsageBySource[];
  // Sandboxed scripts (run_script). Absent on an older backend.
  scripts?: ScriptUsage;
  // Python jobs (run_python_job). Absent on an older backend.
  python_jobs?: PythonJobUsage;
}

export interface PythonJobUsage {
  jobs: number;
  ok: number;
  saved_runs: number;
  attachments: number;
  duration_ms: number;
  cpu_ms: number;
  // The largest peak memory of any one job, in MB.
  peak_mb_max: number;
  bytes_in: number;
  bytes_out: number;
  // Model usage on the turns that ran a job (the whole turn, not just the job).
  turns: number;
  input_tokens: number;
  output_tokens: number;
  cache_read_input_tokens: number;
  cost_usd: number;
}

export interface ScriptUsage {
  scripts: number;
  ok: number;
  calls: number;
  // Upper bound: each call past a script's first would otherwise have needed
  // a model turn, unless the model had batched it with others.
  turns_avoided: number;
  duration_ms: number;
  in_workflows: number;
}

export async function getAuditUsage(
  params: { since?: string; until?: string } = {},
): Promise<UsageSummary> {
  const qs = new URLSearchParams();
  for (const [k, v] of Object.entries(params)) {
    if (v !== undefined && v !== null && v !== "") qs.set(k, String(v));
  }
  const res = await fetch(`${API_BASE}/audit/usage?${qs.toString()}`);
  if (!res.ok) throw new Error("Failed to load token usage");
  return res.json();
}

// ── Fixtures ──────────────────────────────────────────────────────────────────

export interface FixtureDepartmentSummary {
  title: string;
  head: string | null;
}

export interface FixturePersonSummary {
  name: string;
  role: string;
  is_principal: boolean;
}

export interface FixtureSummary {
  name: string;
  display_name: string;
  industry: string;
  stage: string;
  arr: number | null;
  headcount: number | null;
  founding_year: number | null;
  mission: string;
  doc_count: number;
  scenario_count: number;
  departments: FixtureDepartmentSummary[];
  people: FixturePersonSummary[];
  // "curated" = git-tracked YAML seed; "generated" = LLM-authored, DB-backed.
  // Optional for back-compat with older payloads.
  source?: "curated" | "generated";
}

export interface FixtureLoadResult {
  fixture: string;
  display_name: string;
  docs_indexed: number;
  memory_seeded: { decisions: number; initiatives: number; advice_given: number };
}

export async function listFixtures(): Promise<FixtureSummary[]> {
  const res = await fetch(`${API_BASE}/fixtures`);
  if (!res.ok) throw new Error("Failed to list fixtures");
  const data = await res.json();
  return data.fixtures as FixtureSummary[];
}

export async function loadFixture(name: string): Promise<FixtureLoadResult> {
  const res = await fetch(`${API_BASE}/fixtures/${encodeURIComponent(name)}/load`, {
    method: "POST",
  });
  if (!res.ok) {
    const err = await res.json().catch(() => ({ detail: res.statusText }));
    throw new Error(err.detail ?? "Failed to load fixture");
  }
  return res.json() as Promise<FixtureLoadResult>;
}

export interface FixtureStatus {
  active_fixture: string | null;
  has_snapshot: boolean;
}

export interface SnapshotResult {
  snapshot_taken: boolean;
  docs_snapshotted: number;
  memory_snapshotted: { decisions: number; initiatives: number; advice_given: number };
  people_snapshotted: number;
  departments_snapshotted: number;
}

export interface UnloadResult {
  restored_from_backup: boolean;
  display_name: string;
  docs_indexed: number;
  memory_seeded: { decisions: number; initiatives: number; advice_given: number };
  people_seeded: number;
  departments_seeded: number;
}

export async function getFixtureStatus(): Promise<FixtureStatus> {
  const res = await fetch(`${API_BASE}/fixtures/status`);
  if (!res.ok) throw new Error("Failed to fetch fixture status");
  return res.json() as Promise<FixtureStatus>;
}

export async function snapshotCurrentState(): Promise<SnapshotResult> {
  const res = await fetch(`${API_BASE}/fixtures/snapshot`, { method: "POST" });
  if (!res.ok) {
    const err = await res.json().catch(() => ({ detail: res.statusText }));
    throw new Error(err.detail ?? "Failed to snapshot current state");
  }
  return res.json() as Promise<SnapshotResult>;
}

export async function unloadFixture(): Promise<UnloadResult> {
  const res = await fetch(`${API_BASE}/fixtures/unload`, { method: "POST" });
  if (!res.ok) {
    const err = await res.json().catch(() => ({ detail: res.statusText }));
    throw new Error(err.detail ?? "Failed to unload fixture");
  }
  return res.json() as Promise<UnloadResult>;
}

export interface ResetResult {
  reset: boolean;
  departments_seeded: number;
  episodic_cleared: Record<string, number>;
  people_cleared: Record<string, number>;
}

export async function resetAllState(): Promise<ResetResult> {
  const res = await fetch(`${API_BASE}/fixtures/reset`, { method: "POST" });
  if (!res.ok) {
    const err = await res.json().catch(() => ({ detail: res.statusText }));
    throw new Error(err.detail ?? "Failed to reset state");
  }
  return res.json() as Promise<ResetResult>;
}

// ── Generated fixtures (LLM-authored) ───────────────────────────────────────

// A generated fixture bundle. Typed loosely on purpose — the UI only reads a
// few summary fields for the review step; the full object round-trips back to
// the backend on save, which re-validates it against the canonical schema.
export interface GeneratedFixtureBundle {
  profile: {
    name: string;
    industry?: string;
    stage?: string;
    headcount?: number | null;
    annual_revenue_arr?: number | null;
    mission?: string;
    [key: string]: unknown;
  };
  people: Array<{ full_name: string; role?: string; is_principal?: boolean }>;
  departments: Array<{ slug: string; title: string; head_person_name?: string | null }>;
  memory: {
    decisions?: unknown[];
    initiatives?: unknown[];
    advice_given?: unknown[];
    alerts?: unknown[];
  };
  docs: Array<{ filename: string; content?: string }>;
}

export interface GenerateFixtureResult {
  suggested_name: string;
  display_name: string;
  bundle: GeneratedFixtureBundle;
}

export async function generateFixture(
  description: string
): Promise<GenerateFixtureResult> {
  const res = await fetch(`${API_BASE}/fixtures/generate`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ description }),
  });
  if (!res.ok) {
    const err = await res.json().catch(() => ({ detail: res.statusText }));
    throw new Error(err.detail ?? "Failed to generate fixture");
  }
  return res.json() as Promise<GenerateFixtureResult>;
}

export interface CreateFixtureResult {
  name: string;
  display_name: string;
  source: "generated";
  doc_count: number;
}

export async function createFixture(
  bundle: GeneratedFixtureBundle,
  scenarioDescription: string
): Promise<CreateFixtureResult> {
  const res = await fetch(`${API_BASE}/fixtures`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ bundle, scenario_description: scenarioDescription }),
  });
  if (!res.ok) {
    const err = await res.json().catch(() => ({ detail: res.statusText }));
    throw new Error(err.detail ?? "Failed to save fixture");
  }
  return res.json() as Promise<CreateFixtureResult>;
}

export async function deleteFixture(name: string): Promise<void> {
  const res = await fetch(`${API_BASE}/fixtures/${encodeURIComponent(name)}`, {
    method: "DELETE",
  });
  if (!res.ok) {
    const err = await res.json().catch(() => ({ detail: res.statusText }));
    throw new Error(err.detail ?? "Failed to delete fixture");
  }
}

// ---------------------------------------------------------------------------
// Departments
// ---------------------------------------------------------------------------

export interface DepartmentCharter {
  mission: string;
  scope: string[];
  out_of_scope: string[];
}

export interface DepartmentConfig {
  slug: string;
  title: string;
  specialist_key: string | null;
  charter: DepartmentCharter;
  authority_level: "auto_execute" | "propose_only" | "escalate";
  head_person_id: number | null;
  head_persona_slug: string | null;
  cadences: Record<string, string>;
  // Department-scoped broadcast channels. When set, OE can post to
  // the department's team room via `send_department_message` instead
  // of (or in addition to) DMing the head.
  slack_channel_id: string | null;
  discord_channel_id: string | null;
  telegram_chat_id: string | null;
  // Named external entities this department wants monitored. The research
  // watch policy treats them as strong grounding: a proposal about one can
  // be added to the watch list on its own and is routed to this department.
  watched_entities: string[];
}

export type PeriodType = "week" | "month" | "quarter" | "year" | "ongoing";

export interface Goal {
  id: number | null;
  // Null for a goal with no department: it stands on its own.
  department_slug: string | null;
  // Who it is on when set; null = its department's lead, else the principal.
  owner_person_id?: number | null;
  period_type: PeriodType;
  period_value: string;
  key_result: string;
  target: string;
  current: string;
  status: "on_track" | "at_risk" | "off_track";
  created_at: string;
  updated_at: string;
  // When OE last graded this goal (department_check_in workflow, or
  // Phase B: a chat-driven `update_department_goal` tool call). Distinct
  // from `updated_at`, which bumps on any content edit. Empty = never
  // reviewed.
  last_reviewed_at: string;
}

export interface DepartmentState {
  config: DepartmentConfig;
  goals: Goal[];
  headcount: number | null;
  budget_usd: number | null;
  member_person_ids: number[];
  updated_at: string;
}

export async function listDepartments(): Promise<DepartmentState[]> {
  const res = await fetch(`${API_BASE}/departments`);
  if (!res.ok) throw new Error(`Failed to load departments: ${res.statusText}`);
  return res.json();
}

/** One department as its page reads it (GET and PATCH /departments/{slug}). */
export interface DepartmentDetail extends DepartmentState {
  /** When the next check-in is queued (ISO, UTC); null when the check-in is
   *  off, the workspace is solo, or none is queued yet. */
  next_check_in_at: string | null;
}

export async function getDepartment(slug: string): Promise<DepartmentDetail> {
  const res = await fetch(`${API_BASE}/departments/${slug}`);
  if (!res.ok) throw new Error(`Failed to load department: ${res.statusText}`);
  return res.json();
}

export interface DepartmentPatch {
  title?: string;
  charter?: DepartmentCharter;
  authority_level?: DepartmentConfig["authority_level"];
  cadences?: Record<string, string>;
  head_person_id?: number | null;
  headcount?: number | null;
  budget_usd?: number | null;
  slack_channel_id?: string | null;
  discord_channel_id?: string | null;
  telegram_chat_id?: string | null;
  watched_entities?: string[];
}

export async function updateDepartment(slug: string, patch: DepartmentPatch): Promise<DepartmentDetail> {
  const res = await fetch(`${API_BASE}/departments/${slug}`, {
    method: "PATCH",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(patch),
  });
  if (!res.ok) throw await onboardError(res, `Failed to update department: ${res.statusText}`);
  delegationChanged();
  return res.json();
}

export interface DepartmentCreate {
  title: string;
  mission?: string;
}

export async function createDepartment(body: DepartmentCreate): Promise<DepartmentState> {
  const res = await fetch(`${API_BASE}/departments`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });
  if (!res.ok) throw new Error(`Failed to create department: ${res.statusText}`);
  return res.json();
}

export async function deleteDepartment(slug: string): Promise<void> {
  const res = await fetch(`${API_BASE}/departments/${slug}`, {
    method: "DELETE",
  });
  if (!res.ok) throw new Error(`Failed to delete department: ${res.statusText}`);
}

// Only `key_result` is required: the server fills a missing `period_value`
// with the current period for `period_type`, and `target` may be empty.
export interface GoalCreate {
  period_type?: PeriodType;
  period_value?: string;
  key_result: string;
  target?: string;
  current?: string;
  status?: Goal["status"];
  owner_person_id?: number | null;
}

/** A goal as GET /goals returns it: its owner and department resolved. */
export interface GoalView extends Goal {
  // Its own owner, else its department's lead, else the principal.
  owner_id: number | null;
  owner_name: string;
  department_title: string | null;
}

/** Every goal, with or without a department. */
export async function listGoals(): Promise<GoalView[]> {
  const res = await fetch(`${API_BASE}/goals`, { cache: "no-store" });
  if (!res.ok) throw await goalError(res, "Couldn't load goals");
  return res.json();
}

// The server's reason when it gives one — a string `detail`, or the first
// FastAPI validation message — else `fallback`.
async function goalError(res: Response, fallback: string): Promise<Error> {
  const body = (await res.json().catch(() => ({}))) as { detail?: unknown };
  if (typeof body.detail === "string") return new Error(body.detail);
  const first = Array.isArray(body.detail) ? (body.detail[0] as { msg?: unknown; loc?: unknown }) : undefined;
  if (typeof first?.msg === "string") {
    const loc = Array.isArray(first.loc) ? first.loc[first.loc.length - 1] : undefined;
    const field = typeof loc === "string" && loc !== "body" ? `${loc.replace(/_/g, " ")}: ` : "";
    return new Error(`${fallback} — ${field}${first.msg.replace(/^Value error, /, "")}`);
  }
  return new Error(`${fallback} (${res.status})`);
}

export async function createGoal(slug: string, body: GoalCreate): Promise<Goal> {
  const res = await fetch(`${API_BASE}/departments/${slug}/goals`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });
  if (!res.ok) throw await goalError(res, "Couldn't add the goal");
  return res.json();
}

/** Add a goal, naming its department in words: an existing one by slug or
 * title, else a new one of that name. Blank = no department. */
export async function createGoalInArea(area: string, body: GoalCreate): Promise<Goal> {
  const res = await fetch(`${API_BASE}/goals`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ ...body, area }),
  });
  if (!res.ok) throw await goalError(res, "Couldn't add the goal");
  return res.json();
}

export interface GoalPatch {
  period_type?: PeriodType;
  period_value?: string;
  key_result?: string;
  target?: string;
  current?: string;
  status?: Goal["status"];
  // Only through updateAnyGoal. null clears: no owner of its own / no department.
  owner_person_id?: number | null;
  department_slug?: string | null;
}

/** Edit a goal wherever it is, including its owner and department. */
export async function updateAnyGoal(goalId: number, patch: GoalPatch): Promise<Goal> {
  const res = await fetch(`${API_BASE}/goals/${goalId}`, {
    method: "PATCH",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(patch),
  });
  if (!res.ok) throw await goalError(res, "Couldn't save the goal");
  return res.json();
}

export async function deleteAnyGoal(goalId: number): Promise<void> {
  const res = await fetch(`${API_BASE}/goals/${goalId}`, { method: "DELETE" });
  if (!res.ok) throw new Error(`Failed to delete Goal: ${res.statusText}`);
}

export async function updateGoal(slug: string, goalId: number, patch: GoalPatch): Promise<Goal> {
  const res = await fetch(`${API_BASE}/departments/${slug}/goals/${goalId}`, {
    method: "PATCH",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(patch),
  });
  if (!res.ok) throw await goalError(res, "Couldn't save the goal");
  return res.json();
}

export async function deleteGoal(slug: string, goalId: number): Promise<void> {
  const res = await fetch(`${API_BASE}/departments/${slug}/goals/${goalId}`, {
    method: "DELETE",
  });
  if (!res.ok) throw new Error(`Failed to delete Goal: ${res.statusText}`);
}

// ---------------------------------------------------------------------------
// People
// ---------------------------------------------------------------------------

export interface AvailabilityWindow {
  weekdays: number[];
  start_local: string;
  end_local: string;
  timezone: string;
}

// "team": works with the principal — can sign in, talk to the bot, approve and
// be chased. "contact": someone outside the team (a client, a contractor) the
// Executive emails or invites only when the principal asks it to directly.
export type PersonKind = "team" | "contact";

// Other ways to reach someone (people/contact_info.py), for the reader only.
export type DetailKind = "phone" | "mobile" | "website" | "linkedin" | "social" | "address";

export interface ContactDetail {
  kind: DetailKind;
  value: string;
}

export interface Person {
  id: number;
  full_name: string;
  role: string;
  is_principal: boolean;
  kind: PersonKind;
  department_slugs: string[];
  email: string | null;
  // Other addresses they write from: they match their mail and may be
  // emailed, but never sign in (only `email` does).
  email_aliases?: string[];
  slack_user_id: string | null;
  telegram_chat_id: string | null;
  discord_user_id: string | null;
  // Phone, website, profiles, postal address; some from their signature.
  details?: ContactDetail[];
  preferred_channel: string;
  // The chat app they last talked to the Executive in (slack, discord or
  // telegram); with preferred_channel "any" messages go there first.
  last_channel?: string | null;
  availability: AvailabilityWindow[];
  authority_scope: string[];
  response_sla_hours: number;
  on_leave_until: string | null;
  reports_to_person_id: number | null;
  archived: boolean;
}

// Team members only by default — the pickers (department head, workflow
// approver, …) must never offer a contact. The People page asks for both;
// the server honours that only for the principal (contacts are theirs alone).
export async function listPeople(opts: { includeContacts?: boolean } = {}): Promise<Person[]> {
  const query = opts.includeContacts ? "?include_contacts=true" : "";
  const res = await fetch(`${API_BASE}/people${query}`);
  if (!res.ok) throw new Error(`Failed to load people: ${res.statusText}`);
  return res.json();
}

// Who the signed-in viewer is on the roster. Contacts are private to the
// principal, so the People page offers them only when `is_principal`.
export interface PeopleViewer {
  person_id: number | null;
  is_principal: boolean;
}

export async function getPeopleViewer(): Promise<PeopleViewer> {
  const res = await fetch(`${API_BASE}/people/me`);
  if (!res.ok) throw new Error(`Failed to load viewer: ${res.statusText}`);
  return res.json();
}

// Contacts the Executive keeps up to date (people/contact_keeper.py): what
// it changed, with an Undo each, and the switch. The principal's alone.
export type ContactKeeperMode = "on" | "ask" | "off";

export interface ContactChange {
  id: number;
  person_id: number | null;
  action: "add" | "update";
  field: "contact" | "full_name" | "role" | "email_alias" | DetailKind;
  email: string;
  full_name: string;
  old_value: string;
  new_value: string;
  reason: "emailed" | "met" | "asked" | "from_line" | "signature";
  evidence: number;
  status: "applied" | "suggested" | "undone" | "dismissed";
  seen: boolean;
  created_at: string;
  decided_at: string | null;
}

export interface ContactChanges {
  mode: ContactKeeperMode;
  status: string;
  last_run_at: string | null;
  changes: ContactChange[];
}

async function contactsCall<T>(path: string, init?: RequestInit): Promise<T> {
  const res = await fetch(`${API_BASE}/contacts${path}`, init);
  if (!res.ok) {
    const body = await res.json().catch(() => null);
    throw new Error(typeof body?.detail === "string" ? body.detail : `Request failed: ${res.statusText}`);
  }
  return res.json();
}

export function getContactChanges(personId?: number): Promise<ContactChanges> {
  return contactsCall(`/changes${personId !== undefined ? `?person_id=${personId}` : ""}`);
}

// What the Executive remembers about one contact (people/contact_notes.py),
// from the principal's own mail and meetings. null when nothing yet.
export interface ContactNote {
  person_id: number;
  note: string;
  topics: string[];
  last_emailed_at: string | null;
  last_heard_at: string | null;
  last_met_at: string | null;
  next_meeting_at: string | null;
  next_meeting_title: string;
  emailed_count: number;
  met_count: number;
  note_written_at: string | null;
  updated_at: string;
}

export async function getContactNote(personId: number): Promise<ContactNote | null> {
  const res = await fetch(`${API_BASE}/contacts/${personId}/note`);
  if (res.status === 404) return null;
  if (!res.ok) throw new Error(`Request failed: ${res.statusText}`);
  return res.json();
}

export function setContactKeeperMode(mode: ContactKeeperMode): Promise<ContactChanges> {
  return contactsCall("/keeper", {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ mode }),
  });
}

export function markContactChangesSeen(): Promise<ContactChanges> {
  return contactsCall("/changes/seen", { method: "POST" });
}

export function decideContactChange(id: number, verb: "undo" | "accept" | "dismiss"): Promise<ContactChange> {
  return contactsCall(`/changes/${id}/${verb}`, { method: "POST" });
}

export async function getPerson(id: number): Promise<Person> {
  const res = await fetch(`${API_BASE}/people/${id}`);
  if (!res.ok) throw new Error(`Failed to load person: ${res.statusText}`);
  return res.json();
}

export interface PersonCreate {
  full_name: string;
  role?: string;
  is_principal?: boolean;
  kind?: PersonKind;
  department_slugs?: string[];
  email?: string | null;
  email_aliases?: string[];
  slack_user_id?: string | null;
  telegram_chat_id?: string | null;
  discord_user_id?: string | null;
  preferred_channel?: string;
  response_sla_hours?: number;
  on_leave_until?: string | null;
  authority_scope?: string[];
  availability?: AvailabilityWindow[];
}

// The Slack, Discord and Telegram people and rooms the bots can reach, by
// name, for the pickers (lib/chatDirectory.ts). The principal's alone: for
// anyone else (403), or when it can't be read, this is null and the pickers
// keep only the by-hand id field.
async function getDirectory(path: string): Promise<DirectoryListing | null> {
  try {
    const res = await fetch(`${API_BASE}/chat-directory/${path}`);
    if (!res.ok) return null;
    return (await res.json()) as DirectoryListing;
  } catch {
    return null;
  }
}

export function getChatDirectoryPeople(): Promise<DirectoryListing | null> {
  return getDirectory("people");
}

export function getChatDirectoryChannels(): Promise<DirectoryListing | null> {
  return getDirectory("channels");
}

// The Slack person with this work email, or null (no match, no Slack bot, or
// not the principal).
export async function findSlackPersonByEmail(email: string): Promise<DirectoryOption | null> {
  try {
    const res = await fetch(`${API_BASE}/chat-directory/slack/lookup?email=${encodeURIComponent(email)}`);
    if (!res.ok) return null;
    const body = (await res.json()) as { configured: boolean; match: DirectoryOption | null };
    return body.match ?? null;
  } catch {
    return null;
  }
}

// Adding, editing and archiving people is the principal's alone (403 for anyone
// else): the People list is also who can sign in and who the Executive emails.
const PEOPLE_PRINCIPAL_ONLY = "Only the principal can change the People list.";

export async function createPerson(body: PersonCreate): Promise<Person> {
  const res = await fetch(`${API_BASE}/people`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });
  if (res.status === 403) throw new Error(PEOPLE_PRINCIPAL_ONLY);
  if (res.status === 409) throw new Error(await errorDetail(res, "That address is already on another person."));
  // A detail that isn't plainly its kind: the server names the line.
  if (res.status === 422) throw new Error(await errorDetail(res, "Check the phone, website and more lines."));
  if (!res.ok) throw new Error(`Failed to create person: ${res.statusText}`);
  return res.json();
}

export interface PersonPatch {
  full_name?: string;
  role?: string;
  kind?: PersonKind;
  email?: string | null;
  // The full list; replaces the current one.
  email_aliases?: string[];
  // The full list; replaces the current one.
  details?: ContactDetail[];
  slack_user_id?: string | null;
  telegram_chat_id?: string | null;
  discord_user_id?: string | null;
  preferred_channel?: string;
  response_sla_hours?: number;
  on_leave_until?: string | null;
  clear_on_leave?: boolean;
  department_slugs?: string[];
  authority_scope?: string[];
  availability?: AvailabilityWindow[];
}

export async function updatePerson(id: number, patch: PersonPatch): Promise<Person> {
  const res = await fetch(`${API_BASE}/people/${id}`, {
    method: "PATCH",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(patch),
  });
  if (res.status === 403) throw new Error(PEOPLE_PRINCIPAL_ONLY);
  if (res.status === 409) throw new Error(await errorDetail(res, "That address is already on another person."));
  // A detail that isn't plainly its kind: the server names the line.
  if (res.status === 422) throw new Error(await errorDetail(res, "Check the phone, website and more lines."));
  if (!res.ok) throw new Error(`Failed to update person: ${res.statusText}`);
  return res.json();
}

// The server's `detail` for a refused request, or `fallback`.
async function errorDetail(res: Response, fallback: string): Promise<string> {
  try {
    const body = await res.json();
    return typeof body?.detail === "string" ? body.detail : fallback;
  } catch {
    return fallback;
  }
}

// A roster request: someone not on the People list wrote in, was told their
// message is waiting, and is held until the principal says who they are.
// Everything here is server-derived; `display_name` is the name the sender
// gave (unverified) and `previews` are the first lines of what they wrote.
export interface RosterRequestCard {
  id: number;
  channel: "email" | "slack" | "discord" | "telegram" | string;
  channel_ref: string;
  display_name: string;
  profile_email: string | null;
  on_company_domain: boolean;
  suggested_kind: PersonKind | null;
  suggested_person_id: number | null;
  suggested_person_name: string | null;
  message_count: number;
  ack_sent: boolean;
  first_seen_at: string;
  previews: string[];
}

// Either add them (`full_name` + `kind`) or say they are someone already on
// the list (`link_person_id`).
export interface RosterRequestAnswer {
  full_name?: string;
  kind?: PersonKind;
  role?: string;
  link_person_id?: number;
  replace_channel_id?: boolean;
}

export async function approveRosterRequest(id: number, answer: RosterRequestAnswer): Promise<void> {
  const res = await fetch(`${API_BASE}/people/requests/${id}/approve`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(answer),
  });
  if (!res.ok) throw new Error(await errorDetail(res, `Could not add them: ${res.statusText}`));
}

export async function declineRosterRequest(id: number): Promise<void> {
  const res = await fetch(`${API_BASE}/people/requests/${id}/decline`, { method: "POST" });
  if (!res.ok) throw new Error(await errorDetail(res, `Could not ignore them: ${res.statusText}`));
}

export async function archivePerson(id: number): Promise<void> {
  const res = await fetch(`${API_BASE}/people/${id}/archive`, { method: "POST" });
  if (res.status === 403) throw new Error(PEOPLE_PRINCIPAL_ONLY);
  if (!res.ok) throw new Error(`Failed to archive person: ${res.statusText}`);
}

// Attunement — open loops: things a person committed to or was asked for in
// conversation and hasn't reported done. Overdue ones are chased by the
// nudge engine; closing one stops the chase.
export interface OpenLoop {
  loop_id: number;
  owner_person_id: number;
  owner_name: string;
  description: string;
  due_at: string;
  created_at: string;
  // Only on the response to an assignment: whether the person was told.
  notified?: AssignNotice | null;
}

// "sent" on `channel`, "held" for their quiet hours or brief, "not_reached"
// when no channel worked, "skipped" for their own task or with notices off.
// A teammate assigning gets no channel and "later" in place of "held".
export interface AssignNotice {
  status: "sent" | "held" | "later" | "not_reached" | "skipped";
  channel: string | null;
}

export async function getPersonOpenLoops(id: number): Promise<OpenLoop[]> {
  const res = await fetch(`${API_BASE}/people/${id}/open-loops`);
  if (!res.ok) throw new Error(`Failed to load open loops: ${res.statusText}`);
  return res.json();
}

// Assign this person a task: an open loop they are followed up on once it is
// due. They are told once on their own channel when someone else assigns it.
// The principal or anyone on the team may.
// `dueDate` is a local YYYY-MM-DD; omit it for the default due window.
export async function assignOpenLoop(
  personId: number,
  task: string,
  dueDate?: string,
): Promise<OpenLoop> {
  const res = await fetch(`${API_BASE}/people/${personId}/open-loops`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ task, ...(dueDate ? { due_date: dueDate } : {}) }),
  });
  if (!res.ok) throw new Error(await errorDetail(res, `Couldn't assign the task (${res.status})`));
  return res.json();
}

export async function closeOpenLoop(
  loopId: number,
  reason: "done" | "not_needed" | "cancelled" = "done",
): Promise<void> {
  const res = await fetch(`${API_BASE}/open-loops/${loopId}/close`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ reason }),
  });
  if (!res.ok) throw new Error(`Failed to close open loop: ${res.statusText}`);
}

// Attunement outcome ledger: how a person responded to proactive outreach
// over the last 30 days, per kind of outreach.
export interface OutreachStat {
  source: string;
  label: string;
  sent: number;
  replied: number;
  acted: number;
  ignored: number;
  pending: number;
}

export async function getPersonOutreach(id: number): Promise<OutreachStat[]> {
  const res = await fetch(`${API_BASE}/people/${id}/outreach`);
  if (!res.ok) throw new Error(`Failed to load outreach: ${res.statusText}`);
  return res.json();
}

// Attunement working style: a few short "how they like replies" rules pinned
// into this person's own turns. Learned from their own 👍/👎 and requests;
// editable, lockable (a locked profile is never re-learned) and resettable.
export interface WorkingStyle {
  rules: { text: string; basis: string }[];
  locked: boolean;
  updated_at: string | null;
  updated_by: string | null;
}

export async function getPersonWorkingStyle(id: number): Promise<WorkingStyle> {
  const res = await fetch(`${API_BASE}/people/${id}/attunement`);
  if (!res.ok) throw new Error(`Failed to load working style: ${res.statusText}`);
  return res.json();
}

// `rules` null keeps the current rules and only sets the lock.
export async function savePersonWorkingStyle(
  id: number,
  rules: string[] | null,
  locked: boolean,
): Promise<WorkingStyle> {
  const res = await fetch(`${API_BASE}/people/${id}/attunement`, {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ rules, locked }),
  });
  if (!res.ok) {
    const body = await res.json().catch(() => null);
    throw new Error(
      typeof body?.detail === "string" ? body.detail : `Failed to save: ${res.statusText}`,
    );
  }
  return res.json();
}

export async function resetPersonWorkingStyle(id: number): Promise<void> {
  const res = await fetch(`${API_BASE}/people/${id}/attunement`, { method: "DELETE" });
  if (!res.ok) throw new Error(`Failed to reset working style: ${res.statusText}`);
}

// Explicit 👍/👎 on one assistant reply (null clears it).
export async function setMessageFeedback(
  sessionId: string,
  messageId: number,
  feedback: "up" | "down" | null,
): Promise<void> {
  const res = await fetch(
    `${API_BASE}/sessions/${encodeURIComponent(sessionId)}/messages/${messageId}/feedback`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ feedback }),
    },
  );
  if (!res.ok) throw new Error(`Failed to save feedback: ${res.statusText}`);
}

// ---------------------------------------------------------------------------
// Today (live dashboard) — was previously named "Morning Brief"
// ---------------------------------------------------------------------------

// An off-track/at-risk goal surfaced inline on the briefing's Department card
// (see today.py GoalBrief) so the card shows substance, not just counts.
export interface GoalBrief {
  key_result: string;
  current: string;
  target: string;
  status: string; // "at_risk" | "off_track"
  // Who it is on (its own owner, else the department's lead, else the
  // principal). Optional for older API builds.
  owner_id?: number | null;
  owner_name?: string;
}

export interface DepartmentBriefItem {
  // "" for the row holding the goals with no department ("Other goals").
  slug: string;
  title: string;
  authority_level: string;
  goal_count: number;
  at_risk_count: number;
  off_track_count: number;
  awaiting_count: number;
  // The actual problem goals (worst first, capped). Optional so older API
  // builds / test mocks without the field still typecheck.
  attention_goals?: GoalBrief[];
}

export interface PersonBriefItem {
  id: number;
  full_name: string;
  role: string;
  is_principal: boolean;
  preferred_channel: string;
  awaiting_count: number;
  soonest_sla_at: string | null;
  // Enrichment signals (see api/routes/today.py PersonBriefItem).
  status: "on_leave" | "needs_reply" | "awaiting" | "clear";
  awaiting_reply_count: number;
  oldest_awaiting_reply_at: string | null;
  on_leave_until: string | null;
  reachable_now: boolean;
  next_window_at: string | null;
  authority_scope: string[];
  department_slugs: string[];
  last_contact_at: string | null;
  overdue: boolean;
  priority: number;
  insight: string | null;
}

export interface ProposalItem {
  alert_id: number;
  // `headline` is a 160-char excerpt used as the card title; `body` is
  // the full intent text the UI seeds into the chat handoff so the
  // Executive has the full context.
  body: string;
  headline: string;
  routed_to_person_id: number | null;
  suggested_action: string;
  created_at: string;
  topic_tags: string[];
  // Presentation signals from the backend (see briefing/ranking.py).
  // `score` orders the action queue; `category` is "action" (needs a human)
  // or "monitoring" (passive watchlist noise the UI collapses). Optional so
  // older API builds / test mocks still compile.
  score?: number;
  category?: "action" | "monitoring";
  // Why this item is in "Needs you" rather than Monitoring — set only when an
  // external/watchlist signal was pulled into the action lane by its severity
  // (e.g. a large stock move). Null/absent for everything else.
  surfaced_reason?: string | null;
  // Set when this proposal is backed by a decision_instance (a gated calendar
  // booking awaiting approval). The briefing routes Approve/Reject to the
  // /decisions endpoints (which book/cancel server-side) instead of the
  // ack-and-handoff-to-chat flow. Null/absent for ordinary alert proposals.
  decision_instance_id?: number | null;
  // A scheduled run that failed: the run its Run again queues once more.
  failed_run_id?: string | null;
  // Set when the card is a roster request ("who is this new sender?"): the
  // briefing answers it at /people/requests/{id} instead of ack-and-chat.
  roster_request?: RosterRequestCard | null;
  // Alert lifecycle (alerts/lifecycle.py + alerts/review.py). All optional so
  // older API builds and test mocks keep compiling.
  // Coalescing: how many times the same situation re-fired, and when last.
  occurrence_count?: number;
  last_seen_at?: string | null;
  // The Executive's latest review: verdict ('' | relevant | changed |
  // likely_stale | drafted | routed | merged | resolved | stale — the last
  // two only on closed rows), the one-line "what changed
  // since you last looked", the move the card should lead with, a short
  // "why now", and a deadline when one exists.
  last_reviewed_at?: string | null;
  review_verdict?: string;
  review_note?: string;
  recommended_move?: string;
  why_now?: string;
  due_at?: string | null;
  // Rows the review folded into this one (merge).
  superseded_count?: number;
  // Registry workflow the review suggested as the next step ('' = none).
  suggested_workflow?: string;
  // Drafted artifacts only: the format (body is already Markdown for every
  // format) and, for "link" artifacts, the URL in the connected app.
  artifact_format?: ArtifactFormat | null;
  artifact_url?: string | null;
}

// One autonomous alert-review move since the last delivered morning brief
// (routed / nudged / escalated / drafted / merged / closed / changed).
// One brief's held-back lines: what it named that couldn't be matched to
// your data. The brief's note points here ("Left out of your brief").
export interface HeldBackItem {
  event_id: number;
  surface: string;
  at: string;
  lines: string[];
}

export interface HandledItem {
  kind: string;
  summary: string;
  at: string;
  alert_id?: number | null;
  // Structured view of the audit row (all additive; `summary` is the fallback).
  event_type?: string;
  headline?: string | null;
  target?: string | null;
  detail?: string;
  // "resolved" | "dismissed" for a close, "proposed" for a gated route, else "".
  outcome?: string;
  evidence_ref?: string;
  superseded_by_alert_id?: number | null;
  // The alert's status NOW: "open" | "resolved" | "dismissed" | "expired" |
  // "merged" | "" — "open" on a closed row means the close was already undone.
  status?: string;
}

export interface InFlightItem {
  action_id: number;
  intent: string;
  run_at: string;
  kind: string;
  channel: string;
  target: string | null;
  department: string | null;
  overdue: boolean;
}

export interface AwaitingItem {
  person_id: number;
  full_name: string;
  role: string;
  awaiting_count: number;
  oldest_at: string | null;
  overdue: boolean;
}

/** Home's first-week card: a goal to set while none is, and the top
 * findings of the research setup ran. */
export interface FirstWeekCard {
  needs_goal: boolean;
  findings: { title: string; summary: string }[];
  // Setup was today and no morning brief has gone out yet.
  brief_tomorrow: boolean;
}

export interface NarrativePoint {
  text: string;
  // When the point first appeared today (ISO UTC).
  since?: string | null;
  // What the point is about, when Home can open it: an email in your own
  // inbox, or a card in Needs you.
  source?: PointSource | null;
}

// What a Right now being rewritten is doing (shown in its place): reading
// what moved, writing, checking each point. `new_mail`: emails from people
// the owner deals with since the served header (`since`) was written.
export interface NarrativeProgress {
  step: "reading" | "writing" | "checking";
  new_mail?: number;
  since?: string | null;
}

export interface PointSource {
  kind: "mail" | "alert";
  message_id?: string | null;
  thread_id?: string | null;
  decision_id?: number | null;
  alert_id?: number | null;
}

export interface MorningBriefItem {
  at: string;
  text: string;
}

export interface CalendarNextItem {
  title: string;
  // ISO UTC; null for an all-day event.
  start?: string | null;
  all_day?: boolean;
}

export interface Today {
  departments: DepartmentBriefItem[];
  people: PersonBriefItem[];
  proposals: ProposalItem[];
  // Executive-voice "what's going on" narrative for the briefing header.
  // Null/absent until the backend has generated one.
  narrative?: string | null;
  // When the served narrative was written (ISO UTC), and whether a fresher
  // one is being written right now — the page re-polls while it is.
  // Optional for older API builds + test mocks.
  narrative_generated_at?: string | null;
  narrative_stale?: boolean;
  // While narrative_stale: what the rewrite is doing.
  narrative_progress?: NarrativeProgress | null;
  // The same narrative split for Home's Right now card: the bold opener, the
  // points with when each first appeared today, the Move today line, and when
  // this reader last looked. Optional for older API builds + test mocks.
  narrative_lead?: string | null;
  narrative_points?: NarrativePoint[];
  narrative_move?: string | null;
  narrative_seen_at?: string | null;
  // When the served header was last found current (null while a fresher one
  // is being written), and the owner's "Also in" line: today's mail to their
  // own inbox from people they don't deal with. Optional for older API builds.
  narrative_checked_at?: string | null;
  inbox_also?: string[];
  inbox_also_total?: number;
  // The owner's own: today's delivered morning brief and the meetings still
  // ahead today.
  morning_brief?: MorningBriefItem | null;
  calendar_next?: CalendarNextItem[];
  // The install's first week (the principal's Home only): the first-week
  // card shows instead of a quiet day. Optional for older API builds.
  first_week?: boolean;
  first_week_card?: FirstWeekCard | null;
  // In-flight commitments (pending follow-ups/nudges) + people we're awaiting
  // a reply from. Optional/default-empty for older API builds + test mocks.
  in_flight?: InFlightItem[];
  awaiting?: AwaitingItem[];
  // Parked client slots in multi-client practice mode (2+ slots). Empty for
  // single-company installs. Optional for older API builds + test mocks.
  practice_clients?: ClientCockpitCard[];
  // The signed-in caller resolved to a Person id on the backend (via
  // x-caller-email). Lets the UI split proposals into "routed to me"
  // vs "across the team". Null when no caller could be resolved.
  // Optional to keep existing test mocks and older API builds compiling.
  caller_person_id?: number | null;
  // What the Executive's alert review did on its own since the last morning
  // brief — the "handled overnight" rail with Undo. Optional/default-empty.
  handled_overnight?: HandledItem[];
  // Lines grounding left out of your briefs in the last day (principal only).
  held_back?: HeldBackItem[];
}

export async function getToday(): Promise<Today> {
  // Never a cached copy: the header is re-polled while it is being rewritten.
  const res = await fetch(`${API_BASE}/today`, { cache: "no-store" });
  if (!res.ok) throw new Error(`Failed to load today: ${res.statusText}`);
  return res.json();
}

// The reader looked at Right now: its next view counts points as new only
// when they appeared after this. Best-effort; returns the time stored.
export async function markTodaySeen(): Promise<string | null> {
  const res = await fetch(`${API_BASE}/today/seen`, { method: "POST" });
  if (!res.ok) return null;
  const body = (await res.json()) as { seen_at?: string };
  return body.seen_at ?? null;
}

// The latest morning brief or end-of-day digest that didn't reach the owner,
// and what fixes it. Null while briefs are going out, and for anyone but the
// owner.
export interface BriefDeliveryNotice {
  brief: string;
  at: string;
  problem: string;
  fix: string;
  // False when it couldn't be written, so there is nothing to read.
  readable: boolean;
}

export async function getBriefDelivery(signal?: AbortSignal): Promise<BriefDeliveryNotice | null> {
  const res = await fetch(`${API_BASE}/today/brief-delivery`, { signal });
  if (!res.ok) throw new Error(`Failed to load brief delivery: ${res.statusText}`);
  return res.json();
}

// Solo only: today's top three, as the morning brief picks them. Null in
// team mode and for anyone but the owner. Loaded apart from /today because
// it may read the calendar (up to 4 s).
export interface TopThreeItem {
  key: string;
  kind: "commitment" | "goal" | "project";
  text: string;
  why: string;
  // "10:00–11:00" (local) when a calendar was read on a business day; ""
  // when no free block is left for it; null when no calendar was read.
  slot: string | null;
}

export interface TopThreeToday {
  items: TopThreeItem[];
}

export async function getTopThree(signal?: AbortSignal): Promise<TopThreeToday | null> {
  const res = await fetch(`${API_BASE}/today/top-three`, { signal });
  if (!res.ok) throw new Error(`Failed to load the top three: ${res.statusText}`);
  return res.json();
}

// Solo only: the latest completed weekly review. Null when none has run, in
// team mode and for anyone but the owner. The full review is its run page
// (/jobs/runs/{run_id}).
export interface WeeklyReviewSummary {
  run_id: string;
  completed_at: string;
  period: string;
  // Next week's top three, plain text.
  top_three: string[];
  // Shown when top_three is empty: the review's own note, or its first lines.
  excerpt: string;
}

export async function getWeeklyReview(signal?: AbortSignal): Promise<WeeklyReviewSummary | null> {
  const res = await fetch(`${API_BASE}/today/weekly-review`, { signal });
  if (!res.ok) throw new Error(`Failed to load the weekly review: ${res.statusText}`);
  return res.json();
}

// Mark an alert as read/ack/dismissed. Used by the briefing's
// Approve/Dismiss affordance to groom the "Needs you" queue: any
// non-unread status drops the alert from /today's proposals list.
export async function ackAlert(
  alertId: number,
  status: "read" | "ack" | "dismissed",
  opts: { muteTopic?: string | boolean } = {},
): Promise<void> {
  const body: Record<string, unknown> = { status };
  if (opts.muteTopic) body.mute_topic = opts.muteTopic;
  const res = await fetch(`${API_BASE}/alerts/${alertId}/ack`, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify(body),
  });
  if (!res.ok) throw new Error(`Failed to ack alert ${alertId}: ${res.statusText}`);
}

// Groom many alerts at once. The briefing sends explicit ids (it knows which
// cards the caller owns); `older_than_days` / `category` are for ops use.
export async function bulkAckAlerts(body: {
  status: "ack" | "dismissed";
  alert_ids?: number[];
  older_than_days?: number;
  category?: "action" | "monitoring";
}): Promise<{ count: number }> {
  const res = await fetch(`${API_BASE}/alerts/bulk-ack`, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify(body),
  });
  if (!res.ok) throw new Error(`Failed to bulk-ack alerts: ${res.statusText}`);
  return res.json();
}

// Hide a card from Home until `until`; it comes back on its own then.
// `null` brings it back now (the Undo).
export async function snoozeAlert(alertId: number, until: Date | null): Promise<void> {
  const res = await fetch(`${API_BASE}/alerts/${alertId}/snooze`, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ until: until ? until.toISOString() : null }),
  });
  if (!res.ok) throw new Error(`Failed to snooze alert ${alertId}: ${res.status} ${res.statusText}`);
}

// Run a failed scheduled run again (a check-in, a saved workflow on a
// cadence). It is queued now and delivers the way the scheduled run would.
export async function rerunWorkflowRun(runId: string): Promise<void> {
  const res = await fetch(`${API_BASE}/workflows/runs/${encodeURIComponent(runId)}/rerun`, {
    method: "POST",
  });
  if (!res.ok) {
    const body = await res.json().catch(() => ({}));
    throw new Error(typeof body?.detail === "string" ? body.detail : `Failed to run it again: ${res.statusText}`);
  }
}

// Undo for an autonomous close / expiry / dismiss: back to the live queue.
export async function reopenAlert(alertId: number): Promise<void> {
  const res = await fetch(`${API_BASE}/alerts/${alertId}/reopen`, { method: "POST" });
  // 409 = already open (not an Undo target any more); callers treat it as done.
  if (!res.ok) throw new Error(`Failed to reopen alert ${alertId}: ${res.status} ${res.statusText}`);
}

export interface AlertReviewSummary {
  reviewed: number;
  closed: number;
  changed: number;
  routed: number;
  nudged: number;
  escalated: number;
  drafted: number;
  merged: number;
  suggested: number;
  annotated: number;
}

// Run the Executive's relevance review on demand ("Re-check relevance").
export async function reviewAlerts(): Promise<AlertReviewSummary> {
  const res = await fetch(`${API_BASE}/alerts/review`, { method: "POST" });
  if (!res.ok) throw new Error(`Failed to run alert review: ${res.statusText}`);
  return res.json();
}

// Recent self-initiated Executive activity for the briefing rail.
// `kind` is a coarse classifier the UI uses to pick an icon/verb:
// "dm_sent" | "email_sent" | "nudge_sent" | "cadence_sent" |
// "workflow_resumed" | "proposal_routed" | "decision_logged" |
// "advice_given" | "action".
// A finished run ("workflow_done") also carries `detail`, one line on what
// came of it, and `artifact_id`, its write-up when it kept one.
export interface ActivityItem {
  kind: string;
  summary: string;
  actor: string;
  target: string | null;
  department: string | null;
  at: string;
  detail?: string | null;
  artifact_id?: string | null;
}

export interface ActivityResponse {
  items: ActivityItem[];
}

export async function getActivity(limit: number = 20): Promise<ActivityResponse> {
  const res = await fetch(`${API_BASE}/today/activity?limit=${limit}`);
  if (!res.ok) throw new Error(`Failed to load activity: ${res.statusText}`);
  return res.json();
}

// What the Executive did for the owner this month or week, counted from the
// record (GET /today/value). The owner's alone: anyone else gets null.
export interface ValueLine {
  key: string;
  label: string;
  count: number;
  previous: number;
}

export interface ValueDeliverable {
  run_id: string;
  title: string;
  workflow_name: string;
  finished_at: string;
}

export interface ValueSummary {
  period: "month" | "week";
  label: string;
  start: string;
  end: string;
  lines: ValueLine[];
  deliverables: ValueDeliverable[];
  deliverables_total: number;
}

export async function getValueSummary(
  period: "month" | "week" = "month",
  offset: number = 0,
): Promise<ValueSummary | null> {
  const res = await fetch(`${API_BASE}/today/value?period=${period}&offset=${offset}`);
  if (res.status === 403) return null;
  if (!res.ok) throw new Error(`Failed to load the summary: ${res.statusText}`);
  return res.json();
}

/** One day in the Pulse heartbeat heatmap. `date` is YYYY-MM-DD (UTC). */
export interface DailyActivityCount {
  date: string;
  count: number;
}

export interface DailyActivityResponse {
  /** Dense, oldest → newest; every calendar day present (count 0 when idle). */
  days: DailyActivityCount[];
}

export async function getActivityDaily(
  days: number = 90,
  signal?: AbortSignal,
): Promise<DailyActivityResponse> {
  const res = await fetch(`${API_BASE}/today/activity/daily?days=${days}`, { signal });
  if (!res.ok) throw new Error(`Failed to load activity heatmap: ${res.statusText}`);
  return res.json();
}

// ---------------------------------------------------------------------------
// Watch list (external-condition monitors)
// ---------------------------------------------------------------------------

export type WatchlistSignalType =
  | "stock"
  | "rss"
  | "vendor_status"
  | "query"
  | "edgar"
  | "page_watch";
export type WatchlistCadence = "real_time" | "15min" | "hourly" | "daily" | "weekly";
export type WatchlistMode = "active" | "dry_run";
export type WatchlistSeverity = "low" | "medium" | "high" | "urgent";
/** Who put the row on the watchlist. `research_proposed` = a pending suggestion. */
export type WatchlistOrigin = "manual" | "executive" | "research" | "research_proposed";
/** Why a research suggestion / watch was declined — each picks a different remedy. */
export type WatchDeclineReason = "not_relevant" | "too_noisy" | "wrong_source";

export interface WatchlistItem {
  id: number;
  slug: string;
  signal_type: string;
  target: string;
  config_json: Record<string, unknown>;
  trigger_json: Record<string, unknown>;
  cadence: string;
  severity_floor: WatchlistSeverity;
  severity_ceiling: WatchlistSeverity;
  route_to_specialist: string;
  route_to_department: string;
  route_to_person_id: number | null;
  mode: string;
  enabled: boolean;
  created_at: string;
  last_polled_at: string | null;
  last_fired_at: string | null;
  fired_count: number;
  dismiss_count: number;
  trust_score: number;
  notes: string;
  origin: WatchlistOrigin | string;
  /** Detail route only: how many of its recent alerts were dismissed. */
  noise?: WatchNoise;
}

/** A watch's last alerts (up to 8) since its noise question was last answered. */
export interface WatchNoise {
  recent_alerts: number;
  recent_dismissed: number;
  /** At least 6 of the last 8 were dismissed: ask whether to make it quieter. */
  noisy: boolean;
}

/** A watch written from a sentence (POST /watchlist/describe). Not saved. */
export interface WatchDraft {
  slug: string;
  signal_type: WatchlistSignalType | string;
  target: string;
  display_label: string;
  trigger: Record<string, unknown>;
  cadence: WatchlistCadence | string;
  mode: WatchlistMode | string;
  severity_floor: WatchlistSeverity;
  severity_ceiling: WatchlistSeverity;
  notes: string;
  watching: string;
  tell_you_when: string;
  how_often: string;
  how_loud: string;
}

export interface WatchlistSignal {
  id: number;
  watchlist_id: number;
  source_kind: string;
  source_external_id: string;
  captured_at: string;
  /** Upstream publish time (RSS pubDate, EDGAR filing date); null when the source has none. */
  published_at: string | null;
  normalized_summary: string;
  provenance_url: string;
  severity_hint: string;
  dedup_key: string;
  processed_at: string | null;
  processed_outcome: string | null;
  promoted_alert_id: number | null;
  raw_payload: Record<string, unknown>;
}

export interface WatchlistCreate {
  slug: string;
  signal_type: WatchlistSignalType | string;
  target: string;
  trigger?: Record<string, unknown>;
  config?: Record<string, unknown>;
  cadence?: WatchlistCadence | string;
  severity_floor?: WatchlistSeverity;
  severity_ceiling?: WatchlistSeverity;
  mode?: WatchlistMode | string;
  route_to_specialist?: string;
  notes?: string;
  display_label?: string;
}

export interface WatchlistPatch {
  enabled?: boolean;
  mode?: WatchlistMode | string;
  cadence?: WatchlistCadence | string;
  severity_floor?: WatchlistSeverity;
  severity_ceiling?: WatchlistSeverity;
  trigger?: Record<string, unknown>;
  notes?: string;
  /** Stop asking whether this watch is too noisy (for the alerts so far). */
  quiet_noise_nudge?: boolean;
}

/** Draft a watch from what the person typed. Throws with a plain reason. */
export async function describeWatch(text: string): Promise<WatchDraft> {
  const res = await fetch(`${API_BASE}/watchlist/describe`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ text }),
  });
  if (!res.ok) {
    throw new Error(await errorDetail(res, "Couldn't read that just now. Try again, or set it up by hand."));
  }
  return res.json();
}

/** The create body for a draft the person approved as it is. */
export function draftToCreate(draft: WatchDraft): WatchlistCreate {
  return {
    slug: draft.slug,
    signal_type: draft.signal_type,
    target: draft.target,
    display_label: draft.display_label,
    trigger: draft.trigger,
    cadence: draft.cadence,
    mode: draft.mode,
    severity_floor: draft.severity_floor,
    severity_ceiling: draft.severity_ceiling,
    notes: draft.notes,
  };
}

export async function listWatchlist(options: {
  enabledOnly?: boolean;
  signalType?: string;
} = {}): Promise<WatchlistItem[]> {
  const params = new URLSearchParams();
  if (options.enabledOnly) params.set("enabled_only", "true");
  if (options.signalType) params.set("signal_type", options.signalType);
  const qs = params.toString();
  const res = await fetch(`${API_BASE}/watchlist${qs ? `?${qs}` : ""}`);
  if (!res.ok) throw new Error(`Failed to load watchlist: ${res.statusText}`);
  return res.json();
}

export async function getWatchlistItem(slug: string): Promise<WatchlistItem> {
  const res = await fetch(`${API_BASE}/watchlist/${encodeURIComponent(slug)}`);
  if (!res.ok) throw new Error(`Failed to load watchlist entry: ${res.statusText}`);
  return res.json();
}

export async function getWatchlistSignals(
  slug: string,
  limit: number = 50,
): Promise<WatchlistSignal[]> {
  const res = await fetch(
    `${API_BASE}/watchlist/${encodeURIComponent(slug)}/signals?limit=${limit}`,
  );
  if (!res.ok) throw new Error(`Failed to load signals: ${res.statusText}`);
  return res.json();
}

export async function createWatchlistItem(body: WatchlistCreate): Promise<WatchlistItem> {
  const res = await fetch(`${API_BASE}/watchlist`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });
  if (!res.ok) {
    const text = await res.text().catch(() => "");
    throw new Error(`Failed to create watchlist entry: ${res.statusText}${text ? ` — ${text}` : ""}`);
  }
  return res.json();
}

export async function patchWatchlistItem(
  slug: string,
  patch: WatchlistPatch,
): Promise<WatchlistItem> {
  const res = await fetch(`${API_BASE}/watchlist/${encodeURIComponent(slug)}`, {
    method: "PATCH",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(patch),
  });
  if (!res.ok) {
    const text = await res.text().catch(() => "");
    throw new Error(`Failed to update watchlist entry: ${res.statusText}${text ? ` — ${text}` : ""}`);
  }
  return res.json();
}

export async function deleteWatchlistItem(
  slug: string,
  reason?: WatchDeclineReason,
): Promise<void> {
  const qs = reason ? `?reason=${encodeURIComponent(reason)}` : "";
  const res = await fetch(`${API_BASE}/watchlist/${encodeURIComponent(slug)}${qs}`, {
    method: "DELETE",
  });
  if (!res.ok) throw new Error(`Failed to delete watchlist entry: ${res.statusText}`);
}

/** Turn a research suggestion (origin=research_proposed, dry_run) into a live watch. */
export async function approveWatchSuggestion(slug: string): Promise<WatchlistItem> {
  const res = await fetch(`${API_BASE}/watchlist/${encodeURIComponent(slug)}/approve`, {
    method: "POST",
  });
  if (!res.ok) {
    const text = await res.text().catch(() => "");
    throw new Error(`Failed to approve suggestion: ${res.statusText}${text ? ` — ${text}` : ""}`);
  }
  return res.json();
}

export interface WatchDeclineResponse {
  slug: string;
  reason: string;
  /** "removed" (declined + deleted) or "kept_high_floor" (too_noisy → live, only high-severity signals surface). */
  result: "removed" | "kept_high_floor" | string;
}

/** Decline a research suggestion. The reason picks the remedy server-side. */
export async function declineWatchSuggestion(
  slug: string,
  reason: WatchDeclineReason,
): Promise<WatchDeclineResponse> {
  const res = await fetch(`${API_BASE}/watchlist/${encodeURIComponent(slug)}/decline`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ reason }),
  });
  if (!res.ok) {
    const text = await res.text().catch(() => "");
    throw new Error(`Failed to decline suggestion: ${res.statusText}${text ? ` — ${text}` : ""}`);
  }
  return res.json();
}

// How far it goes as you (PUT /delegation/reach): one dial over Act as me,
// the inbox watcher, Handle it for me and its level, and Everything.
export type ReachStep = "off" | "when_asked" | "inbox" | HandleItMode | "everything";

export async function setReach(step: ReachStep): Promise<DelegationSettings> {
  const res = await fetch(`${API_BASE}/delegation/reach`, {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ step }),
  });
  if (!res.ok) throw await delegationError(res, "Couldn't change how far it goes.");
  delegationChanged();
  return res.json();
}

// ---------------------------------------------------------------------------
// What it does for you (GET /what-it-may-do): read-only. What goes out
// without asking, as you and as the Executive, and each department's level,
// each with the setting that decides it. Shown beside the Delegate tabs
// (WhatItDoesPanel), which reloads it on DELEGATION_CHANGED.
// ---------------------------------------------------------------------------

// Fired after a setting the panel reads is saved, so it can show the change.
export const DELEGATION_CHANGED = "oe:delegation-changed";

function delegationChanged(): void {
  if (typeof window !== "undefined") window.dispatchEvent(new Event(DELEGATION_CHANGED));
}

export type MayDoOutcome = "goes" | "waits" | "always_waits" | "drafts" | "off";

export interface MayDoRow {
  id: string;
  what: string;
  outcome: MayDoOutcome;
  then: string;
  why: string;
  /** act_as_me | handle_it | take_the_lead | pause | department:<slug> | "" */
  setting: string;
  items: string[];
}

export interface MayDoSection {
  key: "as_you" | "executive" | "departments";
  title: string;
  available: boolean;
  unavailable: string;
  notes: string[];
  rows: MayDoRow[];
  footer: string;
  goes: number;
}

export interface WhatItMayDo {
  paused: boolean;
  sections: MayDoSection[];
}

export async function getWhatItMayDo(signal?: AbortSignal): Promise<WhatItMayDo | null> {
  const res = await fetch(`${API_BASE}/what-it-may-do`, { signal });
  if (res.status === 403 || res.status === 404) return null;
  if (!res.ok) throw new Error("Couldn't load what it does for you.");
  return res.json();
}

// ---------------------------------------------------------------------------
// Decisions / Trust Ledger (first-climb autonomy)
// ---------------------------------------------------------------------------

export interface DecisionInstance {
  id: number;
  decision_class: string;
  created_at: string;
  department: string;
  originating_session_id: string | null;
  proposed_payload_json: string;
  idempotency_key: string | null;
  gate_mode: string;
  approver_person_id: number | null;
  confidence: number | null;
  status: string;
  resolved_at: string | null;
  resolver_person_id: number | null;
  final_payload_json: string | null;
  external_event_id: string | null;
  reversal_reason: string | null;
  severity: string;
}

// Approve a proposal card that has no decision behind it: the server records
// who approved it, claims it and carries it out (alerts/approvals.py).
export async function approveAlert(alertId: number, editedBody?: string): Promise<AlertApproval> {
  const res = await fetch(`${API_BASE}/alerts/${alertId}/approve`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ edited_body: editedBody ?? null }),
  });
  if (!res.ok) {
    const text = await res.text().catch(() => "");
    throw new Error(`Failed to approve: ${res.statusText}${text ? ` — ${text}` : ""}`);
  }
  return res.json();
}

export async function getAlertApproval(approvalId: number): Promise<AlertApproval> {
  const res = await fetch(`${API_BASE}/alerts/approvals/${approvalId}`);
  if (!res.ok) throw new Error(`Failed to read approval ${approvalId}: ${res.statusText}`);
  return res.json();
}

// One decision, as its approver (or the owner) may see it; 404 otherwise.
export async function getDecision(id: number, signal?: AbortSignal): Promise<DecisionInstance> {
  const res = await fetch(`${API_BASE}/decisions/${id}`, { signal });
  if (!res.ok) throw new Error(`Couldn't load decision ${id}: ${res.statusText}`);
  return res.json();
}

export async function approveDecision(
  id: number,
  edits?: Record<string, unknown>,
): Promise<DecisionInstance> {
  const res = await fetch(`${API_BASE}/decisions/${id}/approve`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ edits: edits ?? null }),
  });
  if (!res.ok) {
    const text = await res.text().catch(() => "");
    throw new Error(`Failed to approve decision: ${res.statusText}${text ? ` — ${text}` : ""}`);
  }
  return res.json();
}

export async function rejectDecision(
  id: number,
  reason = "",
): Promise<DecisionInstance> {
  const res = await fetch(`${API_BASE}/decisions/${id}/reject`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ reason }),
  });
  if (!res.ok) {
    const text = await res.text().catch(() => "");
    throw new Error(`Failed to reject decision: ${res.statusText}${text ? ` — ${text}` : ""}`);
  }
  return res.json();
}

// Confirm something asked for in chat (an app_action card): the route says
// why in words when it can't be done, and that is what the card shows.
export async function approveAppAction(id: number): Promise<DecisionInstance> {
  const res = await fetch(`${API_BASE}/decisions/${id}/approve`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ edits: null }),
  });
  if (!res.ok) {
    const body = (await res.json().catch(() => ({}))) as { detail?: unknown };
    throw new Error(typeof body.detail === "string" ? body.detail : "That didn't go through.");
  }
  return res.json();
}


// ── Client-company slots (fractional / multi-client mode) ──────────────────

export interface ClientSlotSummary {
  slug: string;
  display_name: string;
  created_at: string | null;
  saved_at: string | null;
  origin?: string | null;
  has_state: boolean;
  has_mcp_config: boolean;
  doc_count: number;
  industry?: string;
  stage?: string;
  // Engagement metadata (practice-level, lives in meta.json).
  role?: string | null;
  status?: string | null;
  engagement_start?: string | null;
  renewal_date?: string | null;
  retainer?: string | null;
  hours_per_week?: number | null;
  primary_contact?: string | null;
  notes?: string | null;
}

export interface ClientsStatus {
  active: string | null;
  fixture_active: string | null;
  // True while the overnight rotation is switching contexts. Optional for
  // older API builds + test mocks.
  rotation_in_progress?: boolean;
  clients: ClientSlotSummary[];
}

export async function listClients(): Promise<ClientsStatus> {
  const res = await fetch(`${API_BASE}/clients`);
  if (!res.ok) throw new Error("Failed to list clients");
  return res.json() as Promise<ClientsStatus>;
}

export async function createClient(
  displayName: string,
  source: "current" | "blank",
): Promise<{ slug: string; display_name: string; active: boolean }> {
  const res = await fetch(`${API_BASE}/clients`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ display_name: displayName, source }),
  });
  if (!res.ok) {
    const err = await res.json().catch(() => ({ detail: res.statusText }));
    throw new Error(err.detail ?? "Failed to create client");
  }
  return res.json();
}

export async function activateClient(
  slug: string,
): Promise<{ slug: string; previous?: string | null; mcp_config_changed?: boolean }> {
  const res = await fetch(
    `${API_BASE}/clients/${encodeURIComponent(slug)}/activate`,
    { method: "POST" },
  );
  if (!res.ok) {
    const err = await res.json().catch(() => ({ detail: res.statusText }));
    throw new Error(err.detail ?? "Failed to activate client");
  }
  return res.json();
}

export async function saveActiveClient(): Promise<{ slug: string; saved: boolean }> {
  const res = await fetch(`${API_BASE}/clients/save`, { method: "POST" });
  if (!res.ok) {
    const err = await res.json().catch(() => ({ detail: res.statusText }));
    throw new Error(err.detail ?? "Failed to save client");
  }
  return res.json();
}

export async function deleteClient(slug: string): Promise<void> {
  const res = await fetch(`${API_BASE}/clients/${encodeURIComponent(slug)}`, {
    method: "DELETE",
  });
  if (!res.ok) {
    const err = await res.json().catch(() => ({ detail: res.statusText }));
    throw new Error(err.detail ?? "Failed to delete client");
  }
}

// Engagement intake: grounded AI draft of a real client from intake notes.

export interface ClientDraftBundle {
  profile: { name: string; industry?: string; stage?: string; [k: string]: unknown };
  people: { full_name: string; role?: string; is_principal?: boolean }[];
  departments: { slug: string; title: string }[];
  memory?: {
    decisions?: unknown[];
    initiatives?: unknown[];
    advice_given?: unknown[];
    alerts?: unknown[];
  };
  docs: { filename: string; content: string }[];
}

export interface ClientDraftResult {
  suggested_name: string;
  display_name: string;
  bundle: ClientDraftBundle;
}

export async function generateClientDraft(
  description: string,
  files: File[] = [],
): Promise<ClientDraftResult> {
  // multipart so intake material can include attachments (PDF/Word/Excel/CSV/
  // text). No Content-Type header — the browser sets the multipart boundary.
  const form = new FormData();
  form.append("description", description);
  for (const file of files) form.append("files", file, file.name);

  const res = await fetch(`${API_BASE}/clients/generate`, {
    method: "POST",
    body: form,
  });
  if (!res.ok) {
    const err = await res.json().catch(() => ({ detail: res.statusText }));
    throw new Error(err.detail ?? "Failed to generate client draft");
  }
  return res.json() as Promise<ClientDraftResult>;
}

export async function createClientFromDraft(
  displayName: string,
  bundle: ClientDraftBundle,
  intakeDescription: string,
): Promise<{ slug: string; display_name: string; active: boolean }> {
  const res = await fetch(`${API_BASE}/clients`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      display_name: displayName,
      source: "generated",
      bundle,
      intake_description: intakeDescription,
    }),
  });
  if (!res.ok) {
    const err = await res.json().catch(() => ({ detail: res.statusText }));
    throw new Error(err.detail ?? "Failed to create client from draft");
  }
  return res.json();
}


// ── Practice layer: engagement metadata + cross-client cockpit ─────────────

// Mirrors clients.cockpit.ClientCockpitCard.
export interface ClientCockpitCard {
  slug: string;
  display_name: string;
  is_active: boolean;
  role?: string | null;
  status?: string | null;
  renewal_date?: string | null;
  days_to_renewal?: number | null;
  primary_contact?: string | null;
  pending_actions?: number | null;
  overdue_actions?: number | null;
  awaiting_replies?: number | null;
  unread_alerts?: number | null;
  saved_at?: string | null;
  has_state: boolean;
  error: boolean;
}

export async function getClientsCockpit(): Promise<{
  clients: ClientCockpitCard[];
  generated_at: string;
}> {
  const res = await fetch(`${API_BASE}/clients/cockpit`);
  if (!res.ok) throw new Error("Failed to load practice cockpit");
  return res.json();
}

export interface ClientMetaPatch {
  role?: string;
  status?: string;
  engagement_start?: string;
  renewal_date?: string;
  retainer?: string;
  hours_per_week?: number;
  primary_contact?: string;
  notes?: string;
}

export async function updateClientMeta(
  slug: string,
  patch: ClientMetaPatch,
): Promise<Record<string, unknown>> {
  const res = await fetch(`${API_BASE}/clients/${encodeURIComponent(slug)}`, {
    method: "PATCH",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(patch),
  });
  if (!res.ok) {
    const err = await res.json().catch(() => ({ detail: res.statusText }));
    throw new Error(err.detail ?? "Failed to update client");
  }
  return res.json();
}

// ── Take the lead (Delegate → Take the lead) ────────────────

export type LeadRuleKind = "person" | "domain" | "words" | "amount";

export interface LeadRule {
  id: number;
  kind: LeadRuleKind;
  value: string;
}

// An action it was allowed in training, and the edit it keeps as an example.
export interface LeadLearned {
  id: number;
  label: string;
  // The feature it learned it in ("take_the_lead" for now).
  feature: string;
  example: Record<string, string>;
  uses: number;
  created_at: string;
}

// An action you approved unchanged often enough that it suggests allowing it.
export interface LeadSuggested {
  key: string;
  label: string;
  approvals: number;
}

export interface TakeTheLead {
  enabled: boolean;
  training: boolean;
  ask_first: { kind: string; label: string; hint: string; on: boolean }[];
  rules: LeadRule[];
  learned: LeadLearned[];
  suggested: LeadSuggested[];
  available: boolean;
  paused: boolean;
}

async function leadError(res: Response, fallback: string): Promise<Error> {
  try {
    const body = await res.json();
    if (typeof body?.detail === "string") return new Error(body.detail);
    if (typeof body?.detail?.message === "string") return new Error(body.detail.message);
  } catch {
    // fall through
  }
  return new Error(fallback);
}

// null for anyone but the owner (403) or a backend without it (404).
export async function getTakeTheLead(signal?: AbortSignal): Promise<TakeTheLead | null> {
  const res = await fetch(`${API_BASE}/take-the-lead`, { signal });
  if (res.status === 403 || res.status === 404) return null;
  if (!res.ok) throw await leadError(res, "Couldn't load Take the lead.");
  return res.json();
}

export async function setTakeTheLead(update: {
  enabled?: boolean;
  training?: boolean;
  ask_first?: Record<string, boolean>;
}): Promise<TakeTheLead> {
  const res = await fetch(`${API_BASE}/take-the-lead`, {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(update),
  });
  if (!res.ok) throw await leadError(res, "Couldn't change Take the lead.");
  delegationChanged();
  return res.json();
}

export async function addCompanyLeadRule(kind: LeadRuleKind, value: string): Promise<TakeTheLead> {
  const res = await fetch(`${API_BASE}/take-the-lead/rules`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ kind, value }),
  });
  if (!res.ok) throw await leadError(res, "Couldn't add the rule.");
  delegationChanged();
  return res.json();
}

export async function deleteCompanyLeadRule(id: number): Promise<TakeTheLead> {
  const res = await fetch(`${API_BASE}/take-the-lead/rules/${id}`, { method: "DELETE" });
  if (!res.ok) throw await leadError(res, "Couldn't remove the rule.");
  delegationChanged();
  return res.json();
}

export async function allowLeadSuggestion(key: string): Promise<TakeTheLead> {
  const res = await fetch(`${API_BASE}/take-the-lead/learned`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ key }),
  });
  if (!res.ok) throw await leadError(res, "Couldn't allow it.");
  delegationChanged();
  return res.json();
}

export async function removeLeadLearned(id: number): Promise<TakeTheLead> {
  const res = await fetch(`${API_BASE}/take-the-lead/learned/${id}`, { method: "DELETE" });
  if (!res.ok) throw await leadError(res, "Couldn't remove it.");
  delegationChanged();
  return res.json();
}

// A field a Take the lead card lets you change before approving.
export interface LeadCardField {
  field: string;
  label: string;
  long: boolean;
  value: string;
}

// What a Take the lead card holds (its decision's payload), for the card's
// Edit and Approve + allow. Only its approver and the owner can read it.
export interface LeadCardPayload {
  summary: string;
  reason: string;
  kind: string;
  fields: LeadCardField[];
  allow?: { key: string; label: string };
}

export async function getLeadCard(id: number, signal?: AbortSignal): Promise<LeadCardPayload> {
  const res = await fetch(`${API_BASE}/decisions/${id}`, { signal });
  if (!res.ok) throw await leadError(res, "Couldn't load this card.");
  const instance: DecisionInstance = await res.json();
  const payload = JSON.parse(instance.proposed_payload_json || "{}");
  return {
    summary: String(payload.summary ?? ""),
    reason: String(payload.reason ?? ""),
    kind: String(payload.kind ?? ""),
    fields: Array.isArray(payload.fields) ? payload.fields : [],
    allow: payload.allow && typeof payload.allow.key === "string" ? payload.allow : undefined,
  };
}

// What a team member's held chat action holds (a department_action
// decision): who asked, why it waited, and every field of the call in full.
// Only its approver and the owner can read it.
export interface HeldActionPayload {
  summary: string;
  reason: string;
  requestedBy: string;
  details: { field: string; value: string }[];
}

export async function getHeldAction(id: number, signal?: AbortSignal): Promise<HeldActionPayload> {
  const res = await fetch(`${API_BASE}/decisions/${id}`, { signal });
  if (!res.ok) throw await leadError(res, "Couldn't load this card.");
  const instance: DecisionInstance = await res.json();
  const payload = JSON.parse(instance.proposed_payload_json || "{}");
  const details = Array.isArray(payload.details) ? payload.details : [];
  return {
    summary: String(payload.summary ?? ""),
    reason: String(payload.reason ?? ""),
    requestedBy: String(payload.requested_by ?? ""),
    details: details.map((d: { field?: unknown; value?: unknown }) => ({
      field: String(d.field ?? ""),
      value: String(d.value ?? ""),
    })),
  };
}

// Approve a Take the lead card: ``input`` changes its editable fields first,
// ``allow`` (training cards, the owner's) lets it do this from now on.
export async function approveLeadCard(
  id: number,
  edits: { input?: Record<string, string>; allow?: boolean },
): Promise<DecisionInstance> {
  const res = await fetch(`${API_BASE}/decisions/${id}/approve`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ edits }),
  });
  if (!res.ok) throw await leadError(res, "Couldn't approve it.");
  return res.json();
}

export async function setLeadAsYou(enabled: boolean): Promise<DelegationSettings> {
  const res = await fetch(`${API_BASE}/delegation/take-the-lead`, {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ enabled }),
  });
  if (!res.ok) throw await delegationError(res, "Couldn't change Take the lead as you.");
  delegationChanged();
  return res.json();
}

export async function getMyLeadRules(signal?: AbortSignal): Promise<LeadRule[]> {
  const res = await fetch(`${API_BASE}/delegation/take-the-lead/rules`, { signal });
  if (!res.ok) throw await delegationError(res, "Couldn't load your rules.");
  return ((await res.json()) as { rules: LeadRule[] }).rules;
}

export async function addMyLeadRule(kind: LeadRuleKind, value: string): Promise<LeadRule[]> {
  const res = await fetch(`${API_BASE}/delegation/take-the-lead/rules`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ kind, value }),
  });
  if (!res.ok) throw await delegationError(res, "Couldn't add the rule.");
  delegationChanged();
  return ((await res.json()) as { rules: LeadRule[] }).rules;
}

export async function deleteMyLeadRule(id: number): Promise<LeadRule[]> {
  const res = await fetch(`${API_BASE}/delegation/take-the-lead/rules/${id}`, { method: "DELETE" });
  if (!res.ok) throw await delegationError(res, "Couldn't remove the rule.");
  delegationChanged();
  return ((await res.json()) as { rules: LeadRule[] }).rules;
}

// ── Custom tools (Settings → Advanced → Custom tools) ───────────────────────
// Scripts the Executive kept to run again by name. The owner's alone.

export interface SavedTool {
  name: string;
  description: string;
  enabled: boolean;
  version: number;
  uses_tools: string[];
  origin: string;
  created_at: string;
  updated_at: string;
  // The version workflows may run (the owner turned it on), or null.
  workflow_version?: number | null;
  // "script" or "python" (a kept Python job: chat only). Absent on an older backend.
  kind?: "script" | "python";
}

export interface SavedToolVersion {
  version: number;
  description: string;
  script: string;
  uses_tools: string[];
  origin: string;
  created_at: string;
}

export interface SavedToolRun {
  version: number;
  ok: boolean;
  calls: number;
  duration_ms: number;
  origin: string;
  at: string;
}

export interface SavedToolDetail extends SavedTool {
  script: string;
  versions: SavedToolVersion[];
  runs: SavedToolRun[];
}

async function savedToolError(res: Response, fallback: string): Promise<Error> {
  try {
    const body = await res.json();
    if (typeof body?.detail === "string") return new Error(body.detail);
  } catch {
    // not JSON
  }
  return new Error(fallback);
}

/** Null when the caller isn't the owner (403). */
export async function listSavedTools(
  signal?: AbortSignal,
): Promise<{ enabled: boolean; tools: SavedTool[] } | null> {
  const res = await fetch(`${API_BASE}/saved-tools`, { signal });
  if (res.status === 403) return null;
  if (!res.ok) throw await savedToolError(res, "Couldn't load the custom tools.");
  return res.json();
}

export async function getSavedTool(name: string, signal?: AbortSignal): Promise<SavedToolDetail> {
  const res = await fetch(`${API_BASE}/saved-tools/${encodeURIComponent(name)}`, { signal });
  if (!res.ok) throw await savedToolError(res, "Couldn't load that tool.");
  return res.json();
}

export async function setSavedToolEnabled(name: string, enabled: boolean): Promise<SavedToolDetail> {
  return updateSavedTool(name, { enabled });
}

/** Turn `version` (the one shown to the owner) on for workflows, or
 * workflows off (null). Naming the version means a newer one the Executive
 * saved meanwhile is never approved by accident. */
export async function setSavedToolWorkflows(name: string, version: number | null): Promise<SavedToolDetail> {
  return updateSavedTool(name, version == null ? { workflows: false } : { workflows: true, version });
}

async function updateSavedTool(
  name: string,
  update: { enabled?: boolean; workflows?: boolean; version?: number },
): Promise<SavedToolDetail> {
  const res = await fetch(`${API_BASE}/saved-tools/${encodeURIComponent(name)}`, {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(update),
  });
  if (!res.ok) throw await savedToolError(res, "Couldn't change that tool.");
  return res.json();
}

export async function rollbackSavedTool(name: string, version: number): Promise<SavedToolDetail> {
  const res = await fetch(`${API_BASE}/saved-tools/${encodeURIComponent(name)}/rollback`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ version }),
  });
  if (!res.ok) throw await savedToolError(res, "Couldn't switch the version.");
  return res.json();
}