Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

260 KB
Raw Blame
import "./generated.augment";
import type {
  Adapter,
  CloudMcpServerRelayDesignation,
  CloudRunSource,
  ExecutionMode,
  McpServerConnection,
  ModelAccess,
  PrAuthorshipMode,
  SourceProduct,
  SourceType,
  StoredLogEntry,
  TaskClientProvenance,
  TaskRunArtifactMetadata,
} from "@posthog/shared";
import {
  buildCloudTaskConfigOptions,
  type CloudTaskConfigOption,
  DISMISSAL_REASON_OPTIONS,
  type DismissalReasonOptionValue,
  type GatewayModel,
  getCloudTaskGatewayUrl,
  isSupportedReasoningEffort,
  normalizeGatewayModelsResponse,
  RESOLVE_REASON_OPTIONS,
  type ReportStateReason,
  type ResolveReasonOptionValue,
  resolveCloudInitialPermissionMode,
} from "@posthog/shared";
import type {
  ActionabilityJudgmentArtefact,
  AvailableSuggestedReviewer,
  AvailableSuggestedReviewersResponse,
  ChannelFeedMessage,
  ChannelFeedMessageEvent,
  CodeReferenceArtefact,
  CommitArtefact,
  CommitDiffResponse,
  DismissalArtefact,
  LineReferenceArtefact,
  NoteArtefact,
  OrganizationMemberBasic,
  PriorityJudgmentArtefact,
  ProvisionedTaskChannels,
  RankingHead,
  RankingModelResult,
  RankingScoreArtefact,
  RepoSelectionArtefact,
  SafetyJudgmentArtefact,
  SandboxCustomImage,
  SandboxEnvironment,
  SandboxEnvironmentInput,
  Signal,
  SignalFindingArtefact,
  SignalProcessingStateResponse,
  SignalReport,
  SignalReportArtefact,
  SignalReportArtefactsResponse,
  SignalReportRefundReason,
  SignalReportSectionCounts,
  SignalReportSectionCountsParams,
  SignalReportSignalsResponse,
  SignalReportStatus,
  SignalReportsQueryParams,
  SignalReportsResponse,
  SignalTeamConfig,
  SignalUserAutonomyConfig,
  SlackChannelsQueryParams,
  SlackChannelsResponse,
  SpaceSetupInput,
  SpaceSetupStarted,
  SuggestedReviewersArtefact,
  SuggestedReviewerWriteEntry,
  Task,
  TaskActivityMarkReadResult,
  TaskActivityPage,
  TaskActivityReadMarker,
  TaskChannel,
  TaskMention,
  TaskRun,
  TaskRunArtefact,
  TaskRunArtifact,
  TaskSearchResultRun,
  TaskThreadMessage,
  UserBasic,
  WorkClaimArtefact,
  WorkReleaseArtefact,
} from "@posthog/shared/domain-types";
import { buildPosthogProjectHeaderRecord } from "@posthog/shared/posthog-property-headers";
import {
  spaceSetupInputSchema,
  spaceSetupStartedSchema,
} from "@posthog/shared/schemas";
import {
  activitySection,
  compactCount,
  dailySparkLabels,
  dailySparkPoints,
  decorateFlagPreview,
  decorateSurveyPreview,
  type EvidencePreview,
  type ExperimentMetricQueryResult,
  experimentMetricQueries,
  formatDay,
  gridRows,
  hogqlEscape,
  referencedCohortIds,
  shapeActionPreview,
  shapeCohortPreview,
  shapeDashboardPreview,
  shapeErrorIssuePreview,
  shapeEvaluationPreview,
  shapeEventDefinitionPreview,
  shapeExperimentExposureChart,
  shapeExperimentPreview,
  shapeExperimentResults,
  shapeFlagPreview,
  shapeInboxReportPreview,
  shapePersonPreview,
  shapeRecordingPreview,
  shapeSurveyPreview,
  shapeTicketPreview,
  shapeTracePreview,
} from "./evidence-previews";
import {
  ApiRequestError,
  buildApiFetcher,
  type FetchImplementation,
  requestErrorStatus,
} from "./fetcher";
import { type ResolvedPerson, targetedDistinctIds } from "./flag-audience";
import { createApiClient, type Schemas } from "./generated";
import type {
  McpAgentGrantScope,
  McpAuditCounts,
  McpAuditEvent,
  McpAuditPage,
  McpAuditQuickFilter,
  McpGatewayInstallSharingOptions,
  McpGatewayMemberSummary,
  McpGatewayPolicyScope,
  McpGatewayServer,
  McpGatewayServerUpdate,
  McpResolvedToolPolicy,
  McpServiceAccount,
  McpServiceAccountStatus,
  McpServiceAccountWithToken,
  McpToolPolicyEntry,
  TeamMcpGatewayConfig,
  TeamMcpGatewayConfigUpdate,
} from "./mcp-gateway";
import {
  type ContextWikiPageProposal,
  type ContextWikiProposalApplyResult,
  contextWikiProposalApplyResultSchema,
  contextWikiProposalsSchema,
} from "./schemas";
import type { SpendAnalysisResponse } from "./spend-analysis";
import { parseUserSpendLimit, type UserSpendLimit } from "./spend-limit";
import {
  normalizeTaskResponse,
  normalizeTaskRunArtifact,
  normalizeTaskRunResponse,
  type TaskRunArtifactDTO,
  type TaskSummariesResponse,
  type TaskSummaryDTO,
} from "./task-normalization";

interface HogQLGrid {
  results: unknown[][];
  columns: string[];
}

export type * from "./mcp-gateway";
export type { ContextWikiPageProposal } from "./schemas";
export interface ApiClientLogger {
  warn(...args: unknown[]): void;
}

let log: ApiClientLogger = { warn: () => {} };

export function setPosthogApiClientLogger(logger: ApiClientLogger): void {
  log = logger;
}

// Host build version, set by the host at boot (default "unknown"); avoids a
// build-time global so the package typechecks standalone and across importers.
let clientAppVersion = "unknown";
let taskClientProvenance: TaskClientProvenance = "posthog_desktop";

export function setPosthogApiClientAppVersion(version: string): void {
  clientAppVersion = version;
}

export function setPosthogApiClientTaskClientProvenance(
  provenance: TaskClientProvenance,
): void {
  taskClientProvenance = provenance;
}

export interface PostHogAPIClientOptions {
  fetch?: FetchImplementation;
  appVersion?: string;
  userAgent?: string | null;
  githubConnectFrom?: string;
  taskClientProvenance?: TaskClientProvenance;
}

export function getPosthogApiClientAppVersion(): string {
  return clientAppVersion;
}

/**
 * A scout endpoint answered with a non-2xx. Carries the status so a caller can tell a
 * refusal it has to live with — 403 for a member without `signal_scout:write`, 404 for a
 * stale project id — from a real outage worth retrying or reporting.
 */
export class ScoutRequestError extends Error {
  constructor(
    readonly status: number,
    subPath: string,
    statusText: string,
  ) {
    super(`Scout request failed (${subPath}): ${statusText}`);
    this.name = "ScoutRequestError";
  }
}

export class SandboxCustomImagesDisabledError extends Error {
  constructor(message?: string) {
    super(message ?? "Custom sandbox images are not enabled");
    this.name = "SandboxCustomImagesDisabledError";
  }
}

export type UsageLimitType = "burst" | "sustained" | null;

// Stable message so callers recognize this after a saga reduces the error to a string.
export const CLOUD_USAGE_LIMIT_ERROR_MESSAGE = "Cloud usage limit reached";
export const DESKTOP_BILLING_LIMIT_ERROR_CODE =
  "posthog_code_billing_limit_exceeded";

export const SESSION_LOGS_MAX_PAGE_SIZE = 5000;
export const SESSION_LOGS_PAGE_TIMEOUT_MS = 30_000;
// The task list endpoint caps a page at this many rows (TasksPagination.max_limit).
export const TASK_LIST_MAX_PAGE_SIZE = 100;

export interface TaskRunSessionLogsResult {
  entries: StoredLogEntry[];
  complete: boolean;
  truncatedHeadCount: number;
}

interface RecordingExportRow {
  id: number;
  has_content?: boolean;
  export_context?: {
    start_offset_s?: number | null;
    end_offset_s?: number | null;
    timestamp?: number | null;
    duration?: number | null;
    video_duration_s?: number | null;
    truncated?: boolean | null;
    inactivity_periods?: Array<{
      ts_from_s?: number | null;
      ts_to_s?: number | null;
      active?: boolean | null;
      recording_ts_from_s?: number | null;
      recording_ts_to_s?: number | null;
    }> | null;
  } | null;
}

/**
 * One stretch of the session, and where it landed in the rendered clip. An
 * idle stretch is dropped from the render, so it occupies no clip time and its
 * two clip values are equal.
 */
export interface RecordingClipSegment {
  /** Session time the stretch covers, in seconds from the session start. */
  sessionFromSeconds: number;
  sessionToSeconds: number | null;
  /** Where the stretch sits in the rendered clip, in seconds. */
  clipFromSeconds: number;
  clipToSeconds: number;
  active: boolean;
}

/** A rendered mp4 of a session recording. */
export interface RecordingExport {
  id: number;
  /** Where the clip starts in the session, in seconds from the session start. */
  startOffsetSeconds: number;
  /** Where the clip ends in the session. Null when the render did not record it. */
  endOffsetSeconds: number | null;
  /** Rendered length of the clip. Null on a render that did not record it. */
  clipDurationSeconds: number | null;
  /** The render stopped early, so the clip can end before the session does. */
  truncated: boolean;
  /**
   * Session time to clip time, stretch by stretch. The render drops the idle
   * stretches of a session, so clip time runs behind session time by however
   * much idle time came before it. Empty on a render that kept every stretch.
   */
  segments: RecordingClipSegment[];
}

type SessionLogsPage =
  | { ok: true; entries: StoredLogEntry[]; headers: Headers }
  | { ok: false; status: number; statusText: string };

export interface TaskRunSessionLogsPage {
  entries: StoredLogEntry[];
  hasMore: boolean;
  matchingCount: number | null;
}

export interface TaskUsage {
  token_cost_usd: number;
  compute_cost_usd: number;
  total_cost_usd: number;
}

export interface TaskListOptions {
  repository?: string;
  createdBy?: number;
  originProduct?: string;
  internal?: boolean;
  channel?: string;
  /** Case-insensitive substring match over task title, description, and number. */
  search?: string;
  /**
   * Ask for the basic list payload: a summary shape with heavy fields dropped. Defaults to
   * false. A surface that does not render the description sets this to skip the field that
   * dominates the list payload.
   */
  basic?: boolean;
  /** Filter by the status of the task's most recent run. */
  status?: string;
  /** Filter by the state of the latest run's pull request (open/draft/merged/closed). */
  prState?: string;
  /** Filter by the CI rollup on the latest run's pull request (passing/failing/pending/none). */
  ciStatus?: string;
  /** List only tasks the requesting user has pinned. */
  pinned?: boolean;
  /**
   * List only tasks from any of these sources, in the desktop source filter's words. Filtering on
   * the server keeps sources the user hid, such as scheduled runs, from filling the page.
   */
  sources?: readonly string[];
  /** Filter to tasks with a thread comment from this user ID. */
  commentedBy?: number;
  /** Filter to tasks whose thread mentions this user ID. */
  mentions?: number;
  /** List only archived tasks; the server excludes them by default. */
  archived?: boolean;
  /** Caller-side cap for surfaces that only show the newest few. */
  limit?: number;
  /**
   * Which end of the list the page is cut from. A surface that asks for a short page and means
   * "what has been happening here" has to say so, or the server hands back the newest-created
   * few and a long-running session never makes the page.
   */
  ordering?: "-last_activity_at" | "-created_at";
  /** Zero-based offset for fetching a later task-list page. */
  offset?: number;
}

export interface TaskSearchResult {
  id: string;
  kind: "task" | "pull_request" | "artifact" | "channel" | "canvas";
  title: string;
  subtitle: string;
  task_id: string | null;
  task_run_id: string | null;
  channel_id: string | null;
  created_by?: UserBasic | null;
  origin_product?: string | null;
  latest_run?: TaskSearchResultRun | null;
  updated_at: string;
  metadata: Record<string, unknown>;
}

/**
 * The effective AI run defaults for the signed-in user in a project, as resolved
 * by the tasks backend: their own preference over the project default. `source`
 * says which level supplied them, and is `"none"` when neither is set.
 */
export interface TaskRunDefaults {
  runtime: string;
  runtime_adapter: string | null;
  model: string | null;
  reasoning_effort: string | null;
  source: "user" | "team" | "none";
}

export const NO_TASK_RUN_DEFAULTS: TaskRunDefaults = {
  runtime: "acp",
  runtime_adapter: null,
  model: null,
  reasoning_effort: null,
  source: "none",
};

/**
 * A stored preference triple. All three null means the level is unset and the one
 * below it applies — a personal preference falls back to the project default, and
 * the project default to each surface's built-in model.
 */
export interface TaskRunPreferences {
  runtime: string | null;
  runtime_adapter: string | null;
  model: string | null;
  reasoning_effort: string | null;
}

export const NO_TASK_RUN_PREFERENCES: TaskRunPreferences = {
  runtime: null,
  runtime_adapter: null,
  model: null,
  reasoning_effort: null,
};

/** The signed-in user's defaults for new tasks. Null means never set. */
export interface TaskDefaults {
  start_in_plan_mode: boolean | null;
  auto_publish_cloud_runs: boolean | null;
}

/** What the signed-in user has stored for this project, and what it resolves to. */
export interface MyTaskRunConfig {
  preferences: TaskRunPreferences;
  resolved: TaskRunDefaults;
  taskDefaults: TaskDefaults;
}

export interface TaskSessionStorageAccess {
  id: string;
  download_url: string | null;
  content_sha256: string | null;
}

/**
 * The commentable resources this client knows how to address. `scope` is a
 * free-form column on the backend `Comment` model, so adding a resource is a
 * new member here plus a caller — no migration and no endpoint.
 */
export const COMMENT_SCOPES = ["task_artifact", "canvas", "task"] as const;
export type CommentScope = (typeof COMMENT_SCOPES)[number];

export type SuggestedReviewerEdit = {
  action: Extract<
    NonNullable<Schemas.SignalReportArtefactWrite["action"]>,
    "add" | "remove"
  >;
  targets: NonNullable<Schemas.SignalReportArtefactWrite["targets"]>;
};

/** Named `Resource*` so it never collides with the DOM's global `Comment`.
 * Optimistic rows do not have a server version yet, while item_context is a
 * real JSON value despite the generated serializer's historically narrow type. */
export type ResourceComment = Omit<Schemas.Comment, "version"> & {
  version?: number;
};

export interface CreateResourceCommentRequest {
  scope: CommentScope;
  itemId: string;
  content: string;
  context: unknown;
  sourceCommentId?: string;
  mentions?: number[];
}

/** Thrown when the backend rejects a cloud run with a 429 usage-limit error. */
export class CloudUsageLimitError extends Error {
  limitType: UsageLimitType;
  resetAt: string | null;
  constructor(params: { limitType: UsageLimitType; resetAt: string | null }) {
    super(CLOUD_USAGE_LIMIT_ERROR_MESSAGE);
    this.name = "CloudUsageLimitError";
    this.limitType = params.limitType;
    this.resetAt = params.resetAt;
  }
}

export const MCP_CATEGORIES = [
  { id: "all", label: "All" },
  { id: "business", label: "Business Operations" },
  { id: "data", label: "Data & Analytics" },
  { id: "design", label: "Design & Content" },
  { id: "dev", label: "Developer Tools & APIs" },
  { id: "infra", label: "Infrastructure" },
  { id: "productivity", label: "Productivity & Collaboration" },
] as const;

import type {
  McpApprovalState,
  McpAuthType,
  McpCategory,
  McpInstallationTool,
  McpRecommendedServer,
  McpServerInstallation,
} from "./types";
export type {
  McpApprovalState,
  McpAuthType,
  McpCategory,
  McpInstallationTool,
  McpRecommendedServer,
  McpServerInstallation,
};

export type Evaluation = Schemas.Evaluation;

export type GithubInstallationStatus = "connected" | "unavailable";

export type CodexIntegrationStatus =
  | "not_connected"
  | "connected"
  | "reauth_required";

/** `GET /api/users/@me/integrations/codex/`: the ChatGPT account PostHog holds for the user's cloud Codex runs. */
export interface UserCodexIntegration {
  status: CodexIntegrationStatus;
  plan_type: string | null;
  email: string | null;
  connected_at: string | null;
}

/** The `tokens` object of the `auth.json` that `codex login` writes. */
export interface CodexAuthTokens {
  access_token: string;
  refresh_token: string;
  id_token?: string | null;
}

export interface UserGitHubIntegration {
  id: string;
  kind: "github";
  installation_id: string;
  repository_selection?: string | null;
  account?: {
    type?: string | null;
    name?: string | null;
  } | null;
  github_login?: string | null;
  uses_shared_installation?: boolean;
  /** False when disconnecting would also uninstall the App from GitHub. */
  installation_shared?: boolean;
  installation_status?: GithubInstallationStatus;
  created_at?: string;
}

/** `unidentified` means the requester could not be resolved, so approval can never
 * be detected and the user has to restart the connect flow. */
export type GithubInstallRequestStatus =
  | "pending"
  | "approved"
  | "unidentified";

/** A personal GitHub App install awaiting (or granted) org-owner approval; the
 * durable server-side counterpart to the in-flight connect spinner. Mirrors
 * `GitHubInstallRequest` on the backend. */
export interface GithubInstallRequestItem {
  id: string;
  github_login: string;
  status: GithubInstallRequestStatus;
  installation_id: string | null;
  account_login?: string | null;
  account_type?: string | null;
  requested_at: string;
  resolved_at: string | null;
}

export interface GithubInstallRequestsResponse {
  results: GithubInstallRequestItem[];
  /** App install page with no PostHog state, for an org owner to open. */
  install_url?: string | null;
}

export interface LlmSkillCreatedBy {
  id?: number;
  email?: string | null;
  first_name?: string | null;
  last_name?: string | null;
}

interface LlmSkillFileManifest {
  path: string;
  content_type: string;
}

export interface LlmSkillFile {
  path: string;
  content: string;
  content_type: string;
}

export interface LlmSkillListItem {
  id: string;
  name: string;
  description: string;
  allowed_tools: unknown[];
  metadata: Record<string, unknown>;
  version: number;
  is_latest: boolean;
  latest_version?: number | null;
  version_count?: number | null;
  created_by: LlmSkillCreatedBy | null;
  created_at: string;
  updated_at: string;
}

export interface LlmSkill extends LlmSkillListItem {
  /** The SKILL.md markdown content. */
  body: string;
  /** Length of the whole body, whatever slice of it `body` holds. */
  body_total_length?: number;
  /** Offset of the next body page, or null once `body` reaches the end. */
  body_next_offset?: number | null;
  /** Companion file manifest (paths only; fetch contents separately). */
  files: LlmSkillFileManifest[];
}

export interface LlmSkillFileInput {
  path: string;
  content: string;
  content_type?: string;
}

export interface SignalSourceConfig {
  id: string;
  source_product: SourceProduct;
  source_type: SourceType;
  enabled: boolean;
  config: Record<string, unknown>;
  created_at: string;
  updated_at: string;
  status: "running" | "completed" | "failed" | null;
}

// ── Signals scouts ───────────────────────────────────────────────────────────
// Backend: posthog `products/signals/backend/scout_harness/views.py`.
// Endpoints live under /api/projects/{id}/signals/scout/ and require the
// `signal_scout:read` / `signal_scout:write` scopes.

/**
 * Lifecycle state the coordinator keeps alongside `enabled`:
 * - `active` – running on its schedule.
 * - `pending_pause` – still running, but flagged by the inactivity sweep and
 *   due to be paused unless something changes.
 * - `paused_by_user` – a person switched it off; the system never overrides it.
 * - `paused_by_system` – the platform switched it off, see `pause_reason`.
 */
export type ScoutLifecycleStatus =
  | "active"
  | "pending_pause"
  | "paused_by_user"
  | "paused_by_system";

/**
 * Why the system warned or paused a scout: `ignored` (its findings went
 * unacted on), `no_output` (it stopped emitting anything), or
 * `repeated_failures` (its runs kept erroring).
 */
export type ScoutPauseReason = "ignored" | "no_output" | "repeated_failures";

export interface ScoutConfig {
  id: string;
  skill_name: string;
  enabled: boolean;
  /** False means dry-run: the scout runs but findings are not emitted. */
  emit: boolean;
  /**
   * Lifecycle state behind `enabled`. Absent on backends predating the
   * lifecycle fields, in which case `enabled` is all there is to go on.
   */
  status?: ScoutLifecycleStatus;
  /** Why the system warned or paused the scout; null while it is healthy. */
  pause_reason?: ScoutPauseReason | null;
  /** ISO timestamp of the last `status` transition; null if it never moved. */
  status_changed_at?: string | null;
  /** Runs that failed back to back; trips a `repeated_failures` pause. */
  consecutive_failure_count?: number;
  /**
   * Exempts the scout from the inactivity sweep — both the `ignored` pause and
   * the `no_output` warning. Set on watchdog scouts whose value is staying quiet.
   */
  auto_pause_exempt?: boolean;
  /**
   * Summary of what the scout investigates, from the skill's description
   * metadata. Empty string when the skill is absent or carries no description;
   * absent entirely on backends predating the field.
   */
  description?: string;
  /**
   * Where the scout came from: "canonical" for a scout PostHog ships and
   * maintains (seeded from products/signals/skills), "custom" for one a team
   * hand-authored. The serializer defaults to "custom" when the skill is absent;
   * the field itself is absent entirely on backends predating it.
   */
  scout_origin?: "canonical" | "custom";
  run_interval_minutes: number;
  /**
   * Cron schedule the scout runs on, evaluated in the project timezone. Null when
   * the scout runs on the rolling `run_interval_minutes` cadence instead, and
   * absent entirely on backends predating the field.
   */
  run_cron_schedule?: string | null;
  last_run_at: string | null;
  created_at: string;
}

export interface ScoutSuggestionProposedConfig {
  /** Five-field cron in the project timezone, or null for a rolling interval. */
  run_cron_schedule: string | null;
  /** Minutes between runs when no cron is given; null means the daily default. */
  run_interval_minutes: number | null;
  /** False means the suggested scout would run dry and file nothing. */
  emit: boolean;
}

export interface ScoutSuggestionItem {
  id: string;
  /** `canonical` turns on a PostHog scout that is off; `custom` creates a drafted one. */
  kind: "canonical" | "custom";
  skill_name: string;
  title: string;
  /** Project-specific evidence for this suggestion, in prose. */
  why_here: string;
  /** Custom only: the one-line description the scout would be created with. */
  description: string;
  /** Custom only: the complete skill body the scout would be created with. */
  draft_body: string;
  proposed_config: ScoutSuggestionProposedConfig;
  /** Nothing in the current fleet covers this. */
  gap: boolean;
  confidence: "low" | "medium" | "high";
}

export interface ScoutSuggestionSet {
  /** `fresh`, `stale` (the fleet moved on), `failed` (prior batch, if any), `empty`. */
  status: "fresh" | "stale" | "failed" | "empty";
  generated_at: string | null;
  model: string;
  /** Skill names that were enabled when the batch was generated. */
  fleet_snapshot: string[];
  /** Suggestions not yet dismissed or acted on, best first. Up to 5. */
  items: ScoutSuggestionItem[];
}

export interface ScoutOutputSummary {
  count: number;
  scout_count: number;
  authored_report_count: number;
  edited_report_count: number;
  run_count: number;
  latest_at: string | null;
}

export interface ScoutRun {
  run_id: string;
  created_at?: string;
  emitted_report_ids?: string[];
  edited_report_ids?: string[];
  skill_name: string;
  skill_version: number;
  /** TaskRun-derived status, e.g. "completed" | "failed" | "in_progress" | "queued". */
  status: string;
  started_at: string | null;
  completed_at: string | null;
  task_id: string | null;
  task_run_id: string | null;
  /** Relative PostHog cloud path to the backing task run. */
  task_url: string | null;
  summary: string;
  emitted_count: number | null;
  emitted_finding_ids: string[];
}

export interface ScoutEmission {
  id: string;
  run_id: string;
  finding_id: string;
  description: string;
  weight: number;
  severity: string | null;
  /** Slug tags the scout attached to this finding (lowercase kebab-case, e.g. `cost-spike`). */
  tags?: string[];
  source_id: string;
  emitted_at: string;
}

/** Minimal inbox report projection paired with a scout finding by the reverse lookup. */
export interface LinkedSignalReport {
  id: string;
  title: string | null;
  status: SignalReportStatus;
}

/**
 * One scout finding paired with the inbox report (if any) its signal grouped into.
 * `report` is null when the finding hasn't grouped into a report yet, was
 * de-duplicated away, or its signal was deleted – the link is best effort.
 */
export interface ScoutEmissionReportLink {
  finding_id: string;
  source_id: string;
  report: LinkedSignalReport | null;
}

export interface ScoutScratchpadEntry {
  key: string;
  content: string;
  created_at: string;
  updated_at: string;
  created_by_run_id: string | null;
}

export interface ScoutRunsQueryParams {
  skill_name?: string;
  date_from?: string;
  date_to?: string;
  text?: string;
  emitted?: boolean;
  limit?: number;
}

export interface ExternalDataSourceSchema {
  id: string;
  name: string;
  should_sync: boolean;
  /** e.g. `full_refresh` (full table replication), `incremental`, `append` */
  sync_type?: string | null;
}

export interface ExternalDataSource {
  id: string;
  source_type: string;
  status: string;
  // The generated `ExternalDataSourceSerializers` types this as `string`,
  // but the actual API returns an array of schema objects
  schemas?: ExternalDataSourceSchema[] | string;
  /** Non-secret connection settings, e.g. a GitHub source's `repositories`. */
  job_inputs?: Record<string, unknown> | null;
}

/**
 * Field-config variants for an external data source's connect form, as served
 * by the `external_data_sources/wizard/` endpoint. Mirrors PostHog Cloud's
 * `SourceFieldConfig` union (`posthog/schema.py`). The backend is the single
 * source of truth for which credential fields a source needs, so forms can be
 * rendered generically instead of hardcoded per source.
 */
export interface SourceFieldInputConfig {
  type:
    | "text"
    | "email"
    | "search"
    | "url"
    | "password"
    | "time"
    | "number"
    | "textarea";
  name: string;
  label: string;
  required: boolean;
  placeholder?: string;
  caption?: string | null;
  /** Redacted from API responses; render as a password field. */
  secret?: boolean;
}

export interface SourceFieldOauthConfig {
  type: "oauth";
  name: string;
  label: string;
  kind: string;
  required: boolean;
  requiredScopes?: string;
}

/**
 * A picker whose options are the accounts/resources a connected OAuth integration exposes (loaded
 * from the `oauth_accounts` endpoint using the integration's server-side token). Used e.g. for a
 * GitHub repository or an ad account.
 */
export interface SourceFieldOauthAccountSelectConfig {
  type: "oauth-account-select";
  name: string;
  label: string;
  /** Name of the sibling OAuth id field this selector reads its integration id from. */
  integrationField: string;
  /** Integration kind used to validate the connected integration, e.g. "github". */
  integrationKind: string;
  placeholder?: string;
  caption?: string;
  required?: boolean;
}

/** A selectable account/resource an OAuth integration exposes (shared `IntegrationAccount` shape). */
export interface IntegrationAccount {
  value: string;
  display_name: string;
  is_primary: boolean;
  badges: string[];
  group: string | null;
  secondary_text: string | null;
}

interface SourceFieldSelectConfigOption {
  label: string;
  value: string;
  fields?: SourceFieldConfig[];
}

export interface SourceFieldSelectConfig {
  type: "select";
  name: string;
  label: string;
  required: boolean;
  defaultValue?: string;
  options: SourceFieldSelectConfigOption[];
}

export interface SourceFieldSwitchGroupConfig {
  type: "switch-group";
  name: string;
  label: string;
  caption?: string;
  default?: boolean;
  fields: SourceFieldConfig[];
}

/** Field types the generic renderer does not (yet) handle inline. */
export interface SourceFieldUnsupportedConfig {
  type: "ssh-tunnel" | "file-upload";
  name: string;
  label: string;
}

export type SourceFieldConfig =
  | SourceFieldInputConfig
  | SourceFieldOauthConfig
  | SourceFieldOauthAccountSelectConfig
  | SourceFieldSelectConfig
  | SourceFieldSwitchGroupConfig
  | SourceFieldUnsupportedConfig;

export interface SourceConfig {
  name: string;
  label?: string;
  caption?: string;
  fields: SourceFieldConfig[];
}

export interface ChannelInstructionsUser {
  id?: number;
  uuid?: string;
  first_name?: string;
  last_name?: string | null;
  email?: string;
}

export interface ChannelInstructions {
  channel: string;
  content: string;
  version: number;
  created_at: string;
  created_by: ChannelInstructionsUser | null;
}

export interface ChannelInstructionsVersion {
  channel: string;
  version: number;
  created_at: string;
  created_by: ChannelInstructionsUser | null;
}

// Thrown when PUT /instructions/ rejects a publish because the caller's
// `base_version` is older than the current latest. Callers can re-fetch and
// retry against the new latest.
export class FolderInstructionsConflictError extends Error {
  status = 409;
  constructor(
    message = "Folder instructions changed since you started editing",
  ) {
    super(message);
    this.name = "FolderInstructionsConflictError";
  }
}

export interface PostHogObjectReferenceInput {
  name: string;
  object_kind: string;
  object_id: string;
  source_message_id: string;
}

export interface ContextWikiTree {
  head_sha: string;
  paths: string[];
}

export interface ContextWikiPage {
  path: string;
  content: string;
  head_sha: string;
  updated_at: string;
}

export interface ContextWikiHealthFinding {
  category: string;
  path: string;
  message: string;
}

export interface ContextWikiHealthReport {
  head_sha: string;
  findings: ContextWikiHealthFinding[];
}

export interface ChannelContextWikiPage {
  path: string;
}

export interface ContextWikiDreamRun {
  sha: string;
  date: string;
  committed_at: string;
  summary: string;
  pages_added: number;
  pages_modified: number;
  pages_deleted: number;
}

export interface ContextWikiActiveDreamRun {
  run_status: "not_started" | "queued" | "in_progress";
  started_at: string;
}

export interface ContextWikiDreamList {
  head_sha: string;
  active_run: ContextWikiActiveDreamRun | null;
  dreams: ContextWikiDreamRun[];
}

export interface ContextWikiDreamFile {
  path: string;
  status: "added" | "modified" | "deleted";
  patch: string;
  truncated: boolean;
}

export interface ContextWikiDreamDetail {
  run: ContextWikiDreamRun;
  files: ContextWikiDreamFile[];
}

// Thrown when PUT /context_layer/pages/ rejects a write because the caller's
// `base_head` is older than the wiki's current head. `currentHead` is the head
// to re-read against before retrying.
export class ContextWikiConflictError extends Error {
  status = 409;
  currentHead: string | null;
  constructor(currentHead: string | null) {
    super("The wiki changed since you started editing");
    this.name = "ContextWikiConflictError";
    this.currentHead = currentHead;
  }
}

// Thrown when a page write fails the wiki's structure lint; `errors` lists the
// violations for inline display.
export class ContextWikiLintError extends Error {
  status = 400;
  errors: string[];
  constructor(detail: string, errors: string[]) {
    super(detail);
    this.name = "ContextWikiLintError";
    this.errors = errors;
  }
}

// Thrown on 403: the organization has private projects, so its wiki is
// deliberately unavailable. Distinct from 404 (wiki never enabled).
export class ContextWikiUnavailableError extends Error {
  status = 403;
  constructor(message: string) {
    super(message);
    this.name = "ContextWikiUnavailableError";
  }
}

/** DRF error bodies carry the human-readable message in `detail`. */
function readDetail(error: ApiRequestError): string {
  const body = error.body as { detail?: string } | null;
  return body?.detail ?? error.message;
}

/**
 * DRF validation failures carry the messages per field, `{ field: [msg] }`,
 * with no top-level `detail`. Flatten them so the server's own wording reaches
 * the toast instead of a bare status text.
 */
function readFieldErrors(error: ApiRequestError): string {
  if (typeof error.body !== "object" || error.body === null) {
    return error.message;
  }
  const record = error.body as Record<string, unknown>;
  if (typeof record.detail === "string") return record.detail;
  const parts = Object.values(record).flatMap((messages) =>
    Array.isArray(messages) ? messages.map(String) : [],
  );
  return parts.length > 0 ? parts.join(" ") : error.message;
}

export interface TaskArtifactUploadRequest {
  name: string;
  type: "output" | "user_attachment" | "skill_bundle";
  size: number;
  content_type?: string;
  source?: string;
  metadata?: TaskRunArtifactMetadata;
}

interface DirectUploadPresignedPost {
  url: string;
  fields: Record<string, string>;
}

export interface PreparedTaskArtifactUpload extends TaskArtifactUploadRequest {
  id: string;
  storage_path: string;
  expires_in: number;
  presigned_post: DirectUploadPresignedPost;
}

export interface FinalizedTaskArtifactUpload {
  id: string;
  name: string;
  type: string;
  source?: string;
  size?: number;
  content_type?: string;
  metadata?: TaskArtifactUploadRequest["metadata"];
  storage_path: string;
  uploaded_at?: string;
  uploaded_by?: "agent" | "user";
  uploaded_by_user_id?: number;
}

export interface CloudRunOptions {
  adapter?: Adapter;
  piRuntime?: boolean;
  model?: string;
  reasoningLevel?: string;
  contextWindow?: "200k" | "1m";
  fastMode?: boolean;
  sandboxEnvironmentId?: string;
  customImageId?: string;
  prAuthorshipMode?: PrAuthorshipMode;
  autoPublish?: boolean;
  /** Only false is sent: opts the run out of rtk command-output compression. */
  rtkEnabled?: boolean;
  claudeModelAccess?: ModelAccess;
  codexModelAccess?: ModelAccess;
  runSource?: CloudRunSource;
  signalReportId?: string;
  initialPermissionMode?: ExecutionMode;
  /**
   * Local url-based MCP servers to make available inside the sandbox. The
   * backend merges these into the agent server's `--mcpServers` at spawn.
   */
  importedMcpServers?: McpServerConnection[];
  relayedMcpServers?: CloudMcpServerRelayDesignation[];
}

export type CloudRunCommandMethod =
  | "pi/rpc"
  | "user_message"
  | "permission_response"
  | "set_config_option"
  | "cancel"
  | "close";

export class CloudCommandError extends Error {
  readonly status: number;
  readonly backendError: string | null;
  readonly method: CloudRunCommandMethod;

  constructor(
    method: CloudRunCommandMethod,
    status: number,
    backendError: string | null,
    message: string,
  ) {
    super(message);
    this.name = "CloudCommandError";
    this.method = method;
    this.status = status;
    this.backendError = backendError;
  }

  isSandboxInactive(): boolean {
    const backendError = this.backendError?.toLowerCase();
    return (
      this.status === 404 ||
      backendError?.includes("no active sandbox") === true ||
      backendError?.includes("returned 404") === true
    );
  }
}

function cloudCommandBackendError(payload: unknown): string | null {
  if (typeof payload === "string") return payload || null;
  if (!payload || typeof payload !== "object") return null;

  const error = "error" in payload ? payload.error : null;
  if (typeof error === "string") return error || null;
  if (error && typeof error === "object" && "message" in error) {
    return typeof error.message === "string" ? error.message : null;
  }
  if ("message" in payload && typeof payload.message === "string") {
    return payload.message;
  }
  return null;
}

interface CreateTaskRunOptions extends CloudRunOptions {
  environment?: "local" | "cloud";
  mode?: "interactive" | "background";
  branch?: string | null;
}

interface StartTaskRunOptions {
  pendingUserMessage?: string;
  pendingUserArtifactIds?: string[];
}

function buildCloudRunRequestBody(
  options?: CloudRunOptions & {
    branch?: string | null;
    mode?: "interactive" | "background";
    resumeFromRunId?: string;
    pendingUserMessage?: string;
    pendingUserArtifactIds?: string[];
  },
): Record<string, unknown> {
  const body: Record<string, unknown> = {
    mode: options?.mode ?? "interactive",
  };

  if (options?.branch) {
    body.branch = options.branch;
  }
  if (options?.adapter) {
    body.runtime_adapter = options.adapter;
  }
  if (options?.model && (options.adapter || options.piRuntime)) {
    body.model = options.model;
  }
  if (options?.reasoningLevel && (options.adapter || options.piRuntime)) {
    if (!options.model) {
      throw new Error(
        "A cloud reasoning level requires a model to be selected.",
      );
    }
    if (
      options.adapter &&
      !isSupportedReasoningEffort(
        options.adapter,
        options.model,
        options.reasoningLevel,
      )
    ) {
      throw new Error(
        `Reasoning effort '${options.reasoningLevel}' is not supported for ${options.adapter} model '${options.model}'.`,
      );
    }
    body.reasoning_effort = options.reasoningLevel;
  }
  if (options?.adapter && options.contextWindow) {
    body.context_window = options.contextWindow;
  }
  if (options?.adapter && options.fastMode !== undefined) {
    body.fast_mode = options.fastMode;
  }
  if (options?.adapter && options.initialPermissionMode) {
    body.initial_permission_mode = resolveCloudInitialPermissionMode(
      options.adapter,
      options.initialPermissionMode,
    );
  }
  if (options?.resumeFromRunId) {
    body.resume_from_run_id = options.resumeFromRunId;
  }
  if (options?.pendingUserMessage) {
    body.pending_user_message = options.pendingUserMessage;
  }
  if (options?.pendingUserArtifactIds?.length) {
    body.pending_user_artifact_ids = options.pendingUserArtifactIds;
  }
  if (options?.sandboxEnvironmentId) {
    body.sandbox_environment_id = options.sandboxEnvironmentId;
  }
  if (options?.customImageId) {
    body.custom_image_id = options.customImageId;
  }
  if (options?.prAuthorshipMode) {
    body.pr_authorship_mode = options.prAuthorshipMode;
  }
  if (options?.autoPublish !== undefined) {
    body.auto_publish = options.autoPublish;
  }
  if (options?.rtkEnabled === false) {
    body.rtk_enabled = false;
  }
  if (!options?.piRuntime && options?.claudeModelAccess) {
    body.claude_model_access = options.claudeModelAccess;
  }
  if (!options?.piRuntime && options?.codexModelAccess) {
    body.codex_model_access = options.codexModelAccess;
  }
  if (options?.runSource) {
    body.run_source = options.runSource;
  }
  if (options?.signalReportId) {
    body.signal_report_id = options.signalReportId;
  }
  if (options?.importedMcpServers?.length) {
    body.imported_mcp_servers = options.importedMcpServers;
  }
  if (options?.relayedMcpServers?.length) {
    body.relayed_mcp_servers = options.relayedMcpServers;
  }

  return body;
}

function isObjectRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null;
}

function optionalString(value: unknown): string | null {
  return typeof value === "string" ? value : null;
}

// DRF's generic placeholder for "no route matched" and an unhandled NotFound
// alike — never a business-specific message, so it's less actionable than the
// endpoint's own fallback plus status code.
const DRF_GENERIC_NOT_FOUND_DETAIL = "Not found.";
/** One request per targeted distinct id; flags listing more stay raw past this. */
const MAX_RESOLVED_FLAG_PEOPLE = 10;
const MAX_RESOLVED_COHORTS = 10;

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}

function isPropertyRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}

/** Unwrap the shared fetcher's `Failed request: [<status>] <json>` into the endpoint's clean message. */
function extractRequestErrorMessage(error: unknown, fallback: string): string {
  const raw = error instanceof Error ? error.message : String(error);
  const match = raw.match(/^Failed request: \[(\d+)\] (.*)$/s);
  if (!match) {
    return fallback;
  }
  try {
    const body = JSON.parse(match[2]) as { error?: unknown; detail?: unknown };
    const message = body.error ?? body.detail;
    if (
      typeof message === "string" &&
      message.trim() &&
      message !== DRF_GENERIC_NOT_FOUND_DETAIL
    ) {
      return message;
    }
  } catch {
    // Non-JSON body — fall through to the status-based fallback.
  }
  return `${fallback} (HTTP ${match[1]})`;
}

type AnyArtefact =
  | SignalReportArtefact
  | PriorityJudgmentArtefact
  | ActionabilityJudgmentArtefact
  | SafetyJudgmentArtefact
  | SignalFindingArtefact
  | RepoSelectionArtefact
  | SuggestedReviewersArtefact
  | DismissalArtefact
  | CodeReferenceArtefact
  | LineReferenceArtefact
  | CommitArtefact
  | TaskRunArtefact
  | NoteArtefact
  | WorkClaimArtefact
  | WorkReleaseArtefact
  | RankingScoreArtefact;

// Reasons valid on a dismissal artefact. Resolve reasons are included because the
// backend stores resolve feedback on the same artefact type (a resolve writes a
// `dismissal` artefact), so `fixed_outside_posthog` / `pr_merged` must normalize too.
const DISMISSAL_REASONS = new Set<ReportStateReason>([
  ...DISMISSAL_REASON_OPTIONS.map((o) => o.value),
  ...RESOLVE_REASON_OPTIONS.map((o) => o.value),
  "pr_merged",
]);

const PRIORITY_VALUES = new Set(["P0", "P1", "P2", "P3", "P4"]);

function normalizePriorityJudgmentArtefact(
  value: Record<string, unknown>,
): PriorityJudgmentArtefact | null {
  const id = optionalString(value.id);
  if (!id) return null;

  const contentValue = isObjectRecord(value.content) ? value.content : null;
  if (!contentValue) return null;

  const priority = optionalString(contentValue.priority);
  if (!priority || !PRIORITY_VALUES.has(priority)) return null;

  return {
    id,
    type: "priority_judgment",
    ...artefactBase(value),
    content: {
      explanation: optionalString(contentValue.explanation) ?? "",
      priority: priority as PriorityJudgmentArtefact["content"]["priority"],
    },
  };
}

const ACTIONABILITY_VALUES = new Set([
  "immediately_actionable",
  "requires_human_input",
  "not_actionable",
]);

function normalizeActionabilityJudgmentArtefact(
  value: Record<string, unknown>,
): ActionabilityJudgmentArtefact | null {
  const id = optionalString(value.id);
  if (!id) return null;

  const contentValue = isObjectRecord(value.content) ? value.content : null;
  if (!contentValue) return null;

  // Support both agentic ("actionability") and legacy ("choice") field names
  const actionability =
    optionalString(contentValue.actionability) ??
    optionalString(contentValue.choice);
  if (!actionability || !ACTIONABILITY_VALUES.has(actionability)) return null;

  return {
    id,
    type: "actionability_judgment",
    ...artefactBase(value),
    content: {
      explanation: optionalString(contentValue.explanation) ?? "",
      actionability:
        actionability as ActionabilityJudgmentArtefact["content"]["actionability"],
      already_addressed:
        typeof contentValue.already_addressed === "boolean"
          ? contentValue.already_addressed
          : false,
    },
  };
}

function normalizeSafetyJudgmentArtefact(
  value: Record<string, unknown>,
): SafetyJudgmentArtefact | null {
  const id = optionalString(value.id);
  if (!id) return null;

  const contentValue = isObjectRecord(value.content) ? value.content : null;
  if (!contentValue || typeof contentValue.choice !== "boolean") return null;

  return {
    id,
    type: "safety_judgment",
    ...artefactBase(value),
    content: {
      choice: contentValue.choice,
      explanation: optionalString(contentValue.explanation),
    },
  };
}

function normalizeSignalFindingArtefact(
  value: Record<string, unknown>,
): SignalFindingArtefact | null {
  const id = optionalString(value.id);
  if (!id) return null;

  const contentValue = isObjectRecord(value.content) ? value.content : null;
  if (!contentValue) return null;

  const signalId = optionalString(contentValue.signal_id);
  if (!signalId) return null;

  return {
    id,
    type: "signal_finding",
    ...artefactBase(value),
    content: {
      signal_id: signalId,
      relevant_code_paths: Array.isArray(contentValue.relevant_code_paths)
        ? contentValue.relevant_code_paths.filter(
            (p: unknown): p is string => typeof p === "string",
          )
        : [],
      relevant_commit_hashes: isObjectRecord(
        contentValue.relevant_commit_hashes,
      )
        ? Object.fromEntries(
            Object.entries(contentValue.relevant_commit_hashes).filter(
              (e): e is [string, string] => typeof e[1] === "string",
            ),
          )
        : {},
      data_queried: optionalString(contentValue.data_queried) ?? "",
      verified:
        typeof contentValue.verified === "boolean"
          ? contentValue.verified
          : false,
    },
  };
}

function normalizeRepoSelectionArtefact(
  value: Record<string, unknown>,
): RepoSelectionArtefact | null {
  const id = optionalString(value.id);
  if (!id) return null;

  const contentValue = isObjectRecord(value.content) ? value.content : null;
  if (!contentValue) return null;

  return {
    id,
    type: "repo_selection",
    ...artefactBase(value),
    content: {
      repository: optionalString(contentValue.repository),
      reason: optionalString(contentValue.reason) ?? "",
    },
  };
}

function normalizeDismissalArtefact(
  value: Record<string, unknown>,
): DismissalArtefact | null {
  const id = optionalString(value.id);
  if (!id) return null;

  const contentValue = isObjectRecord(value.content) ? value.content : null;
  if (!contentValue) return null;

  const rawReason = optionalString(contentValue.reason);
  const reason =
    rawReason && DISMISSAL_REASONS.has(rawReason as ReportStateReason)
      ? (rawReason as ReportStateReason)
      : null;

  if (reason == null) {
    return null;
  }

  return {
    id,
    type: "dismissal",
    ...artefactBase(value),
    content: {
      state:
        contentValue.state === "resolved" ||
        contentValue.state === "suppressed" ||
        contentValue.state === "potential"
          ? contentValue.state
          : null,
      reason,
      note: optionalString(contentValue.note) ?? "",
      user_id:
        typeof contentValue.user_id === "number" ? contentValue.user_id : null,
      user_uuid: optionalString(contentValue.user_uuid),
    },
  };
}

// ── Log artefact normalizers ──────────────────────────────────────────────
// The backend stores log-artefact content as a JSON object (not the string-or-
// session_id shape the generic fallback expects), so each type needs an explicit
// normalizer — otherwise it falls through and gets dropped.

/** User the artefact is attributed to, when the row carries a valid `created_by`. */
function normalizeArtefactUser(value: unknown): UserBasic | null {
  if (!isObjectRecord(value)) return null;
  const id = value.id;
  const uuid = optionalString(value.uuid);
  const email = optionalString(value.email);
  if (typeof id !== "number" || !uuid || !email) return null;
  return {
    id,
    uuid,
    email,
    first_name: optionalString(value.first_name) ?? undefined,
    last_name: optionalString(value.last_name) ?? undefined,
  };
}

/** Row-level fields shared by every artefact: timestamps plus user/task attribution. */
function artefactBase(value: Record<string, unknown>): {
  created_at: string;
  updated_at: string | null;
  created_by: UserBasic | null;
  task_id: string | null;
} {
  return {
    created_at: optionalString(value.created_at) ?? new Date(0).toISOString(),
    updated_at: optionalString(value.updated_at),
    created_by: normalizeArtefactUser(value.created_by),
    task_id: optionalString(value.task_id),
  };
}

function normalizeCodeReferenceArtefact(
  value: Record<string, unknown>,
): CodeReferenceArtefact | null {
  const id = optionalString(value.id);
  if (!id) return null;
  const c = isObjectRecord(value.content) ? value.content : null;
  if (!c) return null;
  const file_path = optionalString(c.file_path);
  if (!file_path) return null;

  return {
    id,
    type: "code_reference",
    ...artefactBase(value),
    content: {
      file_path,
      start_line: typeof c.start_line === "number" ? c.start_line : 0,
      end_line: typeof c.end_line === "number" ? c.end_line : 0,
      contents: optionalString(c.contents) ?? "",
      relevance_note: optionalString(c.relevance_note) ?? "",
    },
  };
}

function normalizeLineReferenceArtefact(
  value: Record<string, unknown>,
): LineReferenceArtefact | null {
  const id = optionalString(value.id);
  if (!id) return null;
  const c = isObjectRecord(value.content) ? value.content : null;
  if (!c) return null;
  const file_path = optionalString(c.file_path);
  if (!file_path) return null;

  return {
    id,
    type: "line_reference",
    ...artefactBase(value),
    content: {
      file_path,
      line: typeof c.line === "number" ? c.line : 0,
      note: optionalString(c.note) ?? "",
      contents: optionalString(c.contents),
    },
  };
}

function normalizeCommitArtefact(
  value: Record<string, unknown>,
): CommitArtefact | null {
  const id = optionalString(value.id);
  if (!id) return null;
  const c = isObjectRecord(value.content) ? value.content : null;
  if (!c) return null;
  const repository = optionalString(c.repository);
  const branch = optionalString(c.branch);
  const commit_sha = optionalString(c.commit_sha);
  if (!repository || !branch || !commit_sha) return null;

  return {
    id,
    type: "commit",
    ...artefactBase(value),
    content: {
      repository,
      branch,
      commit_sha,
      message: optionalString(c.message) ?? "",
      note: optionalString(c.note),
    },
  };
}

function normalizeTaskRunArtefact(
  value: Record<string, unknown>,
): TaskRunArtefact | null {
  const id = optionalString(value.id);
  if (!id) return null;
  const c = isObjectRecord(value.content) ? value.content : null;
  if (!c) return null;
  const task_id = optionalString(c.task_id);
  if (!task_id) return null;
  const product = optionalString(c.product);
  const type = optionalString(c.type);
  if (!product || !type) return null;

  return {
    id,
    type: "task_run",
    ...artefactBase(value),
    content: {
      task_id,
      run_id: optionalString(c.run_id),
      product,
      type,
    },
  };
}

function normalizeNoteArtefact(
  value: Record<string, unknown>,
): NoteArtefact | null {
  const id = optionalString(value.id);
  if (!id) return null;
  const c = isObjectRecord(value.content) ? value.content : null;
  if (!c) return null;
  const note = optionalString(c.note);
  if (!note) return null;

  return {
    id,
    type: "note",
    ...artefactBase(value),
    content: {
      note,
      author: optionalString(c.author),
    },
  };
}

function normalizeWorkClaimArtefact(
  value: Record<string, unknown>,
): WorkClaimArtefact | null {
  const id = optionalString(value.id);
  if (!id || !isObjectRecord(value.content)) return null;
  return {
    id,
    type: "work_claim",
    ...artefactBase(value),
    content: { display_name: optionalString(value.content.display_name) },
  };
}

function normalizeWorkReleaseArtefact(
  value: Record<string, unknown>,
): WorkReleaseArtefact | null {
  const id = optionalString(value.id);
  if (!id || !isObjectRecord(value.content)) return null;
  const reason = value.content.reason;
  if (reason !== "released" && reason !== "taken_over") return null;
  return {
    id,
    type: "work_release",
    ...artefactBase(value),
    content: { reason },
  };
}

/** Reads the stored lift first. Otherwise mirrors `head_lifts` in `ranking/model_contract.py`. */
function rankingHeadLift(
  stored: unknown,
  probability: number,
  threshold: number | undefined,
): number | null {
  if (typeof stored === "number" && Number.isFinite(stored)) return stored;
  return threshold !== undefined && threshold > 0
    ? probability / threshold
    : null;
}

function compareRankingHeads(a: RankingHead, b: RankingHead): number {
  if (a.lift !== null && b.lift !== null) return b.lift - a.lift;
  if (a.lift !== null || b.lift !== null) return a.lift === null ? 1 : -1;
  return b.probability - a.probability;
}

function normalizeRankingModelResult(
  key: string,
  value: unknown,
): RankingModelResult | null {
  if (!isObjectRecord(value)) return null;
  const status = value.status;
  if (status !== "scored" && status !== "skipped") return null;
  // Mirrors `readable_head_names` in `ranking/model_contract.py`.
  const metadataHeads =
    isObjectRecord(value.metadata) && Array.isArray(value.metadata.heads)
      ? value.metadata.heads
      : [];
  const readable = new Set(
    metadataHeads
      .filter((entry) => isObjectRecord(entry) && entry.readable === true)
      .map((entry) => String((entry as Record<string, unknown>).head)),
  );
  // Mirrors `classification_thresholds` in `ranking/model_contract.py`.
  const thresholds = new Map<string, number>();
  for (const entry of metadataHeads) {
    if (
      isObjectRecord(entry) &&
      typeof entry.refit_classification_threshold === "number"
    ) {
      thresholds.set(String(entry.head), entry.refit_classification_threshold);
    }
  }
  const lifts = isObjectRecord(value.lifts) ? value.lifts : {};
  const scores = isObjectRecord(value.scores) ? value.scores : {};
  const heads = Object.entries(scores)
    .filter(
      (entry): entry is [string, number] =>
        typeof entry[1] === "number" && Number.isFinite(entry[1]),
    )
    .map(([name, probability]) => ({
      name,
      probability,
      lift: rankingHeadLift(lifts[name], probability, thresholds.get(name)),
      readable: readable.has(name),
    }))
    .sort(compareRankingHeads);
  return {
    key,
    roles: Array.isArray(value.roles)
      ? value.roles.filter((role): role is string => typeof role === "string")
      : [],
    status,
    skip_reason: optionalString(value.skip_reason),
    heads,
  };
}

/** Null when the content does not parse or `served_key` is missing from `results`. */
function normalizeRankingScoreArtefact(
  value: Record<string, unknown>,
): RankingScoreArtefact | null {
  const id = optionalString(value.id);
  if (!id || !isObjectRecord(value.content)) return null;
  const c = value.content;
  const servedKey = optionalString(c.served_key);
  if (!servedKey || !isObjectRecord(c.results)) return null;
  const models = Object.entries(c.results).map(([key, result]) =>
    normalizeRankingModelResult(key, result),
  );
  const served = models.find((model) => model?.key === servedKey);
  if (!served) return null;
  return {
    id,
    type: "ranking_score",
    ...artefactBase(value),
    content: {
      scored_at: optionalString(c.scored_at),
      manifest_version: optionalString(c.manifest_version),
      served,
      challengers: models.filter(
        (model): model is RankingModelResult =>
          !!model && model.key !== servedKey,
      ),
    },
  };
}

/** Best human-readable one-liner from arbitrary artefact content. */
function contentPreview(content: unknown): string {
  if (typeof content === "string") return content;
  if (isObjectRecord(content)) {
    for (const key of ["note", "explanation", "reason", "message", "content"]) {
      const v = content[key];
      if (typeof v === "string" && v.trim()) return v;
    }
  }
  try {
    const text = JSON.stringify(content);
    return text && text !== "{}" && text !== "null" ? text.slice(0, 300) : "";
  } catch {
    return "";
  }
}

/**
 * Last-resort normalizer: keeps the row (type, timestamps, attribution, a text
 * preview) when its content doesn't match the type's expected shape, so an
 * artefact never silently vanishes from the activity log.
 */
function normalizeFallbackArtefact(
  value: Record<string, unknown>,
): SignalReportArtefact | null {
  const id = optionalString(value.id);
  if (!id) return null;
  return {
    id,
    type: optionalString(value.type) ?? "unknown",
    degraded: true,
    ...artefactBase(value),
    content: {
      session_id: "",
      start_time: "",
      end_time: "",
      distinct_id: "",
      content: contentPreview(value.content),
      distance_to_centroid: null,
    },
  };
}

function normalizeSignalReportArtefact(value: unknown): AnyArtefact | null {
  if (!isObjectRecord(value)) {
    return null;
  }

  const dispatchType = optionalString(value.type);
  if (dispatchType === "signal_finding") {
    return (
      normalizeSignalFindingArtefact(value) ?? normalizeFallbackArtefact(value)
    );
  }
  if (dispatchType === "actionability_judgment") {
    return (
      normalizeActionabilityJudgmentArtefact(value) ??
      normalizeFallbackArtefact(value)
    );
  }
  if (dispatchType === "safety_judgment") {
    return (
      normalizeSafetyJudgmentArtefact(value) ?? normalizeFallbackArtefact(value)
    );
  }
  if (dispatchType === "priority_judgment") {
    return (
      normalizePriorityJudgmentArtefact(value) ??
      normalizeFallbackArtefact(value)
    );
  }
  if (dispatchType === "repo_selection") {
    return (
      normalizeRepoSelectionArtefact(value) ?? normalizeFallbackArtefact(value)
    );
  }
  if (dispatchType === "dismissal") {
    return (
      normalizeDismissalArtefact(value) ?? normalizeFallbackArtefact(value)
    );
  }
  if (dispatchType === "code_reference") {
    return (
      normalizeCodeReferenceArtefact(value) ?? normalizeFallbackArtefact(value)
    );
  }
  if (dispatchType === "line_reference") {
    return (
      normalizeLineReferenceArtefact(value) ?? normalizeFallbackArtefact(value)
    );
  }
  if (dispatchType === "commit") {
    return normalizeCommitArtefact(value) ?? normalizeFallbackArtefact(value);
  }
  if (dispatchType === "task_run") {
    return normalizeTaskRunArtefact(value) ?? normalizeFallbackArtefact(value);
  }
  if (dispatchType === "note") {
    return normalizeNoteArtefact(value) ?? normalizeFallbackArtefact(value);
  }
  if (dispatchType === "work_claim") {
    return (
      normalizeWorkClaimArtefact(value) ?? normalizeFallbackArtefact(value)
    );
  }
  if (dispatchType === "work_release") {
    return (
      normalizeWorkReleaseArtefact(value) ?? normalizeFallbackArtefact(value)
    );
  }
  if (dispatchType === "ranking_score") {
    return (
      normalizeRankingScoreArtefact(value) ?? normalizeFallbackArtefact(value)
    );
  }

  const id = optionalString(value.id);
  if (!id) {
    return null;
  }

  const type = dispatchType ?? "unknown";

  // suggested_reviewers: content is an array of reviewer objects
  if (type === "suggested_reviewers" && Array.isArray(value.content)) {
    return {
      id,
      type: "suggested_reviewers" as const,
      ...artefactBase(value),
      content: value.content as SuggestedReviewersArtefact["content"],
    };
  }

  // video_segment and other artefacts with object content
  const contentValue = isObjectRecord(value.content) ? value.content : null;
  if (!contentValue) {
    return normalizeFallbackArtefact(value);
  }

  const content = optionalString(contentValue.content);
  const sessionId = optionalString(contentValue.session_id);

  // The backend may return empty content objects when binary decode fails.
  if (!content && !sessionId) {
    return normalizeFallbackArtefact(value);
  }

  return {
    id,
    type,
    ...artefactBase(value),
    content: {
      session_id: sessionId ?? "",
      start_time: optionalString(contentValue.start_time) ?? "",
      end_time: optionalString(contentValue.end_time) ?? "",
      distinct_id: optionalString(contentValue.distinct_id) ?? "",
      content: content ?? "",
      distance_to_centroid:
        typeof contentValue.distance_to_centroid === "number"
          ? contentValue.distance_to_centroid
          : null,
    },
  };
}

function parseSignalReportArtefactsPayload(
  value: unknown,
): SignalReportArtefactsResponse {
  const payload = isObjectRecord(value) ? value : null;
  const rawResults = Array.isArray(payload?.results)
    ? payload.results
    : Array.isArray(value)
      ? value
      : [];

  const results = rawResults
    .map(normalizeSignalReportArtefact)
    .filter((artefact): artefact is AnyArtefact => artefact !== null);
  const count =
    typeof payload?.count === "number" ? payload.count : results.length;

  if (rawResults.length > 0 && results.length === 0) {
    return {
      results: [],
      count: 0,
      unavailableReason: "invalid_payload",
    };
  }

  return {
    results,
    count,
  };
}

function normalizeAvailableSuggestedReviewer(
  uuid: string,
  value: unknown,
): AvailableSuggestedReviewer | null {
  if (!isObjectRecord(value)) {
    return null;
  }

  const normalizedUuid = optionalString(uuid);
  if (!normalizedUuid) {
    return null;
  }

  return {
    uuid: normalizedUuid,
    name: optionalString(value.name) ?? "",
    email: optionalString(value.email) ?? "",
    github_login: optionalString(value.github_login) ?? "",
  };
}

function parseAvailableSuggestedReviewersPayload(
  value: unknown,
): AvailableSuggestedReviewersResponse {
  if (!isObjectRecord(value)) {
    return {
      results: [],
      count: 0,
    };
  }

  const results = Object.entries(value)
    .map(([uuid, reviewer]) =>
      normalizeAvailableSuggestedReviewer(uuid, reviewer),
    )
    .filter(
      (reviewer): reviewer is AvailableSuggestedReviewer => reviewer !== null,
    );

  return {
    results,
    count: results.length,
  };
}

export class PostHogAPIClient {
  private api: ReturnType<typeof createApiClient>;
  private _teamId: number | null = null;
  private githubConnectFrom: string;
  private readonly apiHost: string;
  private readonly taskClientProvenance: TaskClientProvenance;

  constructor(
    apiHost: string,
    getAccessToken: () => Promise<string>,
    refreshAccessToken: () => Promise<string>,
    teamId?: number,
    options: PostHogAPIClientOptions = {},
  ) {
    const baseUrl = apiHost.endsWith("/") ? apiHost.slice(0, -1) : apiHost;
    this.apiHost = baseUrl;
    this.githubConnectFrom = options.githubConnectFrom ?? "posthog_code";
    this.taskClientProvenance =
      options.taskClientProvenance ?? taskClientProvenance;
    this.api = createApiClient(
      buildApiFetcher({
        getAccessToken,
        refreshAccessToken,
        appVersion: options.appVersion ?? clientAppVersion,
        fetch: options.fetch,
        userAgent: options.userAgent,
      }),
      baseUrl,
    );
    if (teamId) {
      this._teamId = teamId;
    }
  }

  setTeamId(teamId: number | null | undefined): void {
    this._teamId = teamId ?? null;
  }

  private async getTeamId(): Promise<number> {
    if (this._teamId !== null) {
      return this._teamId;
    }

    const user = await this.api.get("/api/users/{uuid}/", {
      path: { uuid: "@me" },
    });

    if (user?.team?.id) {
      this._teamId = user.team.id;
      return this._teamId;
    }

    throw new Error("No team found for user");
  }

  async getCurrentUser() {
    const data = await this.api.get("/api/users/{uuid}/", {
      path: { uuid: "@me" },
    });
    return data;
  }

  async getCloudTaskGatewayModels(): Promise<GatewayModel[]> {
    const teamId = await this.getTeamId();
    const url = new URL(`${getCloudTaskGatewayUrl(this.apiHost)}/v1/models`);
    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path: url.pathname,
      parameters: {
        header: buildPosthogProjectHeaderRecord(teamId),
      },
    });
    return normalizeGatewayModelsResponse(await response.json());
  }

  async getCloudTaskConfigOptions(
    adapter: Adapter = "claude",
  ): Promise<CloudTaskConfigOption[]> {
    return buildCloudTaskConfigOptions(
      await this.getCloudTaskGatewayModels(),
      adapter,
    );
  }

  // The task currently generating this folder's CONTEXT.md, shared across the
  // project so any user sees an in-progress generation (instead of fragile
  // local state). Keyed on the folder row (which always exists), not the
  // instructions object (which doesn't until the first version is published).
  // Returns null when nothing is generating — or, until the backend ships this
  // endpoint, on 404 (the feature degrades to no shared indicator).
  async getDesktopFolderGenerationTask(
    folderId: string,
  ): Promise<string | null> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/projects/${teamId}/desktop_file_system/${encodeURIComponent(folderId)}/context_generation/`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path: urlPath,
    });
    if (response.status === 404) return null;
    if (!response.ok) {
      throw new Error(
        `Failed to fetch folder generation task: ${response.statusText}`,
      );
    }
    const data = (await response.json()) as { task_id?: string | null };
    return data.task_id ?? null;
  }

  // Record (or clear, with null) the task generating this folder's CONTEXT.md.
  async setDesktopFolderGenerationTask(
    folderId: string,
    taskId: string | null,
  ): Promise<void> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/projects/${teamId}/desktop_file_system/${encodeURIComponent(folderId)}/context_generation/`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    const response = await this.api.fetcher.fetch({
      method: "put",
      url,
      path: urlPath,
      overrides: {
        body: JSON.stringify({ task_id: taskId }),
      },
    });
    if (!response.ok && response.status !== 404) {
      throw new Error(
        `Failed to set folder generation task: ${response.statusText}`,
      );
    }
  }

  async getGithubLogin(): Promise<string | null> {
    const data = (await this.api.get("/api/users/{uuid}/github_login/", {
      path: { uuid: "@me" },
    })) as { github_login: string | null };
    return data.github_login;
  }

  /**
   * `POST .../integrations/github/start/`. Optional `teamId` matches app project when session `current_team` differs.
   */
  async startGithubUserIntegrationConnect(teamId?: number): Promise<{
    install_url: string;
    connect_flow?: "oauth_authorize" | "oauth_discover" | "app_install";
  }> {
    const id = teamId ?? (await this.getTeamId());
    const urlPath = `/api/users/@me/integrations/github/start/`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    const response = await this.api.fetcher.fetch({
      method: "post",
      url,
      path: urlPath,
      overrides: {
        body: JSON.stringify({
          team_id: id,
          connect_from: this.githubConnectFrom,
        }),
      },
    });
    if (!response.ok) {
      const err = (await response.json().catch(() => ({}))) as {
        detail?: unknown;
      };
      const detail =
        typeof err.detail === "string"
          ? err.detail
          : "Failed to start GitHub connection";
      throw new Error(detail);
    }
    return (await response.json()) as {
      install_url: string;
      connect_flow?: "oauth_authorize" | "oauth_discover" | "app_install";
    };
  }

  async getGithubUserIntegrations(): Promise<UserGitHubIntegration[]> {
    const urlPath = `/api/users/@me/integrations/?kind=github`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path: urlPath,
    });

    if (!response.ok) {
      throw new Error(
        `Failed to fetch personal GitHub integrations: ${response.statusText}`,
      );
    }

    const data = (await response.json()) as {
      results?: UserGitHubIntegration[];
    };
    return data.results ?? [];
  }

  async disconnectGithubUserIntegration(installationId: string): Promise<void> {
    const urlPath = `/api/users/@me/integrations/github/${encodeURIComponent(installationId)}/`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    const response = await this.api.fetcher.fetch({
      method: "delete",
      url,
      path: urlPath,
    });
    if (!response.ok && response.status !== 404) {
      throw new Error(
        `Failed to disconnect GitHub integration: ${response.statusText}`,
      );
    }
  }

  async getCodexUserIntegration(): Promise<UserCodexIntegration> {
    const urlPath = `/api/users/@me/integrations/codex/`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path: urlPath,
    });
    if (!response.ok) {
      throw new Error(
        `Failed to fetch the ChatGPT account: ${response.statusText}`,
      );
    }
    return (await response.json()) as UserCodexIntegration;
  }

  /**
   * `POST /api/users/@me/integrations/codex/`. PostHog refreshes the chain once and keeps
   * the rotated tokens, so the local `auth.json` is stale after this call.
   */
  async connectCodexUserIntegration(
    tokens: CodexAuthTokens,
  ): Promise<UserCodexIntegration> {
    const urlPath = `/api/users/@me/integrations/codex/`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    const response = await this.api.fetcher.fetch({
      method: "post",
      url,
      path: urlPath,
      overrides: { body: JSON.stringify({ tokens }) },
    });
    if (!response.ok) {
      const err = (await response.json().catch(() => ({}))) as {
        detail?: unknown;
      };
      throw new Error(
        typeof err.detail === "string"
          ? err.detail
          : `Failed to connect the ChatGPT account: ${response.statusText}`,
      );
    }
    return (await response.json()) as UserCodexIntegration;
  }

  async disconnectCodexUserIntegration(): Promise<void> {
    const urlPath = `/api/users/@me/integrations/codex/`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    const response = await this.api.fetcher.fetch({
      method: "delete",
      url,
      path: urlPath,
    });
    if (!response.ok && response.status !== 404) {
      throw new Error(
        `Failed to disconnect the ChatGPT account: ${response.statusText}`,
      );
    }
  }

  /** `GET /api/users/@me/integrations/github/install_requests/`: installs waiting on a GitHub org owner. */
  async getGithubInstallRequests(): Promise<GithubInstallRequestsResponse> {
    const urlPath = `/api/users/@me/integrations/github/install_requests/`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path: urlPath,
    });
    if (!response.ok) {
      throw new Error(
        `Failed to fetch GitHub install requests: ${response.statusText}`,
      );
    }
    const data =
      (await response.json()) as Partial<GithubInstallRequestsResponse>;
    return {
      results: data.results ?? [],
      install_url: data.install_url ?? null,
    };
  }

  async dismissGithubInstallRequest(requestId: string): Promise<void> {
    const urlPath = `/api/users/@me/integrations/github/install_requests/${encodeURIComponent(requestId)}/`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    await this.api.fetcher.fetch({
      method: "delete",
      url,
      path: urlPath,
    });
  }

  /** `DELETE /api/environments/{project}/integrations/{id}/`: any team-level integration (GitHub, Slack, ...). */
  async deleteIntegration(
    projectId: number,
    integrationId: number | string,
  ): Promise<void> {
    await this.api.delete("/api/projects/{project_id}/integrations/{id}/", {
      path: { project_id: projectId.toString(), id: Number(integrationId) },
    });
  }

  /** Emails the project's admins asking them to connect an integration; members only. */
  async requestIntegrationAccess(
    projectId: number,
    body: { kind: string; reason: string },
  ): Promise<void> {
    const urlPath = `/api/environments/${projectId}/integrations/request_access/`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    await this.api.fetcher.fetch({
      method: "post",
      url,
      path: urlPath,
      overrides: { body: JSON.stringify(body) },
    });
  }

  /** The user's linked Slack identities. Empty until they run the Sign-in-with-Slack flow. */
  async listSlackUserIntegrations(): Promise<
    {
      slack_user_id: string;
      slack_team_id: string;
      slack_team_name: string | null;
    }[]
  > {
    const urlPath = `/api/users/@me/integrations/`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    url.searchParams.set("kind", "slack");
    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path: urlPath,
    });
    if (!response.ok) {
      throw new Error(
        `Failed to list Slack integrations: ${response.statusText}`,
      );
    }
    const data = (await response.json()) as {
      results?: {
        slack_user_id: string;
        slack_team_id: string;
        slack_team_name: string | null;
      }[];
    };
    return data.results ?? [];
  }

  /**
   * `POST .../integrations/slack/start`. Returns the Sign-in-with-Slack URL; Slack tells the
   * callback which user authorized, so nobody types a Slack ID.
   */
  async startSlackUserIntegrationConnect(
    teamId?: number,
  ): Promise<{ install_url: string }> {
    const id = teamId ?? (await this.getTeamId());
    const urlPath = `/api/users/@me/integrations/slack/start/`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    const response = await this.api.fetcher.fetch({
      method: "post",
      url,
      path: urlPath,
      overrides: { body: JSON.stringify({ team_id: id }) },
    });
    if (!response.ok) {
      const err = (await response.json().catch(() => ({}))) as {
        detail?: unknown;
      };
      throw new Error(
        typeof err.detail === "string"
          ? err.detail
          : `Failed to start Slack connect: ${response.statusText}`,
      );
    }
    return (await response.json()) as { install_url: string };
  }

  /** Patch the user's server-side notification settings. Merged server-side, so pass only the keys you change. */
  async updateNotificationSettings(
    settings: Record<string, unknown>,
  ): Promise<void> {
    await this.api.patch("/api/users/{uuid}/", {
      path: { uuid: "@me" },
      body: { notification_settings: settings } as Record<string, unknown>,
    });
  }

  async switchOrganization(orgId: string): Promise<void> {
    await this.api.patch("/api/users/{uuid}/", {
      path: { uuid: "@me" },
      body: { set_current_organization: orgId } as Record<string, unknown>,
    });
  }

  async approveAiDataProcessing(organizationId: string): Promise<void> {
    const urlPath = `/api/organizations/${organizationId}/`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    await this.api.fetcher.fetch({
      method: "patch",
      url,
      path: urlPath,
      overrides: {
        body: JSON.stringify({ is_ai_data_processing_approved: true }),
      },
    });
  }

  async areDesktopBetaTermsAccepted(): Promise<boolean> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/projects/${teamId}/desktop_beta_terms/`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path: urlPath,
    });
    if (!response.ok) {
      throw new Error(
        `Failed to check Desktop beta terms: ${response.statusText}`,
      );
    }
    const data = (await response.json()) as {
      is_desktop_beta_terms_accepted: boolean;
    };
    return data.is_desktop_beta_terms_accepted;
  }

  async acceptDesktopBetaTerms(): Promise<void> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/projects/${teamId}/desktop_beta_terms/`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    const response = await this.api.fetcher.fetch({
      method: "post",
      url,
      path: urlPath,
    });
    if (!response.ok) {
      throw new Error(
        `Failed to accept Desktop beta terms: ${response.statusText}`,
      );
    }
  }

  async getProject(projectId: number) {
    //@ts-expect-error this is not in the generated client
    const data = await this.api.get("/api/projects/{project_id}/", {
      path: { project_id: projectId.toString() },
    });
    return data as Schemas.ProjectBackwardCompat;
  }

  /**
   * The AI run triple a task run gets when the caller pins no runtime selection —
   * the signed-in user's per-project preference over the project default.
   *
   * Hand-rolled rather than routed through the generated client because
   * `tasks/@me/config/` postdates the last schema pull.
   */
  async getTaskRunDefaults(projectId: number): Promise<TaskRunDefaults> {
    return (await this.getMyTaskRunConfig(projectId)).resolved;
  }

  /** The signed-in user's stored preference for this project, plus what it resolves to. */
  async getMyTaskRunConfig(projectId: number): Promise<MyTaskRunConfig> {
    return await this.taskRunConfigRequest(
      "get",
      `/api/projects/${projectId}/tasks/@me/config/`,
    );
  }

  /**
   * Store the signed-in user's preference for this project. All three fields null
   * clears it, which is how "use the project default" is expressed.
   */
  async updateMyTaskRunPreferences(
    projectId: number,
    preferences: TaskRunPreferences,
  ): Promise<MyTaskRunConfig> {
    return await this.taskRunConfigRequest(
      "post",
      `/api/projects/${projectId}/tasks/@me/config/`,
      preferences,
    );
  }

  /**
   * The project-wide default. Readable by any member; only project admins may change
   * it, which is why this client offers no writer for it — the settings page links to
   * PostHog rather than presenting a control that would 403.
   */
  async getTeamTaskRunPreferences(
    projectId: number,
  ): Promise<TaskRunPreferences> {
    return (
      await this.taskRunConfigRequest(
        "get",
        `/api/projects/${projectId}/tasks/config/`,
      )
    ).preferences;
  }

  /** The signed-in user's personal instructions for cloud runs in this project. Empty when unset. */
  async getMyAgentInstructions(projectId: number): Promise<string> {
    const urlPath = `/api/projects/${projectId}/tasks/@me/config/`;
    const response = await this.api.fetcher.fetch({
      method: "get",
      url: new URL(`${this.api.baseUrl}${urlPath}`),
      path: urlPath,
    });
    if (!response.ok) {
      throw new Error(`Agent instructions request failed: ${response.status}`);
    }
    const payload = (await response.json()) as {
      agent_instructions?: string | null;
    };
    return payload.agent_instructions ?? "";
  }

  /** Replace the signed-in user's personal instructions for cloud runs in this project. */
  async setMyAgentInstructions(
    projectId: number,
    instructions: string,
  ): Promise<void> {
    const urlPath = `/api/projects/${projectId}/tasks/@me/config/agent_instructions/`;
    const response = await this.api.fetcher.fetch({
      method: "post",
      url: new URL(`${this.api.baseUrl}${urlPath}`),
      path: urlPath,
      overrides: {
        body: JSON.stringify({ agent_instructions: instructions }),
      },
    });
    if (!response.ok) {
      throw new Error(`Agent instructions update failed: ${response.status}`);
    }
  }

  private async taskRunConfigRequest(
    method: "get" | "post",
    urlPath: string,
    body?: TaskRunPreferences,
  ): Promise<MyTaskRunConfig> {
    const response = await this.api.fetcher.fetch({
      method,
      url: new URL(`${this.api.baseUrl}${urlPath}`),
      path: urlPath,
      ...(body ? { overrides: { body: JSON.stringify(body) } } : {}),
    });
    if (!response.ok) {
      throw new Error(`Task run config request failed: ${response.status}`);
    }
    const payload = (await response.json()) as {
      ai_run_preferences?: Partial<TaskRunPreferences> | null;
      resolved_ai_run_defaults?: TaskRunDefaults | null;
      task_defaults?: Partial<TaskDefaults> | null;
    };
    return {
      // The API stores a cleared preference as `{}`, so read each field rather than
      // assuming the triple is present.
      preferences: {
        runtime: payload.ai_run_preferences?.runtime ?? null,
        runtime_adapter: payload.ai_run_preferences?.runtime_adapter ?? null,
        model: payload.ai_run_preferences?.model ?? null,
        reasoning_effort: payload.ai_run_preferences?.reasoning_effort ?? null,
      },
      resolved: payload.resolved_ai_run_defaults ?? NO_TASK_RUN_DEFAULTS,
      taskDefaults: {
        start_in_plan_mode: payload.task_defaults?.start_in_plan_mode ?? null,
        auto_publish_cloud_runs:
          payload.task_defaults?.auto_publish_cloud_runs ?? null,
      },
    };
  }

  /** Save some of the signed-in user's task defaults. Fields left out keep their value. */
  async setMyTaskDefaults(
    projectId: number,
    changes: Partial<Record<keyof TaskDefaults, boolean>>,
  ): Promise<void> {
    const urlPath = `/api/projects/${projectId}/tasks/@me/config/task_defaults/`;
    const response = await this.api.fetcher.fetch({
      method: "post",
      url: new URL(`${this.api.baseUrl}${urlPath}`),
      path: urlPath,
      overrides: { body: JSON.stringify(changes) },
    });
    if (!response.ok) {
      throw new Error(`Task defaults update failed: ${response.status}`);
    }
  }

  async listSignalSourceConfigs(
    projectId: number,
  ): Promise<SignalSourceConfig[]> {
    const urlPath = `/api/projects/${projectId}/signals/source_configs/`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path: urlPath,
    });
    if (!response.ok) {
      throw new Error(
        `Failed to fetch signal source configs: ${response.statusText}`,
      );
    }
    const data = (await response.json()) as
      | { results: SignalSourceConfig[] }
      | SignalSourceConfig[];
    return Array.isArray(data) ? data : (data.results ?? []);
  }

  async createSignalSourceConfig(
    projectId: number,
    options: {
      source_product: SignalSourceConfig["source_product"];
      source_type: SignalSourceConfig["source_type"];
      enabled: boolean;
      config?: Record<string, unknown>;
    },
  ): Promise<SignalSourceConfig> {
    const urlPath = `/api/projects/${projectId}/signals/source_configs/`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    const response = await this.api.fetcher.fetch({
      method: "post",
      url,
      path: urlPath,
      overrides: {
        body: JSON.stringify(options),
      },
    });
    if (!response.ok) {
      const errorData = (await response.json().catch(() => ({}))) as {
        detail?: string;
      };
      throw new Error(
        errorData.detail ??
          `Failed to create signal source config: ${response.statusText}`,
      );
    }
    return (await response.json()) as SignalSourceConfig;
  }

  async updateSignalSourceConfig(
    projectId: number,
    configId: string,
    updates: { enabled: boolean },
  ): Promise<SignalSourceConfig> {
    const urlPath = `/api/projects/${projectId}/signals/source_configs/${configId}/`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    const response = await this.api.fetcher.fetch({
      method: "patch",
      url,
      path: urlPath,
      overrides: {
        body: JSON.stringify(updates),
      },
    });
    if (!response.ok) {
      const errorData = (await response.json().catch(() => ({}))) as {
        detail?: string;
      };
      throw new Error(
        errorData.detail ??
          `Failed to update signal source config: ${response.statusText}`,
      );
    }
    return (await response.json()) as SignalSourceConfig;
  }

  private async scoutGet<T>(
    projectId: number,
    subPath: string,
    query?: Record<string, string | number | boolean | undefined>,
  ): Promise<T> {
    const urlPath = `/api/projects/${projectId}/signals/scout/${subPath}`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    for (const [key, value] of Object.entries(query ?? {})) {
      if (value !== undefined) url.searchParams.set(key, String(value));
    }
    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path: urlPath,
    });
    if (!response.ok) {
      throw new ScoutRequestError(
        response.status,
        subPath,
        response.statusText,
      );
    }
    return (await response.json()) as T;
  }

  private async scoutPost<T>(
    projectId: number,
    subPath: string,
    body: unknown,
    query?: Record<string, string | number | boolean | undefined>,
  ): Promise<T> {
    const urlPath = `/api/projects/${projectId}/signals/scout/${subPath}`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    for (const [key, value] of Object.entries(query ?? {})) {
      if (value !== undefined) url.searchParams.set(key, String(value));
    }
    const response = await this.api.fetcher
      .fetch({
        method: "post",
        url,
        path: urlPath,
        overrides: {
          body: JSON.stringify(body),
        },
      })
      .catch((error: unknown) => {
        if (error instanceof ApiRequestError) {
          throw new ScoutRequestError(error.status, subPath, readDetail(error));
        }
        throw error;
      });
    if (!response.ok) {
      throw new ScoutRequestError(
        response.status,
        subPath,
        response.statusText,
      );
    }
    return (await response.json()) as T;
  }

  async listScoutConfigs(projectId: number): Promise<ScoutConfig[]> {
    const data = await this.scoutGet<
      { results: ScoutConfig[] } | ScoutConfig[]
    >(projectId, "configs/");
    return Array.isArray(data) ? data : (data.results ?? []);
  }

  /**
   * Materialize the project's scout fleet and return it: the backend seeds the
   * canonical `signals-scout-*` skills, registers a config for every scout
   * missing one, and retires the ones no longer shipped. Idempotent, and the
   * only way a project the Temporal coordinator never reached gets any scouts.
   */
  async syncScoutConfigs(projectId: number): Promise<ScoutConfig[]> {
    const data = await this.scoutPost<
      { results: ScoutConfig[] } | ScoutConfig[]
    >(projectId, "configs/sync/", {}, { surface: "desktop" });
    return Array.isArray(data) ? data : (data.results ?? []);
  }

  /**
   * The pre-computed "Suggested for this project" batch: PostHog scouts worth
   * turning on, and drafts worth creating, each with the evidence behind it.
   * A coordinator refreshes it on a schedule, so this read never waits on one.
   */
  async listScoutSuggestions(projectId: number): Promise<ScoutSuggestionSet> {
    return this.scoutGet<ScoutSuggestionSet>(projectId, "suggestions/");
  }

  async dismissScoutSuggestion(
    projectId: number,
    suggestionId: string,
  ): Promise<void> {
    await this.scoutPost<unknown>(
      projectId,
      `suggestions/${suggestionId}/dismiss/`,
      {},
    );
  }

  async updateScoutConfig(
    projectId: number,
    configId: string,
    updates: {
      /**
       * Flipping this off records a user pause (`status` becomes
       * `paused_by_user`, which the system never overrides); flipping it on
       * resumes the scout from any pause, including a system one.
       */
      enabled?: boolean;
      emit?: boolean;
      run_interval_minutes?: number;
      /** A cron expression puts the scout on a calendar; null returns it to the rolling cadence. */
      run_cron_schedule?: string | null;
      auto_pause_exempt?: boolean;
    },
  ): Promise<ScoutConfig> {
    const urlPath = `/api/projects/${projectId}/signals/scout/configs/${configId}/`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    const response = await this.api.fetcher.fetch({
      method: "patch",
      url,
      path: urlPath,
      overrides: {
        body: JSON.stringify(updates),
      },
    });
    if (!response.ok) {
      const errorData = (await response.json().catch(() => ({}))) as {
        detail?: string;
      };
      throw new Error(
        errorData.detail ??
          `Failed to update scout config: ${response.statusText}`,
      );
    }
    return (await response.json()) as ScoutConfig;
  }

  /**
   * Queue one run of a scout outside its schedule. 409 when a run is already in
   * flight, 429 when the project's daily run budget is spent.
   */
  async runScoutNow(
    projectId: number,
    configId: string,
  ): Promise<{ skill_name: string; workflow_id: string; started: boolean }> {
    return await this.scoutPost(projectId, `configs/${configId}/run/`, {});
  }

  async listScoutRuns(
    projectId: number,
    params?: ScoutRunsQueryParams,
  ): Promise<ScoutRun[]> {
    const data = await this.scoutGet<{ results: ScoutRun[] } | ScoutRun[]>(
      projectId,
      "runs/",
      {
        skill_name: params?.skill_name,
        date_from: params?.date_from,
        date_to: params?.date_to,
        text: params?.text,
        emitted: params?.emitted,
        limit: params?.limit,
      },
    );
    return Array.isArray(data) ? data : (data.results ?? []);
  }

  async listRecentScoutRuns(projectId: number): Promise<ScoutRun[]> {
    return await this.scoutGet<ScoutRun[]>(
      projectId,
      "runs/recent-per-scout/",
      { per_scout_limit: 18 },
    );
  }

  async getScoutOutputSummary(projectId: number): Promise<ScoutOutputSummary> {
    return await this.scoutGet<ScoutOutputSummary>(
      projectId,
      "runs/findings/summary/",
      { window_hours: 72 },
    );
  }

  async getScoutRun(projectId: number, runId: string): Promise<ScoutRun> {
    return await this.scoutGet<ScoutRun>(projectId, `runs/${runId}/`);
  }

  /**
   * POST a run-id list to a scout batch endpoint and flatten the response. The
   * API caps each call at SCOUT_BATCH_RUN_ID_LIMIT ids, so larger lists are
   * split into parallel chunks and concatenated — the caller never has to know
   * the cap exists. Run ids belonging to another team contribute no rows rather
   * than erroring, so a single stale id can't blank the list.
   */
  private async scoutBatchByRunIds<T>(
    projectId: number,
    subPath: string,
    runIds: string[],
  ): Promise<T[]> {
    if (runIds.length === 0) return [];
    const SCOUT_BATCH_RUN_ID_LIMIT = 200;
    const chunks: string[][] = [];
    for (let i = 0; i < runIds.length; i += SCOUT_BATCH_RUN_ID_LIMIT) {
      chunks.push(runIds.slice(i, i + SCOUT_BATCH_RUN_ID_LIMIT));
    }
    const pages = await Promise.all(
      chunks.map((chunk) =>
        this.scoutPost<{ results: T[] } | T[]>(projectId, subPath, {
          run_ids: chunk,
        }),
      ),
    );
    return pages.flatMap((data) =>
      Array.isArray(data) ? data : (data.results ?? []),
    );
  }

  /**
   * Every supplied run's emitted findings in one request, flattened newest-first
   * (each row keeps its `run_id` so the caller can regroup). Replaces the old
   * per-run fan-out — one Postgres query instead of one request per run.
   */
  async batchScoutRunEmissions(
    projectId: number,
    runIds: string[],
  ): Promise<ScoutEmission[]> {
    return this.scoutBatchByRunIds<ScoutEmission>(
      projectId,
      "runs/emissions/batch/",
      runIds,
    );
  }

  /**
   * Best-effort reverse lookup: for each finding the supplied runs emitted, the
   * inbox report (if any) its underlying signal grouped into. Resolves every
   * run's findings in a single ClickHouse round-trip instead of one per run.
   * Pairs with the report's evidence list, which links the other direction.
   */
  async batchScoutEmissionReports(
    projectId: number,
    runIds: string[],
  ): Promise<ScoutEmissionReportLink[]> {
    return this.scoutBatchByRunIds<ScoutEmissionReportLink>(
      projectId,
      "runs/emissions/reports/batch/",
      runIds,
    );
  }

  async searchScoutScratchpad(
    projectId: number,
    params?: { text?: string; limit?: number },
  ): Promise<ScoutScratchpadEntry[]> {
    const data = await this.scoutGet<
      { results: ScoutScratchpadEntry[] } | ScoutScratchpadEntry[]
    >(projectId, "scratchpad/", {
      text: params?.text,
      limit: params?.limit,
    });
    return Array.isArray(data) ? data : (data.results ?? []);
  }

  async listEvaluations(projectId: number): Promise<Evaluation[]> {
    const data = await this.api.get("/api/projects/{project_id}/evaluations/", {
      path: { project_id: projectId.toString() },
      query: { limit: 200 },
    });
    return data.results ?? [];
  }

  async updateEvaluation(
    projectId: number,
    evaluationId: string,
    updates: { enabled: boolean },
  ): Promise<Evaluation> {
    return await this.api.patch(
      "/api/projects/{project_id}/evaluations/{id}/",
      {
        path: {
          project_id: projectId.toString(),
          id: evaluationId,
        },
        body: updates,
      },
    );
  }

  async listExternalDataSources(
    projectId: number,
  ): Promise<ExternalDataSource[]> {
    const data = (await this.api.get(
      "/api/projects/{project_id}/external_data_sources/",
      {
        path: { project_id: projectId.toString() },
        query: {},
      },
    )) as unknown as { results?: ExternalDataSource[] } | ExternalDataSource[];
    return Array.isArray(data) ? data : (data.results ?? []);
  }

  async createExternalDataSource(
    projectId: number,
    payload: {
      source_type: string;
      payload: Record<string, unknown>;
    },
  ): Promise<ExternalDataSource> {
    const response = await this.api.post(
      "/api/projects/{project_id}/external_data_sources/",
      {
        path: { project_id: projectId.toString() },
        body: payload as unknown as Schemas.ExternalDataSourceCreate,
        withResponse: true,
        throwOnStatusError: false,
      },
    );
    if (!response.ok) {
      const errorData = isObjectRecord(response.data)
        ? (response.data as { detail?: string })
        : {};
      throw new Error(
        errorData.detail ??
          `Failed to create external data source: ${response.statusText}`,
      );
    }
    return response.data as unknown as ExternalDataSource;
  }

  /**
   * `PATCH .../external_data_sources/{id}/`. `job_inputs` merges into the stored inputs, so
   * changing a GitHub source's repositories only needs `{ repositories: [...] }`.
   */
  async updateExternalDataSource(
    projectId: number,
    sourceId: string,
    payload: { job_inputs: Record<string, unknown> },
  ): Promise<ExternalDataSource> {
    const response = await this.api.patch(
      "/api/projects/{project_id}/external_data_sources/{id}/",
      {
        path: { project_id: projectId.toString(), id: sourceId },
        body: payload as unknown as Schemas.PatchedExternalDataSourceSerializers,
        withResponse: true,
        throwOnStatusError: false,
      },
    );
    if (!response.ok) {
      const errorData = isObjectRecord(response.data)
        ? (response.data as { detail?: string })
        : {};
      throw new Error(
        errorData.detail ??
          `Failed to update external data source: ${response.statusText}`,
      );
    }
    return response.data as unknown as ExternalDataSource;
  }

  /**
   * Fetch the connect-form field schema for external data source types from the
   * warehouse wizard endpoint. Pass `sourceType` (e.g. `"Jira"`) to scope to one
   * source; omit to fetch every source's config. Returns a map keyed by the
   * capitalized source type string.
   */
  async getExternalDataSourceConfigs(
    projectId: number,
    sourceType?: string,
  ): Promise<Record<string, SourceConfig>> {
    const url = new URL(
      `${this.api.baseUrl}/api/environments/${projectId}/external_data_sources/wizard/`,
    );
    if (sourceType) {
      url.searchParams.set("source_type", sourceType);
    }
    const path = `/api/environments/${projectId}/external_data_sources/wizard/`;
    const response = await this.api.fetcher.fetch({ method: "get", url, path });
    if (!response.ok) {
      throw new Error(`Failed to fetch source configs: ${response.statusText}`);
    }
    return (await response.json()) as Record<string, SourceConfig>;
  }

  /**
   * List the accounts/resources a connected OAuth integration exposes for a source type (e.g. the
   * repositories a GitHub integration can access), for an `oauth-account-select` field. The backend
   * uses the integration's stored token; the client only passes the integration id. Pass `search`
   * to filter server-side for large lists.
   */
  async getOauthAccounts(
    projectId: number,
    sourceType: string,
    integrationId: number | string,
    search?: string,
  ): Promise<IntegrationAccount[]> {
    const url = new URL(
      `${this.api.baseUrl}/api/environments/${projectId}/external_data_sources/oauth_accounts/`,
    );
    url.searchParams.set("source_type", sourceType);
    url.searchParams.set("integration_id", String(integrationId));
    if (search?.trim()) {
      url.searchParams.set("search", search.trim());
    }
    const path = `/api/environments/${projectId}/external_data_sources/oauth_accounts/`;
    const response = await this.api.fetcher.fetch({ method: "get", url, path });
    if (!response.ok) {
      throw new Error(`Failed to fetch accounts: ${response.statusText}`);
    }
    const data = (await response.json()) as { accounts?: IntegrationAccount[] };
    return data.accounts ?? [];
  }

  async updateExternalDataSchema(
    projectId: number,
    schemaId: string,
    updates: { should_sync: boolean; sync_type?: string },
  ): Promise<void> {
    const urlPath = `/api/projects/${projectId}/external_data_schemas/${schemaId}/`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    const response = await this.api.fetcher.fetch({
      method: "patch",
      url,
      path: urlPath,
      overrides: {
        body: JSON.stringify(updates),
      },
    });
    if (!response.ok) {
      const errorData = (await response.json().catch(() => ({}))) as {
        detail?: string;
      };
      throw new Error(
        errorData.detail ??
          `Failed to update external data schema: ${response.statusText}`,
      );
    }
  }

  /**
   * Update several of a source's schemas in one request. The backend commits each schema on its
   * own, so one schema failing still applies the rest and the error names the ones it could not
   * save — unlike a client-side loop, where the first failure skips everything after it.
   */
  async bulkUpdateExternalDataSchemas(
    projectId: number,
    sourceId: string,
    schemas: { id: string; should_sync?: boolean; sync_type?: string }[],
  ): Promise<void> {
    const response = await this.api.patch(
      "/api/projects/{project_id}/external_data_sources/{id}/bulk_update_schemas/",
      {
        path: { project_id: projectId.toString(), id: sourceId },
        body: {
          schemas,
        } as unknown as Schemas.ExternalDataSourceBulkUpdateSchemas,
        withResponse: true,
        throwOnStatusError: false,
      },
    );
    if (!response.ok) {
      const errorData = isObjectRecord(response.data)
        ? (response.data as { detail?: string })
        : {};
      throw new Error(
        errorData.detail ??
          `Failed to update external data schemas: ${response.statusText}`,
      );
    }
  }

  async getTasks(options?: TaskListOptions): Promise<Task[]> {
    return (await this.getTasksPage(options)).tasks;
  }

  async getTasksWithStatus(
    options?: TaskListOptions,
    pagination?: { maxPages?: number; fetchAll?: boolean },
  ): Promise<{ tasks: Task[]; isComplete: boolean }> {
    const maxPages = pagination?.fetchAll
      ? Number.POSITIVE_INFINITY
      : (pagination?.maxPages ?? 1);
    const pageSize = Math.min(
      options?.limit ?? TASK_LIST_MAX_PAGE_SIZE,
      TASK_LIST_MAX_PAGE_SIZE,
    );
    const tasks: Task[] = [];
    let count = 0;

    for (let pageIndex = 0; pageIndex < maxPages; pageIndex++) {
      const page = await this.getTasksPage({
        ...options,
        limit: pageSize,
        offset: tasks.length,
      });
      tasks.push(...page.tasks);
      count = page.count;
      if (tasks.length >= count) return { tasks, isComplete: true };
      if (page.tasks.length === 0) break;
    }

    return { tasks, isComplete: tasks.length >= count };
  }

  async searchTasks(query: string, limit = 20): Promise<TaskSearchResult[]> {
    const teamId = await this.getTeamId();
    const path = `/api/projects/${teamId}/tasks/search/`;
    const url = new URL(`${this.api.baseUrl}${path}`);
    url.searchParams.set("q", query);
    url.searchParams.set("limit", String(limit));
    const response = await this.api.fetcher.fetch({ method: "get", url, path });
    if (!response.ok) {
      throw new Error(`Failed to search tasks: ${response.statusText}`);
    }
    return (await response.json()) as TaskSearchResult[];
  }

  /**
   * The same list with the total behind it, for surfaces that ask for a short
   * page and still have to say how much they are not showing.
   */
  async getTasksPage(
    options?: TaskListOptions,
  ): Promise<{ tasks: Task[]; count: number }> {
    const teamId = await this.getTeamId();
    const params: Record<string, string | number | boolean | string[]> = {
      limit: options?.limit ?? 500,
    };

    if (options?.offset !== undefined) {
      params.offset = options.offset;
    }

    if (options?.repository) {
      params.repository = options.repository;
    }

    if (options?.createdBy) {
      params.created_by = options.createdBy;
    }

    if (options?.originProduct) {
      params.origin_product = options.originProduct;
    }

    if (options?.internal) {
      params.internal = true;
    }

    if (options?.channel) {
      params.channel = options.channel;
    }

    if (options?.search) {
      params.search = options.search;
    }

    if (options?.status) {
      params.status = options.status;
    }

    if (options?.prState) {
      params.pr_state = options.prState;
    }

    if (options?.ciStatus) {
      params.ci_status = options.ciStatus;
    }

    if (options?.pinned) {
      params.pinned = true;
    }

    if (options?.sources?.length) {
      params.sources = [...options.sources];
    }

    if (options?.commentedBy) {
      params.commented_by = options.commentedBy;
    }

    if (options?.mentions) {
      params.mentions = options.mentions;
    }

    if (options?.archived) {
      params.archived = "true";
    }

    if (options?.ordering) {
      params.ordering = options.ordering;
    }

    if (options?.basic) {
      params.basic = true;
    }

    const data = await this.api.get(`/api/projects/{project_id}/tasks/`, {
      path: { project_id: teamId.toString() },
      query: params,
    });

    const tasks = (data.results ?? []).map((task) =>
      normalizeTaskResponse(task, { teamId }),
    );
    return { tasks, count: data.count ?? tasks.length };
  }

  async getTaskSummaries(ids: string[]) {
    if (ids.length === 0) return [];
    // The endpoint caps a page at 100 rows (TasksPagination.max_limit). Ask for
    // the largest page, then pull any remaining pages in parallel by offset. The
    // old code walked `next` one blocking request at a time, so a large sidebar
    // turned into a chain of serial round-trips on every inbox open.
    const MAX_PAGES = 50;
    const teamId = await this.getTeamId();
    const basePath = `/api/projects/${teamId}/tasks/summaries/`;

    const fetchPage = async (
      offset: number,
    ): Promise<TaskSummariesResponse> => {
      const urlPath = `${basePath}?limit=${TASK_LIST_MAX_PAGE_SIZE}&offset=${offset}`;
      const response = await this.api.fetcher.fetch({
        method: "post",
        url: new URL(`${this.api.baseUrl}${urlPath}`),
        path: urlPath,
        overrides: {
          body: JSON.stringify({ ids } satisfies Schemas.TaskSummariesRequest),
        },
      });
      if (!response.ok) {
        throw new Error(
          `Failed to fetch task summaries: ${response.statusText}`,
        );
      }
      return (await response.json()) as TaskSummariesResponse;
    };

    const first = await fetchPage(0);
    const all: TaskSummaryDTO[] = [...first.results];
    const capped = Math.min(first.count, TASK_LIST_MAX_PAGE_SIZE * MAX_PAGES);
    if (first.count > TASK_LIST_MAX_PAGE_SIZE * MAX_PAGES) {
      log.warn(
        `getTaskSummaries capped at ${MAX_PAGES} pages; returning partial results`,
        { ids: ids.length, count: first.count },
      );
    }
    const offsets: number[] = [];
    for (
      let offset = TASK_LIST_MAX_PAGE_SIZE;
      offset < capped;
      offset += TASK_LIST_MAX_PAGE_SIZE
    ) {
      offsets.push(offset);
    }
    // Cap how many page POSTs are in flight at once. A large sidebar can span
    // dozens of pages, and this runs on every poll; an unbounded fan-out would
    // fire them all together (each re-sending the full id list).
    const CONCURRENCY = 6;
    for (let i = 0; i < offsets.length; i += CONCURRENCY) {
      const batch = offsets.slice(i, i + CONCURRENCY);
      const pages = await Promise.all(batch.map((offset) => fetchPage(offset)));
      for (const page of pages) all.push(...page.results);
    }
    return all;
  }

  async getTask(taskId: string): Promise<Task> {
    const teamId = await this.getTeamId();
    const data = await this.api.get(`/api/projects/{project_id}/tasks/{id}/`, {
      path: { project_id: teamId.toString(), id: taskId },
    });
    return normalizeTaskResponse(data, { teamId });
  }

  async getTaskReview(taskId: string, page = 1): Promise<Schemas.TaskReview> {
    const teamId = await this.getTeamId();
    return this.api.get("/api/projects/{project_id}/tasks/{id}/review/", {
      path: { project_id: teamId.toString(), id: taskId },
      query: { page },
    });
  }

  async getTaskUsage(taskId: string): Promise<TaskUsage> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/projects/${teamId}/tasks/${taskId}/usage/`;
    const response = await this.api.fetcher.fetch({
      method: "get",
      url: new URL(`${this.api.baseUrl}${urlPath}`),
      path: urlPath,
    });
    if (!response.ok) {
      throw new Error(`Failed to fetch task usage: ${response.statusText}`);
    }
    return (await response.json()) as TaskUsage;
  }

  async getPinnedTaskIds(): Promise<string[]> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/projects/${teamId}/tasks/pinned/`;
    const response = await this.api.fetcher.fetch({
      method: "get",
      url: new URL(`${this.api.baseUrl}${urlPath}`),
      path: urlPath,
    });
    if (!response.ok) {
      throw new Error(`Failed to fetch pinned tasks: ${response.statusText}`);
    }
    const data = (await response.json()) as { task_ids: string[] };
    return data.task_ids;
  }

  async setTaskPinned(taskId: string, pinned: boolean): Promise<boolean> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/projects/${teamId}/tasks/${taskId}/pin/`;
    const response = await this.api.fetcher.fetch({
      method: "post",
      url: new URL(`${this.api.baseUrl}${urlPath}`),
      path: urlPath,
      overrides: { body: JSON.stringify({ pinned }) },
    });
    if (!response.ok) {
      throw new Error(`Failed to update task pin: ${response.statusText}`);
    }
    const data = (await response.json()) as { pinned: boolean };
    return data.pinned;
  }

  // Handoff is absent from the Desktop-generated client, so use the same raw-fetch path as pin.
  async handoffTask(taskId: string, userId: number): Promise<Task> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/projects/${teamId}/tasks/${taskId}/handoff/`;
    const response = await this.api.fetcher.fetch({
      method: "post",
      url: new URL(`${this.api.baseUrl}${urlPath}`),
      path: urlPath,
      overrides: { body: JSON.stringify({ user: userId }) },
    });
    if (!response.ok) {
      throw new Error(`Failed to hand off task: ${response.statusText}`);
    }
    const data = (await response.json()) as Parameters<
      typeof normalizeTaskResponse
    >[0];
    return normalizeTaskResponse(data, { teamId });
  }

  async createTask(
    options: Pick<Task, "description"> &
      Partial<
        Pick<
          Task,
          | "title"
          | "repository"
          | "json_schema"
          | "origin_product"
          | "runtime"
          | "signal_report"
        >
      > & {
        github_integration?: number | null;
        github_user_integration?: string | null;
        signal_report_task_relationship?: string;
        signal_report_discussion_question?: string;
        branch?: string | null;
        runtime_adapter?: string | null;
        model?: string | null;
        reasoning_effort?: string | null;
        channel?: string | null;
        pending_user_message?: string;
        pending_user_artifact_ids?: string[];
        initial_permission_mode?: ExecutionMode;
        auto_publish?: boolean;
        naming_source?: string;
      },
  ): Promise<Task> {
    const teamId = await this.getTeamId();
    const { origin_product: originProduct, ...taskOptions } = options;

    const data = await this.withCloudUsageLimitCheck(() =>
      this.api.post(`/api/projects/{project_id}/tasks/`, {
        header: {
          "X-PostHog-Client-Provenance": this.taskClientProvenance,
        },
        path: { project_id: teamId.toString() },
        body: {
          ...taskOptions,
          origin_product: originProduct ?? "user_created",
        } as unknown as Schemas.TaskCreate,
      }),
    );

    return normalizeTaskResponse(data, { teamId });
  }

  async createSignalReportTask(options: {
    reportId: string;
    relationship: "implementation" | "discussion";
    description: string;
    title?: string;
    question?: string;
  }): Promise<Task> {
    return this.createTask({
      description: options.description,
      title: options.title,
      origin_product: "signal_report",
      signal_report: options.reportId,
      signal_report_task_relationship: options.relationship,
      ...(options.relationship === "discussion"
        ? { signal_report_discussion_question: options.question?.trim() ?? "" }
        : {}),
    });
  }

  async updateTask(
    taskId: string,
    updates: Schemas.PatchedTaskWrite,
  ): Promise<Task> {
    const teamId = await this.getTeamId();
    const data = await this.api.patch(
      `/api/projects/{project_id}/tasks/{id}/`,
      {
        path: { project_id: teamId.toString(), id: taskId },
        body: updates,
      },
    );

    return normalizeTaskResponse(data, { teamId });
  }

  /**
   * Mirror this device's archive state onto the task, so every client agrees on
   * what is archived — and so the list endpoint, which hides archived tasks,
   * counts what the app actually shows.
   */
  async setTaskArchived(taskId: string, archived: boolean): Promise<void> {
    await this.updateTask(taskId, { archived });
  }

  async deleteTask(taskId: string) {
    const teamId = await this.getTeamId();
    await this.api.delete(`/api/projects/{project_id}/tasks/{id}/`, {
      path: { project_id: teamId.toString(), id: taskId },
    });
  }

  async duplicateTask(taskId: string) {
    const task = await this.getTask(taskId);
    return this.createTask({
      description: task.description ?? "",
      title: task.title,
      repository: task.repository,
      json_schema: task.json_schema,
      origin_product: task.origin_product,
      github_integration: task.github_integration,
      github_user_integration: task.github_user_integration,
    });
  }

  // Task channels + threads. Not in the generated OpenAPI client yet, so these
  // go through the raw fetcher like the desktop file-system endpoints above.

  // All public channels plus the requester's #me. Creates nothing: startup provisions the
  // default spaces, which is what lets a caller gate on one already existing.
  async getTaskChannels(): Promise<TaskChannel[]> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/projects/${teamId}/task_channels/`;
    const response = await this.api.fetcher.fetch({
      method: "get",
      url: new URL(`${this.api.baseUrl}${urlPath}`),
      path: urlPath,
    });
    if (!response.ok) {
      throw new Error(`Failed to fetch task channels: ${response.statusText}`);
    }
    return (await response.json()) as TaskChannel[];
  }

  // Create a channel. A public channel (default) is resolve-or-create by name
  // (idempotent server-side). A private channel is always created fresh with the
  // requester plus `memberIds` as its members. `star` only applies when this call
  // creates the channel; an existing public one keeps the requester's star as it was.
  async resolveTaskChannel(
    name: string,
    options: {
      star: boolean;
      channelType?: "public" | "private";
      memberIds?: number[];
    },
  ): Promise<TaskChannel> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/projects/${teamId}/task_channels/`;
    const body: Record<string, unknown> = { name, star: options.star };
    if (options.channelType === "private") {
      body.channel_type = "private";
      body.member_ids = options.memberIds ?? [];
    }
    const response = await this.api.fetcher.fetch({
      method: "post",
      url: new URL(`${this.api.baseUrl}${urlPath}`),
      path: urlPath,
      overrides: {
        body: JSON.stringify(body),
      },
    });
    if (!response.ok) {
      throw new Error(`Failed to resolve task channel: ${response.statusText}`);
    }
    return (await response.json()) as TaskChannel;
  }

  // The members of a private channel. Public and personal channels have no
  // members and read as an empty list.
  async listTaskChannelMembers(id: string): Promise<UserBasic[]> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/projects/${teamId}/task_channels/${encodeURIComponent(id)}/members/`;
    const response = await this.api.fetcher.fetch({
      method: "get",
      url: new URL(`${this.api.baseUrl}${urlPath}`),
      path: urlPath,
    });
    if (!response.ok) {
      throw new Error(`Failed to fetch space members: ${response.statusText}`);
    }
    return (await response.json()) as UserBasic[];
  }

  // Replace a private channel's member set. The creator is always kept, whatever
  // `userIds` holds. Returns the updated members.
  async setTaskChannelMembers(
    id: string,
    userIds: number[],
  ): Promise<UserBasic[]> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/projects/${teamId}/task_channels/${encodeURIComponent(id)}/members/`;
    const response = await this.api.fetcher.fetch({
      method: "put",
      url: new URL(`${this.api.baseUrl}${urlPath}`),
      path: urlPath,
      overrides: { body: JSON.stringify({ user_ids: userIds }) },
    });
    if (!response.ok) {
      throw new Error(`Failed to update space members: ${response.statusText}`);
    }
    return (await response.json()) as UserBasic[];
  }

  async renameTaskChannel(id: string, name: string): Promise<TaskChannel> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/projects/${teamId}/task_channels/${encodeURIComponent(id)}/`;
    const response = await this.api.fetcher.fetch({
      method: "patch",
      url: new URL(`${this.api.baseUrl}${urlPath}`),
      path: urlPath,
      overrides: { body: JSON.stringify({ name }) },
    });
    if (!response.ok) {
      throw new Error(`Failed to rename task channel: ${response.statusText}`);
    }
    return (await response.json()) as TaskChannel;
  }

  async provisionDefaultTaskChannels(): Promise<ProvisionedTaskChannels> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/projects/${teamId}/task_channels/provision_defaults/`;
    const response = await this.api.fetcher.fetch({
      method: "post",
      url: new URL(`${this.api.baseUrl}${urlPath}`),
      path: urlPath,
    });
    if (!response.ok) {
      throw new Error(
        `Failed to provision default spaces: ${response.statusText}`,
      );
    }
    return (await response.json()) as ProvisionedTaskChannels;
  }

  /**
   * Opens the first-run agent session in #general. Reads the company's homepage, so it takes a
   * few seconds; callers fire it without awaiting. Resolves false when no session was started,
   * which is the normal path while the spaces rollout has not reached this user.
   */
  async startOnboardingSession(): Promise<string | null> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/projects/${teamId}/task_channels/onboarding_session/`;
    const response = await this.api.fetcher.fetch({
      method: "post",
      url: new URL(`${this.api.baseUrl}${urlPath}`),
      path: urlPath,
    });
    if (!response.ok) return null;
    const data = (await response.json()) as { task_id?: string | null };
    return data.task_id ?? null;
  }

  async startOnboardingTestSession(input: {
    company_domain: string;
    joining_existing_organization: boolean;
    has_events: boolean;
    signal_reports_waiting: number;
    other_members: string[];
    sources_enabled: string[];
    sources_watching: string[];
    sources_newly_enabled: boolean;
  }): Promise<{ task_id: string; channel_id: string }> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/projects/${teamId}/task_channels/onboarding_session_test/`;
    const response = await this.api.fetcher.fetch({
      method: "post",
      url: new URL(`${this.api.baseUrl}${urlPath}`),
      path: urlPath,
      overrides: { body: JSON.stringify(input) },
    });
    if (!response.ok) {
      throw new Error(
        `Failed to start test onboarding session: ${response.statusText}`,
      );
    }
    return (await response.json()) as { task_id: string; channel_id: string };
  }

  async createTeachingCanvasForTest(): Promise<{
    canvas_id: string;
    channel_id: string;
  }> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/projects/${teamId}/task_channels/teaching_canvas_test/`;
    const response = await this.api.fetcher.fetch({
      method: "post",
      url: new URL(`${this.api.baseUrl}${urlPath}`),
      path: urlPath,
    });
    if (!response.ok) {
      throw new Error(
        `Failed to create teaching canvas: ${response.statusText}`,
      );
    }
    return (await response.json()) as { canvas_id: string; channel_id: string };
  }

  async updateTaskChannelRepositories(
    id: string,
    githubIntegration: number | null,
    repositories: string[],
  ): Promise<TaskChannel> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/projects/${teamId}/task_channels/${encodeURIComponent(id)}/`;
    const response = await this.api.fetcher.fetch({
      method: "patch",
      url: new URL(`${this.api.baseUrl}${urlPath}`),
      path: urlPath,
      overrides: {
        body: JSON.stringify({
          github_integration: githubIntegration,
          repositories,
        }),
      },
    });
    if (!response.ok) {
      throw new Error(
        `Failed to update space repositories: ${response.statusText}`,
      );
    }
    return (await response.json()) as TaskChannel;
  }

  async updateTaskChannelType(
    id: string,
    channelType: "public" | "private",
  ): Promise<TaskChannel> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/projects/${teamId}/task_channels/${encodeURIComponent(id)}/`;
    const response = await this.api.fetcher.fetch({
      method: "patch",
      url: new URL(`${this.api.baseUrl}${urlPath}`),
      path: urlPath,
      overrides: { body: JSON.stringify({ channel_type: channelType }) },
    });
    if (!response.ok) {
      throw new Error(
        `Failed to update space visibility: ${response.statusText}`,
      );
    }
    return (await response.json()) as TaskChannel;
  }

  async updateTaskChannelAutoArchive(
    id: string,
    inactivityDays: number | null,
  ): Promise<TaskChannel> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/projects/${teamId}/task_channels/${encodeURIComponent(id)}/`;
    const response = await this.api.fetcher.fetch({
      method: "patch",
      url: new URL(`${this.api.baseUrl}${urlPath}`),
      path: urlPath,
      overrides: {
        body: JSON.stringify({ auto_archive_after_days: inactivityDays }),
      },
    });
    if (!response.ok) {
      throw new Error(
        `Failed to update automatic archiving: ${response.statusText}`,
      );
    }
    const updatedChannel = (await response.json()) as TaskChannel;
    if (updatedChannel.auto_archive_after_days !== inactivityDays) {
      throw new Error(
        "Automatic archiving isn't available on this server yet. Try again after it has been updated.",
      );
    }
    return updatedChannel;
  }

  async deleteTaskChannel(id: string): Promise<void> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/projects/${teamId}/task_channels/${encodeURIComponent(id)}/`;
    const response = await this.api.fetcher.fetch({
      method: "delete",
      url: new URL(`${this.api.baseUrl}${urlPath}`),
      path: urlPath,
    });
    if (!response.ok && response.status !== 404) {
      throw new Error(`Failed to delete task channel: ${response.statusText}`);
    }
  }

  async starTaskChannel(id: string, starred: boolean): Promise<void> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/projects/${teamId}/task_channels/${encodeURIComponent(id)}/star/`;
    const response = await this.api.fetcher.fetch({
      method: "post",
      url: new URL(`${this.api.baseUrl}${urlPath}`),
      path: urlPath,
      overrides: { body: JSON.stringify({ starred }) },
    });
    if (!response.ok) {
      throw new Error(`Failed to star task channel: ${response.statusText}`);
    }
  }

  async getChannelInstructions(
    channelId: string,
  ): Promise<ChannelInstructions | null> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/projects/${teamId}/task_channels/${encodeURIComponent(channelId)}/instructions/`;
    const response = await this.api.fetcher.fetch({
      method: "get",
      url: new URL(`${this.api.baseUrl}${urlPath}`),
      path: urlPath,
    });
    if (response.status === 404) return null;
    if (!response.ok) {
      throw new Error(
        `Failed to fetch channel instructions: ${response.statusText}`,
      );
    }
    return (await response.json()) as ChannelInstructions;
  }

  async putChannelInstructions(
    channelId: string,
    input: { content: string; baseVersion?: number },
  ): Promise<ChannelInstructions> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/projects/${teamId}/task_channels/${encodeURIComponent(channelId)}/instructions/`;
    const response = await this.api.fetcher.fetch({
      method: "put",
      url: new URL(`${this.api.baseUrl}${urlPath}`),
      path: urlPath,
      overrides: {
        body: JSON.stringify({
          content: input.content,
          ...(input.baseVersion !== undefined
            ? { base_version: input.baseVersion }
            : {}),
        }),
      },
    });
    if (response.status === 409) {
      throw new FolderInstructionsConflictError();
    }
    if (!response.ok) {
      throw new Error(
        `Failed to publish channel instructions: ${response.statusText}`,
      );
    }
    return (await response.json()) as ChannelInstructions;
  }

  async deleteChannelInstructions(channelId: string): Promise<void> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/projects/${teamId}/task_channels/${encodeURIComponent(channelId)}/instructions/`;
    const response = await this.api.fetcher.fetch({
      method: "delete",
      url: new URL(`${this.api.baseUrl}${urlPath}`),
      path: urlPath,
    });
    if (!response.ok && response.status !== 404) {
      throw new Error(
        `Failed to delete channel instructions: ${response.statusText}`,
      );
    }
  }

  async listChannelInstructionVersions(
    channelId: string,
  ): Promise<ChannelInstructionsVersion[]> {
    const maxPages = 20;
    const teamId = await this.getTeamId();
    const all: ChannelInstructionsVersion[] = [];
    let urlPath = `/api/projects/${teamId}/task_channels/${encodeURIComponent(channelId)}/instructions/versions/`;
    for (let i = 0; i < maxPages; i++) {
      const response = await this.api.fetcher.fetch({
        method: "get",
        url: new URL(`${this.api.baseUrl}${urlPath}`),
        path: urlPath,
      });
      if (!response.ok) {
        throw new Error(
          `Failed to fetch channel instruction versions: ${response.statusText}`,
        );
      }
      const body = (await response.json()) as
        | ChannelInstructionsVersion[]
        | { next: string | null; results: ChannelInstructionsVersion[] };
      if (Array.isArray(body)) return [...all, ...body];
      all.push(...body.results);
      if (!body.next) return all;
      const nextUrl = new URL(body.next);
      urlPath = `${nextUrl.pathname}${nextUrl.search}`;
    }
    log.warn("Channel instruction version pagination limit reached", {
      channelId,
      returned: all.length,
    });
    return all;
  }

  // ---- Organization context wiki (context_layer) ------------------------
  // Org-scoped: the wiki is one repo per organization, shared across projects.
  // 404 means the wiki was never enabled; 403 means it exists but is dark
  // because the organization has private projects.

  // GET with the wiki's shared read semantics: 404 (never enabled or missing
  // page) reads as null, 403 (privacy guard) as ContextWikiUnavailableError.
  private async getContextWikiResource<T>(urlPath: string): Promise<T | null> {
    try {
      const response = await this.api.fetcher.fetch({
        method: "get",
        url: new URL(`${this.api.baseUrl}${urlPath}`),
        path: urlPath,
      });
      return (await response.json()) as T;
    } catch (error) {
      if (error instanceof ApiRequestError) {
        if (error.status === 404) return null;
        if (error.status === 403) {
          throw new ContextWikiUnavailableError(readDetail(error));
        }
      }
      throw error;
    }
  }

  async getContextWikiTree(): Promise<ContextWikiTree | null> {
    return this.getContextWikiResource<ContextWikiTree>(
      `/api/organizations/@current/context_layer/tree/`,
    );
  }

  async getContextWikiPage(path: string): Promise<ContextWikiPage | null> {
    return this.getContextWikiResource<ContextWikiPage>(
      `/api/organizations/@current/context_layer/pages/?path=${encodeURIComponent(path)}`,
    );
  }

  async getContextWikiHealthReport(): Promise<ContextWikiHealthReport | null> {
    return this.getContextWikiResource<ContextWikiHealthReport>(
      `/api/organizations/@current/context_layer/wiki/report/`,
    );
  }

  async getChannelContextWikiPage(
    channelId: string,
  ): Promise<ChannelContextWikiPage | null> {
    return this.getContextWikiResource<ChannelContextWikiPage>(
      `/api/organizations/@current/context_layer/channel-pages/${encodeURIComponent(channelId)}/`,
    );
  }

  async getContextWikiDreams(): Promise<ContextWikiDreamList | null> {
    return this.getContextWikiResource<ContextWikiDreamList>(
      `/api/organizations/@current/context_layer/dreams/`,
    );
  }

  async getContextWikiDream(
    sha: string,
  ): Promise<ContextWikiDreamDetail | null> {
    return this.getContextWikiResource<ContextWikiDreamDetail>(
      `/api/organizations/@current/context_layer/dreams/${encodeURIComponent(sha)}/`,
    );
  }

  async getContextWikiProposals(): Promise<ContextWikiPageProposal[] | null> {
    const response = await this.getContextWikiResource<unknown>(
      "/api/organizations/@current/context_layer/proposals/",
    );
    return response === null
      ? null
      : contextWikiProposalsSchema.parse(response);
  }

  async applyContextWikiProposal(
    id: string,
  ): Promise<ContextWikiProposalApplyResult> {
    const path = `/api/organizations/@current/context_layer/proposals/${encodeURIComponent(id)}/apply/`;
    const response = await this.api.fetcher.fetch({
      method: "post",
      url: new URL(`${this.api.baseUrl}${path}`),
      path,
    });
    return contextWikiProposalApplyResultSchema.parse(await response.json());
  }

  /**
   * Full-content page write guarded by `baseHead` optimistic concurrency.
   * The server holds a per-org writer lock shared with agent commit landings;
   * a lock-busy 429 surfaces as ApiRequestError and is safe to retry with the
   * same base head — callers configure that retry (see
   * `useContextWikiPageMutation`). 409 (stale base head) and 400 (lint) are
   * the actionable failures.
   */
  async putContextWikiPage(input: {
    path: string;
    content: string;
    baseHead?: string;
  }): Promise<{ head_sha: string }> {
    const urlPath = `/api/organizations/@current/context_layer/pages/`;
    try {
      const response = await this.api.fetcher.fetch({
        method: "put",
        url: new URL(`${this.api.baseUrl}${urlPath}`),
        path: urlPath,
        overrides: {
          body: JSON.stringify({
            path: input.path,
            content: input.content,
            ...(input.baseHead ? { base_head: input.baseHead } : {}),
          }),
        },
      });
      return (await response.json()) as { head_sha: string };
    } catch (error) {
      if (!(error instanceof ApiRequestError)) throw error;
      if (error.status === 409) {
        const body = error.body as { current_head?: string } | null;
        throw new ContextWikiConflictError(body?.current_head ?? null);
      }
      if (error.status === 400) {
        const body = error.body as {
          detail?: string;
          errors?: string[];
        } | null;
        throw new ContextWikiLintError(
          body?.detail ?? "The change violates the wiki structure.",
          body?.errors ?? [],
        );
      }
      if (error.status === 403) {
        throw new ContextWikiUnavailableError(readDetail(error));
      }
      throw error;
    }
  }

  async enableContextWiki(): Promise<{ head_sha: string }> {
    const urlPath = `/api/organizations/@current/context_layer/enable/`;
    try {
      const response = await this.api.fetcher.fetch({
        method: "post",
        url: new URL(`${this.api.baseUrl}${urlPath}`),
        path: urlPath,
        overrides: { body: JSON.stringify({}) },
      });
      return (await response.json()) as { head_sha: string };
    } catch (error) {
      if (error instanceof ApiRequestError) {
        throw new Error(
          `Failed to enable the context wiki: ${readDetail(error)}`,
        );
      }
      throw error;
    }
  }

  // A channel's system-announcement feed (context created, CONTEXT.md being
  // built), chronological. Durable + team-visible, rendered alongside task cards.
  async getChannelFeed(channelId: string): Promise<ChannelFeedMessage[]> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/projects/${teamId}/task_channels/${channelId}/feed/`;
    const response = await this.api.fetcher.fetch({
      method: "get",
      url: new URL(`${this.api.baseUrl}${urlPath}`),
      path: urlPath,
    });
    if (!response.ok) {
      throw new Error(`Failed to fetch channel feed: ${response.statusText}`);
    }
    return (await response.json()) as ChannelFeedMessage[];
  }

  // Start the task that sets a space up for a goal or a feature. The server builds
  // the prompt and files the task into the channel.
  async setupTaskChannel(
    channelId: string,
    input: SpaceSetupInput,
  ): Promise<SpaceSetupStarted> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/projects/${teamId}/task_channels/${channelId}/setup/`;
    try {
      const response = await this.api.fetcher.fetch({
        method: "post",
        url: new URL(`${this.api.baseUrl}${urlPath}`),
        path: urlPath,
        overrides: {
          body: JSON.stringify(spaceSetupInputSchema.parse(input)),
        },
      });
      return spaceSetupStartedSchema.parse(await response.json());
    } catch (error) {
      throw new Error(
        extractRequestErrorMessage(
          error,
          "Could not start space setup. Try again.",
        ),
      );
    }
  }

  // Post a system announcement into a channel's feed. The row is authored by the
  // system; the server records the requester as `author` for "Adam …" rendering.
  async postChannelFeedMessage(
    channelId: string,
    input: {
      event: ChannelFeedMessageEvent;
      payload?: Record<string, unknown>;
      // Optional explicit timestamp (ISO) so a burst of announcements orders
      // deterministically instead of racing on server insert time.
      createdAt?: string;
    },
  ): Promise<ChannelFeedMessage> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/projects/${teamId}/task_channels/${channelId}/feed/`;
    const response = await this.api.fetcher.fetch({
      method: "post",
      url: new URL(`${this.api.baseUrl}${urlPath}`),
      path: urlPath,
      overrides: {
        body: JSON.stringify({
          event: input.event,
          payload: input.payload ?? {},
          ...(input.createdAt ? { created_at: input.createdAt } : {}),
        }),
      },
    });
    if (!response.ok) {
      throw new Error(
        `Failed to post channel feed message: ${response.statusText}`,
      );
    }
    return (await response.json()) as ChannelFeedMessage;
  }

  // Mentions of the current user across task threads, newest first.
  async getTaskMentions(options?: { since?: string }): Promise<TaskMention[]> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/projects/${teamId}/task_mentions/`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    if (options?.since) {
      url.searchParams.set("since", options.since);
    }
    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path: urlPath,
    });
    if (!response.ok) {
      throw new Error(`Failed to fetch task mentions: ${response.statusText}`);
    }
    return (await response.json()) as TaskMention[];
  }

  // Task lifecycle and individual comment activity, newest first.
  async getTaskActivity(options?: {
    before?: string;
    beforeId?: string;
  }): Promise<TaskActivityPage> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/projects/${teamId}/task_activity/`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    if (options?.before && options.beforeId) {
      url.searchParams.set("before", options.before);
      url.searchParams.set("before_id", options.beforeId);
    }
    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path: urlPath,
    });
    if (!response.ok) {
      throw new Error(`Failed to fetch task activity: ${response.statusText}`);
    }
    return (await response.json()) as TaskActivityPage;
  }

  // Task lifecycle activity clears by task timestamp; comment activity clears by row id.
  async markTaskActivityRead(
    activities: TaskActivityReadMarker[],
  ): Promise<TaskActivityMarkReadResult> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/projects/${teamId}/task_activity/mark_read/`;
    const response = await this.api.fetcher.fetch({
      method: "post",
      url: new URL(`${this.api.baseUrl}${urlPath}`),
      path: urlPath,
      overrides: {
        body: JSON.stringify({ activities }),
      },
    });
    if (!response.ok) {
      throw new Error(
        `Failed to mark task activity read: ${response.statusText}`,
      );
    }
    return (await response.json()) as TaskActivityMarkReadResult;
  }

  async getTaskThreadMessages(taskId: string): Promise<TaskThreadMessage[]> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/projects/${teamId}/tasks/${taskId}/thread_messages/`;
    const response = await this.api.fetcher.fetch({
      method: "get",
      url: new URL(`${this.api.baseUrl}${urlPath}`),
      path: urlPath,
    });
    if (!response.ok) {
      throw new Error(
        `Failed to fetch thread messages: ${response.statusText}`,
      );
    }
    return (await response.json()) as TaskThreadMessage[];
  }

  async createTaskThreadMessage(
    taskId: string,
    content: string,
  ): Promise<TaskThreadMessage> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/projects/${teamId}/tasks/${taskId}/thread_messages/`;
    const response = await this.api.fetcher.fetch({
      method: "post",
      url: new URL(`${this.api.baseUrl}${urlPath}`),
      path: urlPath,
      overrides: { body: JSON.stringify({ content }) },
    });
    if (!response.ok) {
      throw new Error(`Failed to post thread message: ${response.statusText}`);
    }
    return (await response.json()) as TaskThreadMessage;
  }

  async deleteTaskThreadMessage(
    taskId: string,
    messageId: string,
  ): Promise<void> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/projects/${teamId}/tasks/${taskId}/thread_messages/${encodeURIComponent(messageId)}/`;
    const response = await this.api.fetcher.fetch({
      method: "delete",
      url: new URL(`${this.api.baseUrl}${urlPath}`),
      path: urlPath,
    });
    if (!response.ok && response.status !== 404) {
      throw new Error(
        `Failed to delete thread message: ${response.statusText}`,
      );
    }
  }

  // Forward a thread message into the task's live run. Task author only; the
  // backend rejects with 400/403 otherwise (surfaced via the error body detail).
  async sendTaskThreadMessageToAgent(
    taskId: string,
    messageId: string,
  ): Promise<TaskThreadMessage> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/projects/${teamId}/tasks/${taskId}/thread_messages/${encodeURIComponent(messageId)}/send_to_agent/`;
    const response = await this.api.fetcher.fetch({
      method: "post",
      url: new URL(`${this.api.baseUrl}${urlPath}`),
      path: urlPath,
      overrides: { body: JSON.stringify({}) },
    });
    if (!response.ok) {
      const errorText = await response.text().catch(() => "");
      let message = `Failed to send message to agent: ${response.statusText}`;
      try {
        const parsed = JSON.parse(errorText) as { detail?: string };
        if (parsed.detail) message = parsed.detail;
      } catch {
        if (errorText) message = errorText;
      }
      throw new Error(message);
    }
    return (await response.json()) as TaskThreadMessage;
  }

  // Everyone in the current organization — the pool of taggable teammates for
  // thread @-mentions. Membership churn is slow, so callers cache aggressively.
  async listOrganizationMembers(): Promise<OrganizationMemberBasic[]> {
    const result = await this.listOrganizationMembersWithStatus();
    return result.members;
  }

  async listOrganizationMembersWithStatus(): Promise<{
    members: OrganizationMemberBasic[];
    isComplete: boolean;
  }> {
    const ORG_MEMBERS_MAX_PAGES = 20;
    const ORG_MEMBERS_PAGE_SIZE = 200;
    const all: OrganizationMemberBasic[] = [];
    let urlPath = `/api/organizations/@current/members/?limit=${ORG_MEMBERS_PAGE_SIZE}`;
    for (let i = 0; i < ORG_MEMBERS_MAX_PAGES; i++) {
      const response = await this.api.fetcher.fetch({
        method: "get",
        url: new URL(`${this.api.baseUrl}${urlPath}`),
        path: urlPath,
      });
      if (!response.ok) {
        throw new Error(
          `Failed to fetch organization members: ${response.statusText}`,
        );
      }
      const page = (await response.json()) as {
        results: OrganizationMemberBasic[];
        next: string | null;
      };
      all.push(...page.results);
      if (!page.next) return { members: all, isComplete: true };
      const nextUrl = new URL(page.next);
      urlPath = `${nextUrl.pathname}${nextUrl.search}`;
    }
    log.warn(
      `listOrganizationMembers hit MAX_PAGES (${ORG_MEMBERS_MAX_PAGES}); returning partial results`,
      { returned: all.length },
    );
    return { members: all, isComplete: false };
  }

  async sendRunCommand(
    taskId: string,
    runId: string,
    method: CloudRunCommandMethod,
    params?: Record<string, unknown>,
  ): Promise<{ success: boolean; result?: unknown; error?: string }> {
    try {
      return {
        success: true,
        result: await this.sendCloudRunCommand(taskId, runId, method, params),
      };
    } catch (error) {
      return {
        success: false,
        error: error instanceof Error ? error.message : "Unknown error",
      };
    }
  }

  async sendCloudRunCommand(
    taskId: string,
    runId: string,
    method: CloudRunCommandMethod,
    params: Record<string, unknown> = {},
  ): Promise<unknown> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/projects/${teamId}/tasks/${taskId}/runs/${runId}/command/`,
    );
    const body = {
      jsonrpc: "2.0",
      method,
      params,
      id: `posthog-code-${Date.now()}`,
    };

    try {
      const response = await this.api.fetcher.fetch({
        method: "post",
        url,
        path: `/api/projects/${teamId}/tasks/${taskId}/runs/${runId}/command/`,
        overrides: {
          body: JSON.stringify(body),
        },
      });

      const data = (await response.json()) as {
        error?: unknown;
        result?: unknown;
      };
      if (data.error) {
        const backendError = cloudCommandBackendError(data);
        throw new CloudCommandError(
          method,
          response.status,
          backendError,
          `Cloud command '${method}' error: ${backendError ?? JSON.stringify(data.error)}`,
        );
      }

      return data.result;
    } catch (error) {
      if (error instanceof CloudCommandError) throw error;
      if (error instanceof ApiRequestError) {
        this.throwIfCloudUsageLimit(error);
        const backendError = cloudCommandBackendError(error.body);
        throw new CloudCommandError(
          method,
          error.status,
          backendError,
          `Cloud command '${method}' failed: ${error.status}${backendError ? ` ${backendError}` : ""}`,
        );
      }
      throw error;
    }
  }

  async cancelTaskRun(
    taskId: string,
    runId: string,
    reason?: string,
    onlyIfAwaitingFirstMessage = false,
  ): Promise<{ status?: string }> {
    const teamId = await this.getTeamId();
    const path = `/api/projects/${teamId}/tasks/${taskId}/runs/${runId}/cancel/`;
    const response = await this.api.fetcher.fetch({
      method: "post",
      url: new URL(`${this.api.baseUrl}${path}`),
      path,
      overrides: {
        body: JSON.stringify({
          ...(reason ? { reason } : {}),
          ...(onlyIfAwaitingFirstMessage
            ? { only_if_awaiting_first_message: true }
            : {}),
        }),
      },
    });
    return (await response.json().catch(() => ({}))) as { status?: string };
  }

  async runTaskInCloud(
    taskId: string,
    branch?: string | null,
    options?: CloudRunOptions & {
      resumeFromRunId?: string;
      pendingUserMessage?: string;
      pendingUserArtifactIds?: string[];
    },
  ): Promise<Task> {
    const teamId = await this.getTeamId();
    const body = buildCloudRunRequestBody({
      ...options,
      branch,
      mode: "interactive",
    });

    const data = await this.withCloudUsageLimitCheck(() =>
      this.api.post(`/api/projects/{project_id}/tasks/{id}/run/`, {
        header: {},
        path: { project_id: teamId.toString(), id: taskId },
        body,
      }),
    );

    return normalizeTaskResponse(data, { teamId });
  }

  async warmTask(options: {
    repository?: string | null;
    repositories?: string[];
    github_integration?: number | null;
    branch?: string | null;
    runtime_adapter?: string | null;
    model?: string | null;
    reasoning_effort?: string | null;
    initial_permission_mode?: ExecutionMode | null;
    context_window?: "200k" | "1m" | null;
    fast_mode?: boolean | null;
    sandbox_environment_id?: string | null;
    custom_image_id?: string | null;
  }): Promise<{ task_id: string; run_id: string } | null> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/projects/${teamId}/tasks/warm/`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    const response = await this.withCloudUsageLimitCheck(() =>
      this.api.fetcher.fetch({
        method: "post",
        url,
        path: urlPath,
        parameters: {
          header: {
            "X-PostHog-Client-Provenance": this.taskClientProvenance,
          },
        },
        overrides: {
          body: JSON.stringify({
            repository: options.repository,
            repositories: options.repositories,
            github_integration: options.github_integration,
            branch: options.branch ?? null,
            runtime_adapter: options.runtime_adapter ?? null,
            model: options.model ?? null,
            reasoning_effort: options.reasoning_effort ?? null,
            initial_permission_mode: options.initial_permission_mode ?? null,
            ...(options.context_window
              ? { context_window: options.context_window }
              : {}),
            ...(options.fast_mode != null
              ? { fast_mode: options.fast_mode }
              : {}),
            ...(options.sandbox_environment_id
              ? { sandbox_environment_id: options.sandbox_environment_id }
              : {}),
            ...(options.custom_image_id
              ? { custom_image_id: options.custom_image_id }
              : {}),
          }),
        },
      }),
    );
    if (!response.ok) {
      throw new Error(`Failed to warm task: ${response.statusText}`);
    }
    const text = await response.text();
    if (!text) {
      return null;
    }
    return JSON.parse(text) as { task_id: string; run_id: string };
  }

  async prepareTaskStagedArtifactUploads(
    taskId: string,
    artifacts: TaskArtifactUploadRequest[],
  ): Promise<PreparedTaskArtifactUpload[]> {
    if (!artifacts.length) {
      return [];
    }

    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/projects/${teamId}/tasks/${taskId}/staged_artifacts/prepare_upload/`,
    );
    const response = await this.api.fetcher.fetch({
      method: "post",
      url,
      path: `/api/projects/${teamId}/tasks/${taskId}/staged_artifacts/prepare_upload/`,
      overrides: {
        body: JSON.stringify({ artifacts }),
      },
    });

    if (!response.ok) {
      throw new Error(
        `Failed to prepare staged uploads: ${response.statusText}`,
      );
    }

    const data = (await response.json()) as {
      artifacts?: PreparedTaskArtifactUpload[];
    };
    return data.artifacts ?? [];
  }

  async finalizeTaskStagedArtifactUploads(
    taskId: string,
    artifacts: PreparedTaskArtifactUpload[],
  ): Promise<FinalizedTaskArtifactUpload[]> {
    if (!artifacts.length) {
      return [];
    }

    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/projects/${teamId}/tasks/${taskId}/staged_artifacts/finalize_upload/`,
    );
    const response = await this.api.fetcher.fetch({
      method: "post",
      url,
      path: `/api/projects/${teamId}/tasks/${taskId}/staged_artifacts/finalize_upload/`,
      overrides: {
        body: JSON.stringify({
          artifacts: artifacts.map((artifact) => ({
            id: artifact.id,
            name: artifact.name,
            type: artifact.type,
            source: artifact.source,
            content_type: artifact.content_type,
            metadata: artifact.metadata,
            storage_path: artifact.storage_path,
          })),
        }),
      },
    });

    if (!response.ok) {
      throw new Error(
        `Failed to finalize staged uploads: ${response.statusText}`,
      );
    }

    const data = (await response.json()) as {
      artifacts?: FinalizedTaskArtifactUpload[];
    };
    return data.artifacts ?? [];
  }

  async prepareTaskRunArtifactUploads(
    taskId: string,
    runId: string,
    artifacts: TaskArtifactUploadRequest[],
  ): Promise<PreparedTaskArtifactUpload[]> {
    if (!artifacts.length) {
      return [];
    }

    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/projects/${teamId}/tasks/${taskId}/runs/${runId}/artifacts/prepare_upload/`,
    );
    const response = await this.api.fetcher.fetch({
      method: "post",
      url,
      path: `/api/projects/${teamId}/tasks/${taskId}/runs/${runId}/artifacts/prepare_upload/`,
      overrides: {
        body: JSON.stringify({ artifacts }),
      },
    });

    if (!response.ok) {
      throw new Error(`Failed to prepare uploads: ${response.statusText}`);
    }

    const data = (await response.json()) as {
      artifacts?: PreparedTaskArtifactUpload[];
    };
    return data.artifacts ?? [];
  }

  async finalizeTaskRunArtifactUploads(
    taskId: string,
    runId: string,
    artifacts: PreparedTaskArtifactUpload[],
  ): Promise<FinalizedTaskArtifactUpload[]> {
    if (!artifacts.length) {
      return [];
    }

    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/projects/${teamId}/tasks/${taskId}/runs/${runId}/artifacts/finalize_upload/`,
    );
    const response = await this.api.fetcher.fetch({
      method: "post",
      url,
      path: `/api/projects/${teamId}/tasks/${taskId}/runs/${runId}/artifacts/finalize_upload/`,
      overrides: {
        body: JSON.stringify({
          artifacts: artifacts.map((artifact) => ({
            id: artifact.id,
            name: artifact.name,
            type: artifact.type,
            source: artifact.source,
            content_type: artifact.content_type,
            metadata: artifact.metadata,
            storage_path: artifact.storage_path,
          })),
        }),
      },
    });

    if (!response.ok) {
      throw new Error(`Failed to finalize uploads: ${response.statusText}`);
    }

    const data = (await response.json()) as {
      artifacts?: FinalizedTaskArtifactUpload[];
    };
    return data.artifacts ?? [];
  }

  async registerTaskRunPostHogReferences(
    taskId: string,
    runId: string,
    references: PostHogObjectReferenceInput[],
  ): Promise<TaskRunArtifact[]> {
    if (references.length === 0) return [];
    const teamId = await this.getTeamId();
    const path = `/api/projects/${teamId}/tasks/${taskId}/runs/${runId}/artifacts/references/`;
    const response = await this.api.fetcher.fetch({
      method: "post",
      url: new URL(`${this.api.baseUrl}${path}`),
      path,
      overrides: { body: JSON.stringify({ references }) },
    });
    if (!response.ok) {
      throw new Error(`Failed to register references: ${response.statusText}`);
    }
    const data = (await response.json()) as {
      artifacts?: TaskRunArtifactDTO[];
    };
    return (data.artifacts ?? []).map(normalizeTaskRunArtifact);
  }

  async presignTaskRunArtifact(
    taskId: string,
    runId: string,
    storagePath: string,
  ): Promise<string> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/projects/${teamId}/tasks/${taskId}/runs/${runId}/artifacts/presign/`,
    );
    const response = await this.api.fetcher.fetch({
      method: "post",
      url,
      path: `/api/projects/${teamId}/tasks/${taskId}/runs/${runId}/artifacts/presign/`,
      overrides: {
        body: JSON.stringify({ storage_path: storagePath }),
      },
    });

    if (!response.ok) {
      throw new Error(
        `Failed to generate artifact preview URL: ${response.statusText}`,
      );
    }

    const data = (await response.json()) as { url: string };
    return data.url;
  }

  async getResourceComments(
    scope: CommentScope,
    itemId: string,
    taskId: string,
  ): Promise<ResourceComment[]> {
    const MAX_COMMENT_PAGES = 50;
    const teamId = await this.getTeamId();
    const comments: ResourceComment[] = [];
    let cursor: string | undefined;
    for (let pageIndex = 0; pageIndex < MAX_COMMENT_PAGES; pageIndex++) {
      const page = await this.api.get("/api/projects/{project_id}/comments/", {
        path: { project_id: String(teamId) },
        query: { scope, item_id: itemId, task_id: taskId, cursor },
      });
      comments.push(...page.results);
      cursor = page.next
        ? (new URL(page.next).searchParams.get("cursor") ?? undefined)
        : undefined;
      if (!cursor) return comments;
    }
    log.warn(
      `getResourceComments hit MAX_PAGES (${MAX_COMMENT_PAGES}); returning partial results`,
      { scope, itemId, returned: comments.length },
    );
    return comments;
  }

  async createResourceComment(
    request: CreateResourceCommentRequest,
  ): Promise<ResourceComment> {
    const teamId = await this.getTeamId();
    const payload = {
      content: request.content,
      scope: request.scope,
      item_id: request.itemId,
      item_context: request.context,
      source_comment: request.sourceCommentId ?? null,
      mentions: request.mentions ?? [],
      // Resolution is represented by a thread-state reply so this stays on the
      // same PAT-compatible write path as ordinary comments.
      is_task: false,
    };
    return await this.api.post("/api/projects/{project_id}/comments/", {
      path: { project_id: String(teamId) },
      body: payload as unknown as Schemas.Comment,
    });
  }

  /** Hide or restore every version of a file on the run, returning the updated manifest. */
  async setTaskRunArtifactsDismissed(
    taskId: string,
    runId: string,
    artifactIds: string[],
    dismissed: boolean,
  ): Promise<TaskRunArtifact[]> {
    const teamId = await this.getTeamId();
    const path = `/api/projects/${teamId}/tasks/${taskId}/runs/${runId}/artifacts/dismiss/`;
    const response = await this.api.fetcher.fetch({
      method: "post",
      url: new URL(`${this.api.baseUrl}${path}`),
      path,
      overrides: {
        body: JSON.stringify({ artifact_ids: artifactIds, dismissed }),
      },
    });

    if (!response.ok) {
      throw new Error(`Failed to update artifact: ${response.statusText}`);
    }

    const data = (await response.json()) as {
      artifacts?: TaskRunArtifactDTO[];
    };
    return (data.artifacts ?? []).map(normalizeTaskRunArtifact);
  }

  async getTaskSessionStorageAccess(
    taskId: string,
    runId: string,
  ): Promise<TaskSessionStorageAccess | null> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/projects/${teamId}/tasks/${taskId}/runs/${runId}/task_session/`,
    );
    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path: `/api/projects/${teamId}/tasks/${taskId}/runs/${runId}/task_session/`,
    });
    if (response.status === 404) {
      return null;
    }
    if (!response.ok) {
      throw new Error(`Failed to load task session: ${response.statusText}`);
    }

    return (await response.json()) as TaskSessionStorageAccess;
  }

  async resumeRunInCloud(taskId: string, runId: string): Promise<TaskRun> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/projects/${teamId}/tasks/${taskId}/runs/${runId}/resume_in_cloud/`,
    );
    const response = await this.withCloudUsageLimitCheck(() =>
      this.api.fetcher.fetch({
        method: "post",
        url,
        path: `/api/projects/${teamId}/tasks/${taskId}/runs/${runId}/resume_in_cloud/`,
      }),
    );

    if (!response.ok) {
      throw new Error(`Failed to resume run in cloud: ${response.statusText}`);
    }

    const data = (await response.json()) as Schemas.TaskRunDetailDTO;
    return normalizeTaskRunResponse(data, { teamId, taskId });
  }

  async listTaskRuns(taskId: string): Promise<TaskRun[]> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/projects/${teamId}/tasks/${taskId}/runs/`,
    );
    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path: `/api/projects/${teamId}/tasks/${taskId}/runs/`,
    });

    if (!response.ok) {
      throw new Error(`Failed to fetch task runs: ${response.statusText}`);
    }

    const data =
      (await response.json()) as Partial<Schemas.PaginatedTaskRunDetailDTOList>;
    return (data.results ?? []).map((run) =>
      normalizeTaskRunResponse(run, { teamId, taskId }),
    );
  }

  async getTaskRun(taskId: string, runId: string): Promise<TaskRun> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/projects/${teamId}/tasks/${taskId}/runs/${runId}/`,
    );
    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path: `/api/projects/${teamId}/tasks/${taskId}/runs/${runId}/`,
    });

    if (!response.ok) {
      throw new Error(`Failed to fetch task run: ${response.statusText}`);
    }

    const data = (await response.json()) as Schemas.TaskRunDetailDTO;
    return normalizeTaskRunResponse(data, { teamId, taskId });
  }

  async createTaskRun(
    taskId: string,
    options?: CreateTaskRunOptions,
  ): Promise<TaskRun> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/projects/${teamId}/tasks/${taskId}/runs/`,
    );
    const response = await this.withCloudUsageLimitCheck(() =>
      this.api.fetcher.fetch({
        method: "post",
        url,
        path: `/api/projects/${teamId}/tasks/${taskId}/runs/`,
        overrides: {
          body: JSON.stringify({
            ...buildCloudRunRequestBody({
              ...options,
              mode: options?.mode ?? "background",
            }),
            environment: options?.environment ?? "local",
          }),
        },
      }),
    );

    if (!response.ok) {
      throw new Error(`Failed to create task run: ${response.statusText}`);
    }

    const data = (await response.json()) as Schemas.TaskRunDetailDTO;
    return normalizeTaskRunResponse(data, { teamId, taskId });
  }

  async startTaskRun(
    taskId: string,
    runId: string,
    options?: StartTaskRunOptions,
  ): Promise<Task> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/projects/${teamId}/tasks/${taskId}/runs/${runId}/start/`,
    );
    const response = await this.withCloudUsageLimitCheck(() =>
      this.api.fetcher.fetch({
        method: "post",
        url,
        path: `/api/projects/${teamId}/tasks/${taskId}/runs/${runId}/start/`,
        overrides: {
          body: JSON.stringify({
            pending_user_message: options?.pendingUserMessage,
            pending_user_artifact_ids: options?.pendingUserArtifactIds,
          }),
        },
      }),
    );

    if (!response.ok) {
      throw new Error(`Failed to start task run: ${response.statusText}`);
    }

    const data = (await response.json()) as Schemas.TaskDetailDTO;
    return normalizeTaskResponse(data, { teamId });
  }

  async updateTaskRun(
    taskId: string,
    runId: string,
    updates: Partial<
      Pick<
        TaskRun,
        "status" | "branch" | "stage" | "error_message" | "output" | "state"
      >
    > & {
      state_append?: Record<string, unknown>;
    },
  ): Promise<TaskRun> {
    const teamId = await this.getTeamId();
    const data = await this.api.patch(
      `/api/projects/{project_id}/tasks/{task_id}/runs/{id}/`,
      {
        path: {
          project_id: teamId.toString(),
          task_id: taskId,
          id: runId,
        },
        body: updates as Record<string, unknown>,
      },
    );
    return normalizeTaskRunResponse(data, { teamId, taskId });
  }

  async analyzeTaskRun(
    taskId: string,
    runId: string,
  ): Promise<{ analysis_task_id: string; created: boolean }> {
    const teamId = await this.getTeamId();
    return await this.api.post(
      `/api/projects/{project_id}/tasks/{task_id}/runs/{id}/analyze/`,
      {
        path: {
          project_id: teamId.toString(),
          task_id: taskId,
          id: runId,
        },
      },
    );
  }

  /**
   * Append events to a task run's S3 log file
   */
  async appendTaskRunLog(
    taskId: string,
    runId: string,
    entries: StoredLogEntry[],
  ): Promise<void> {
    const teamId = await this.getTeamId();
    const url = `${this.api.baseUrl}/api/projects/${teamId}/tasks/${taskId}/runs/${runId}/append_log/`;
    const response = await this.api.fetcher.fetch({
      method: "post",
      url: new URL(url),
      path: url,
      overrides: {
        body: JSON.stringify({ entries }),
      },
    });
    if (!response.ok) {
      throw new Error(`Failed to append log: ${response.statusText}`);
    }
  }

  /**
   * Record a `/clear` boundary in a finished run's log, so the next run in the
   * chain resumes past it with an empty conversation. Only valid for a finished
   * run, because an active one has an agent that owns the clear (409 otherwise).
   */
  async clearTaskRunConversation(taskId: string, runId: string): Promise<void> {
    const teamId = await this.getTeamId();
    const path = `/api/projects/${teamId}/tasks/${taskId}/runs/${runId}/clear_conversation/`;
    const url = new URL(`${this.api.baseUrl}${path}`);

    // The shared fetcher throws `Failed request: [<status>] <json-body>` for any non-2xx, so
    // unwrap that into the endpoint's clean `error` message rather than surfacing the raw string.
    try {
      await this.api.fetcher.fetch({ method: "post", url, path });
    } catch (error) {
      throw new Error(
        extractRequestErrorMessage(error, "Couldn’t clear the conversation."),
      );
    }
  }

  // AbortController + setTimeout because Hermes, which runs this client on
  // mobile, has no AbortSignal.timeout.
  private async fetchSessionLogsPage(
    url: URL,
    path: string,
    offset: number,
  ): Promise<SessionLogsPage> {
    for (let attempt = 0; ; attempt++) {
      const controller = new AbortController();
      const timer = setTimeout(
        () =>
          controller.abort(new Error("Session logs page request timed out")),
        SESSION_LOGS_PAGE_TIMEOUT_MS,
      );
      try {
        const response = await this.api.fetcher.fetch({
          method: "get",
          url,
          path,
          overrides: { signal: controller.signal },
        });
        if (!response.ok) {
          return {
            ok: false,
            status: response.status,
            statusText: response.statusText,
          };
        }
        // Read the body here, while the timer is still armed: fetch resolves on
        // headers, and a page body stalling after them is what wedges hydration.
        const entries = (await response.json()) as StoredLogEntry[];
        return { ok: true, entries, headers: response.headers };
      } catch (err) {
        const status = requestErrorStatus(err);
        const retryable = status === undefined || status >= 500;
        if (attempt > 0 || !retryable) throw err;
        log.warn(`Retrying session logs page at offset ${offset}`, err);
      } finally {
        clearTimeout(timer);
      }
    }
  }

  async getTaskRunSessionLogsPage(
    taskId: string,
    runId: string,
    options: { limit: number; offset?: number; after?: string },
  ): Promise<TaskRunSessionLogsPage> {
    const teamId = await this.getTeamId();
    const path = `/api/projects/${teamId}/tasks/${taskId}/runs/${runId}/session_logs/`;
    const url = new URL(`${this.api.baseUrl}${path}`);
    url.searchParams.set("limit", String(options.limit));
    if (options.offset) {
      url.searchParams.set("offset", String(options.offset));
    }
    if (options.after) {
      url.searchParams.set("after", options.after);
    }
    const page = await this.fetchSessionLogsPage(
      url,
      path,
      options.offset ?? 0,
    );
    if (!page.ok) {
      throw new Error(
        `Failed to fetch session logs page at offset ${options.offset ?? 0}: ${page.status} ${page.statusText}`,
      );
    }
    // Number(null) is 0, so an absent header must stay null.
    const matchingHeader = page.headers.get("X-Matching-Count");
    const matchingCount =
      matchingHeader === null ? null : Number(matchingHeader);
    return {
      entries: page.entries,
      hasMore: page.headers.get("X-Has-More") === "true",
      matchingCount:
        matchingCount !== null && Number.isFinite(matchingCount)
          ? matchingCount
          : null,
    };
  }

  async getTaskRunSessionLogsResult(
    taskId: string,
    runId: string,
    options?: { limit?: number; after?: string },
  ): Promise<TaskRunSessionLogsResult> {
    const maxEntries = options?.limit ?? SESSION_LOGS_MAX_PAGE_SIZE;
    const entries: StoredLogEntry[] = [];
    let truncatedHeadCount = 0;
    try {
      let offset = 0;
      let isFirstPage = true;
      while (entries.length < maxEntries) {
        const page = await this.getTaskRunSessionLogsPage(taskId, runId, {
          limit: Math.min(
            SESSION_LOGS_MAX_PAGE_SIZE,
            maxEntries - entries.length,
          ),
          offset,
          after: options?.after,
        });
        if (isFirstPage) {
          isFirstPage = false;
          if (page.matchingCount !== null && page.matchingCount > maxEntries) {
            // Restart from the tail so the newest maxEntries survive the cap.
            truncatedHeadCount = page.matchingCount - maxEntries;
            offset = truncatedHeadCount;
            continue;
          }
        }
        entries.push(...page.entries);
        if (!page.hasMore || page.entries.length === 0) {
          return { entries, complete: true, truncatedHeadCount };
        }
        offset += page.entries.length;
      }
      // A deliberate tail fetch is complete; capping out without a matching
      // count means unknown loss.
      return { entries, complete: truncatedHeadCount > 0, truncatedHeadCount };
    } catch (err) {
      log.warn("Failed to fetch task run session logs", err);
      return { entries, complete: false, truncatedHeadCount };
    }
  }

  async getIntegrations() {
    const teamId = await this.getTeamId();
    return this.getIntegrationsForProject(teamId);
  }

  async getIntegrationsForProject(projectId: number) {
    const url = new URL(
      `${this.api.baseUrl}/api/environments/${projectId}/integrations/`,
    );
    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path: `/api/environments/${projectId}/integrations/`,
    });

    if (!response.ok) {
      throw new Error(`Failed to fetch integrations: ${response.statusText}`);
    }

    const data = (await response.json()) as {
      results?: { kind: string; id: number | string; [key: string]: unknown }[];
    };
    return data.results ?? [];
  }

  async getGithubBranches(
    integrationId: string | number,
    repo: string,
  ): Promise<{ branches: string[]; defaultBranch: string | null }> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/environments/${teamId}/integrations/${integrationId}/github_branches/`,
    );
    url.searchParams.set("repo", repo);
    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path: `/api/environments/${teamId}/integrations/${integrationId}/github_branches/`,
    });

    if (!response.ok) {
      throw new Error(
        `Failed to fetch GitHub branches: ${response.statusText}`,
      );
    }

    const data = (await response.json()) as {
      branches?: string[];
      results?: string[];
      default_branch?: string | null;
    };
    return {
      branches: data.branches ?? data.results ?? [],
      defaultBranch: data.default_branch ?? null,
    };
  }

  async getGithubBranchesPage(
    integrationId: string | number,
    repo: string,
    offset: number,
    limit: number,
    search?: string,
  ): Promise<{
    branches: string[];
    defaultBranch: string | null;
    hasMore: boolean;
  }> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/environments/${teamId}/integrations/${integrationId}/github_branches/`,
    );
    url.searchParams.set("repo", repo);
    url.searchParams.set("offset", String(offset));
    url.searchParams.set("limit", String(limit));
    if (search?.trim()) {
      url.searchParams.set("search", search.trim());
    }
    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path: `/api/environments/${teamId}/integrations/${integrationId}/github_branches/`,
    });

    if (!response.ok) {
      throw new Error(
        `Failed to fetch GitHub branches: ${response.statusText}`,
      );
    }

    const data = (await response.json()) as {
      branches?: string[];
      results?: string[];
      default_branch?: string | null;
      has_more?: boolean;
    };
    return {
      branches: data.branches ?? data.results ?? [],
      defaultBranch: data.default_branch ?? null,
      hasMore: data.has_more ?? false,
    };
  }

  async getGithubUserBranchesPage(
    installationId: string | number,
    repo: string,
    offset: number,
    limit: number,
    search?: string,
  ): Promise<{
    branches: string[];
    defaultBranch: string | null;
    hasMore: boolean;
  }> {
    const urlPath = `/api/users/@me/integrations/github/${installationId}/branches/`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    url.searchParams.set("repo", repo);
    url.searchParams.set("offset", String(offset));
    url.searchParams.set("limit", String(limit));
    if (search?.trim()) {
      url.searchParams.set("search", search.trim());
    }
    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path: urlPath,
    });

    if (!response.ok) {
      throw new Error(
        `Failed to fetch personal GitHub branches: ${response.statusText}`,
      );
    }

    const data = (await response.json()) as {
      branches?: string[];
      results?: string[];
      default_branch?: string | null;
      has_more?: boolean;
    };
    return {
      branches: data.branches ?? data.results ?? [],
      defaultBranch: data.default_branch ?? null,
      hasMore: data.has_more ?? false,
    };
  }

  async getGithubRepositories(
    integrationId: string | number,
  ): Promise<string[]> {
    const repositories: string[] = [];
    let offset = 0;

    while (true) {
      const page = await this.getGithubRepositoriesPage(
        integrationId,
        offset,
        500,
      );
      repositories.push(...page.repositories);

      if (!page.hasMore) {
        return repositories;
      }

      offset += page.repositories.length;
    }
  }

  async getGithubRepositoriesPage(
    integrationId: string | number,
    offset: number,
    limit: number,
    search?: string,
  ): Promise<{
    repositories: string[];
    hasMore: boolean;
    total: number | null;
  }> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/environments/${teamId}/integrations/${integrationId}/github_repos/`,
    );
    url.searchParams.set("offset", String(offset));
    url.searchParams.set("limit", String(limit));
    if (search?.trim()) {
      url.searchParams.set("search", search.trim());
    }
    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path: `/api/environments/${teamId}/integrations/${integrationId}/github_repos/`,
    });

    if (!response.ok) {
      throw new Error(
        `Failed to fetch GitHub repositories: ${response.statusText}`,
      );
    }

    const data = (await response.json()) as {
      has_more?: boolean;
      total?: number;
    };
    return {
      repositories: this.normalizeGithubRepositories(data),
      hasMore: data.has_more ?? false,
      total: typeof data.total === "number" ? data.total : null,
    };
  }

  async getGithubUserRepositories(
    installationId: string | number,
  ): Promise<string[]> {
    const repositories: string[] = [];
    let offset = 0;

    while (true) {
      const page = await this.getGithubUserRepositoriesPage(
        installationId,
        offset,
        500,
      );
      repositories.push(...page.repositories);

      if (!page.hasMore) {
        return repositories;
      }

      offset += page.repositories.length;
    }
  }

  async getGithubUserRepositoriesPage(
    installationId: string | number,
    offset: number,
    limit: number,
    search?: string,
  ): Promise<{
    repositories: string[];
    hasMore: boolean;
    total: number | null;
  }> {
    const urlPath = `/api/users/@me/integrations/github/${installationId}/repos/`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    url.searchParams.set("offset", String(offset));
    url.searchParams.set("limit", String(limit));
    if (search?.trim()) {
      url.searchParams.set("search", search.trim());
    }
    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path: urlPath,
    });

    if (!response.ok) {
      throw new Error(
        `Failed to fetch personal GitHub repositories: ${response.statusText}`,
      );
    }

    const data = (await response.json()) as {
      has_more?: boolean;
      total?: number;
    };
    return {
      repositories: this.normalizeGithubRepositories(data),
      hasMore: data.has_more ?? false,
      total: typeof data.total === "number" ? data.total : null,
    };
  }

  async refreshGithubRepositories(
    integrationId: string | number,
  ): Promise<string[]> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/environments/${teamId}/integrations/${integrationId}/github_repos/refresh/`,
    );
    const response = await this.api.fetcher.fetch({
      method: "post",
      url,
      path: `/api/environments/${teamId}/integrations/${integrationId}/github_repos/refresh/`,
    });

    if (!response.ok) {
      throw new Error(
        `Failed to refresh GitHub repositories: ${response.statusText}`,
      );
    }

    const data: unknown = await response.json();
    return this.normalizeGithubRepositories(data);
  }

  async refreshGithubUserRepositories(
    installationId: string | number,
  ): Promise<string[]> {
    const urlPath = `/api/users/@me/integrations/github/${installationId}/repos/refresh/`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    const response = await this.api.fetcher.fetch({
      method: "post",
      url,
      path: urlPath,
    });

    if (!response.ok) {
      throw new Error(
        `Failed to refresh personal GitHub repositories: ${response.statusText}`,
      );
    }

    const data: unknown = await response.json();
    return this.normalizeGithubRepositories(data);
  }

  private normalizeGithubRepositories(data: unknown): string[] {
    const repos =
      (data as { repositories?: unknown[] }).repositories ??
      (data as { results?: unknown[] }).results ??
      (Array.isArray(data) ? data : []);

    return (repos as (string | { full_name?: string; name?: string })[]).map(
      (repo) => {
        if (typeof repo === "string") return repo;
        return (repo.full_name ?? repo.name ?? "").toLowerCase();
      },
    );
  }

  async getAgents() {
    const teamId = await this.getTeamId();
    const url = new URL(`${this.api.baseUrl}/api/projects/${teamId}/agents/`);
    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path: `/api/projects/${teamId}/agents/`,
    });

    if (!response.ok) {
      throw new Error(`Failed to fetch agents: ${response.statusText}`);
    }

    const data = (await response.json()) as { results?: unknown[] };
    return data.results ?? [];
  }

  async getUsers() {
    const data = (await this.api.get("/api/users/", {
      query: { limit: 1000 },
    })) as unknown as { results: Schemas.User[] } | Schemas.User[];
    return Array.isArray(data) ? data : (data.results ?? []);
  }

  async updateTeam(updates: {
    session_recording_opt_in?: boolean;
    autocapture_exceptions_opt_in?: boolean;
  }): Promise<Schemas.ProjectBackwardCompat> {
    const teamId = await this.getTeamId();
    const url = new URL(`${this.api.baseUrl}/api/projects/${teamId}/`);
    const response = await this.api.fetcher.fetch({
      method: "patch",
      url,
      path: `/api/projects/${teamId}/`,
      overrides: {
        body: JSON.stringify(updates),
      },
    });

    if (!response.ok) {
      const responseText = await response.text();
      let detail = responseText;
      try {
        const parsed = JSON.parse(responseText) as
          | { detail?: string }
          | Record<string, unknown>;
        if (
          typeof parsed === "object" &&
          parsed !== null &&
          "detail" in parsed &&
          typeof parsed.detail === "string"
        ) {
          detail = parsed.detail;
        } else if (typeof parsed === "object" && parsed !== null) {
          detail = Object.entries(parsed)
            .map(([key, value]) => `${key}: ${JSON.stringify(value)}`)
            .join(", ");
        }
      } catch {
        // keep plain text fallback
      }

      throw new Error(
        `Failed to update team: ${detail || response.statusText}`,
      );
    }

    return (await response.json()) as Schemas.ProjectBackwardCompat;
  }

  async getSignalReport(reportId: string): Promise<SignalReport | null> {
    const teamId = await this.getTeamId();
    const path = `/api/projects/${teamId}/signals/reports/${reportId}/`;
    const url = new URL(`${this.api.baseUrl}${path}`);

    try {
      const response = await this.api.fetcher.fetch({
        method: "get",
        url,
        path,
      });
      return (await response.json()) as SignalReport;
    } catch (error) {
      // The shared fetcher throws "Failed request: [<status>] <body>" for any
      // non-2xx. Treat missing / forbidden as "not available in the current
      // team" and surface other errors to the caller.
      const msg = error instanceof Error ? error.message : String(error);
      if (msg.includes("[404]") || msg.includes("[403]")) {
        return null;
      }
      throw error;
    }
  }

  async getReportReadStates(
    reportIds: string[],
    read?: boolean,
  ): Promise<Record<string, boolean>> {
    const teamId = await this.getTeamId();
    const data = await this.api.post(
      "/api/projects/{project_id}/signals/reports/read_state/",
      {
        path: { project_id: teamId.toString() },
        body: {
          report_ids: reportIds,
          ...(read === undefined ? {} : { read }),
        },
      },
    );
    return data.states;
  }

  private readRequests = new Map<
    string,
    { resolve: (read: boolean) => void; reject: (error: unknown) => void }[]
  >();

  getReportReadState(reportId: string): Promise<boolean> {
    const pending = this.readRequests;
    const first = pending.size === 0;
    const result = new Promise<boolean>((resolve, reject) => {
      pending.set(reportId, [
        ...(pending.get(reportId) ?? []),
        { resolve, reject },
      ]);
    });
    if (first)
      queueMicrotask(() => {
        const entries = [...pending.entries()];
        pending.clear();
        for (let offset = 0; offset < entries.length; offset += 100) {
          const batch = entries.slice(offset, offset + 100);
          void this.getReportReadStates(batch.map(([id]) => id))
            .then((states) => {
              for (const [id, listeners] of batch)
                for (const listener of listeners)
                  listener.resolve(states[id] === true);
            })
            .catch((error) => {
              for (const [, listeners] of batch)
                for (const listener of listeners) listener.reject(error);
            });
        }
      });
    return result;
  }

  async getSignalReports(
    params?: SignalReportsQueryParams,
  ): Promise<SignalReportsResponse> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/projects/${teamId}/signals/reports/`,
    );

    if (params?.limit != null) {
      url.searchParams.set("limit", String(params.limit));
    }
    if (params?.offset != null) {
      url.searchParams.set("offset", String(params.offset));
    }
    if (params?.status) {
      url.searchParams.set("status", params.status);
    }
    if (params?.ordering) {
      url.searchParams.set("ordering", params.ordering);
    }
    if (params?.search) url.searchParams.set("search", params.search);
    if (params?.unread !== undefined)
      url.searchParams.set("unread", String(params.unread));
    if (params?.source_product) {
      url.searchParams.set("source_product", params.source_product);
    }
    if (params?.suggested_reviewers) {
      url.searchParams.set("suggested_reviewers", params.suggested_reviewers);
    }
    if (params?.priority) {
      url.searchParams.set("priority", params.priority);
    }
    if (params?.actionability) {
      url.searchParams.set("actionability", params.actionability);
    }
    if (params?.count_only != null) {
      url.searchParams.set("count_only", String(params.count_only));
    }
    if (params?.has_implementation_pr != null) {
      url.searchParams.set(
        "has_implementation_pr",
        String(params.has_implementation_pr),
      );
    }
    if (params?.channel_id) {
      url.searchParams.set("channel_id", params.channel_id);
    }

    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path: `/api/projects/${teamId}/signals/reports/`,
    });

    if (!response.ok) {
      throw new Error(`Failed to fetch signal reports: ${response.statusText}`);
    }

    const data = (await response.json()) as {
      results?: SignalReport[];
      count?: number;
    };
    return {
      results: data.results ?? [],
      count: data.count ?? data.results?.length ?? 0,
    };
  }

  async getSignalReportSectionCounts(
    params?: SignalReportSectionCountsParams,
  ): Promise<SignalReportSectionCounts> {
    const teamId = await this.getTeamId();
    const path = `/api/projects/${teamId}/signals/reports/section_counts/`;
    const url = new URL(`${this.api.baseUrl}${path}`);
    if (params?.source_product) {
      url.searchParams.set("source_product", params.source_product);
    }
    if (params?.priority) url.searchParams.set("priority", params.priority);
    if (params?.suggested_reviewers) {
      url.searchParams.set("suggested_reviewers", params.suggested_reviewers);
    }

    const response = await this.api.fetcher.fetch({ method: "get", url, path });
    if (!response.ok) {
      throw new Error(
        `Failed to fetch signal report section counts: ${response.statusText}`,
      );
    }
    return (await response.json()) as SignalReportSectionCounts;
  }

  async getSignalProcessingState(): Promise<SignalProcessingStateResponse> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/projects/${teamId}/signals/processing/`,
    );
    const path = `/api/projects/${teamId}/signals/processing/`;

    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path,
    });

    if (!response.ok) {
      throw new Error(
        `Failed to fetch signal processing state: ${response.statusText}`,
      );
    }

    const data = (await response.json()) as { paused_until?: string | null };
    return {
      paused_until:
        typeof data?.paused_until === "string" ? data.paused_until : null,
    };
  }

  async getAvailableSuggestedReviewers(
    query?: string,
  ): Promise<AvailableSuggestedReviewersResponse> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/projects/${teamId}/signals/reports/available_reviewers/`,
    );
    const path = `/api/projects/${teamId}/signals/reports/available_reviewers/`;

    if (query?.trim()) {
      url.searchParams.set("query", query.trim());
    }

    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path,
    });

    if (!response.ok) {
      throw new Error(
        `Failed to fetch available suggested reviewers: ${response.statusText}`,
      );
    }

    return parseAvailableSuggestedReviewersPayload(await response.json());
  }

  async getSignalReportSignals(
    reportId: string,
  ): Promise<SignalReportSignalsResponse> {
    try {
      const teamId = await this.getTeamId();
      const url = new URL(
        `${this.api.baseUrl}/api/projects/${teamId}/signals/reports/${reportId}/signals/`,
      );
      const response = await this.api.fetcher.fetch({
        method: "get",
        url,
        path: `/api/projects/${teamId}/signals/reports/${reportId}/signals/`,
      });

      if (!response.ok) {
        log.warn("Signal report signals unavailable", {
          reportId,
          status: response.status,
        });
        return { report: null, signals: [] };
      }

      const data = (await response.json()) as {
        report?: SignalReport | null;
        signals?: Signal[];
      };
      return {
        report: data.report ?? null,
        signals: data.signals ?? [],
      };
    } catch (error) {
      log.warn("Failed to fetch signal report signals", { reportId, error });
      return { report: null, signals: [] };
    }
  }

  /**
   * The list is newest-first and truncates to the server page size, which drops the oldest
   * rows — including the scout `task_run` written when the report was created. Pass `limit`
   * from callers that read the whole log. Callers that need only the newest row of a
   * latest-wins type should omit it: artefacts carry diffs and code excerpts, and list rows
   * fetch this once per card.
   */
  async getSignalReportArtefacts(
    reportId: string,
    options?: { limit?: number },
  ): Promise<SignalReportArtefactsResponse> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/projects/${teamId}/signals/reports/${reportId}/artefacts/`,
    );
    const path = `/api/projects/${teamId}/signals/reports/${reportId}/artefacts/`;
    if (options?.limit !== undefined) {
      url.searchParams.set("limit", String(options.limit));
    }

    try {
      const response = await this.api.fetcher.fetch({
        method: "get",
        url,
        path,
      });

      if (!response.ok) {
        const responseText = await response.text();
        const unavailableReason =
          response.status === 403
            ? "forbidden"
            : response.status === 404
              ? "not_found"
              : "request_failed";

        log.warn("Signal report artefacts unavailable", {
          teamId,
          reportId,
          status: response.status,
          statusText: response.statusText,
          body: responseText || undefined,
        });

        return { results: [], count: 0, unavailableReason };
      }

      const data = (await response.json()) as unknown;
      const parsed = parseSignalReportArtefactsPayload(data);

      if (parsed.unavailableReason) {
        log.warn("Signal report artefacts payload did not match schema", {
          teamId,
          reportId,
        });
      }

      return parsed;
    } catch (error) {
      log.warn("Failed to fetch signal report artefacts", {
        teamId,
        reportId,
        error,
      });
      return {
        results: [],
        count: 0,
        unavailableReason: "request_failed",
      };
    }
  }

  async getCommitDiff(
    reportId: string,
    artefactId: string,
  ): Promise<CommitDiffResponse> {
    const teamId = await this.getTeamId();
    const path = `/api/projects/${teamId}/signals/reports/${reportId}/artefacts/${artefactId}/diff/`;
    const url = new URL(`${this.api.baseUrl}${path}`);

    // The shared fetcher throws `Failed request: [<status>] <json-body>` for any non-2xx, so
    // unwrap that into the endpoint's clean `error` message rather than surfacing the raw string.
    let response: Response;
    try {
      response = await this.api.fetcher.fetch({ method: "get", url, path });
    } catch (error) {
      throw new Error(
        extractRequestErrorMessage(error, "Couldn\u2019t load the diff."),
      );
    }

    const data = (await response.json()) as Partial<CommitDiffResponse>;
    return {
      diff: typeof data.diff === "string" ? data.diff : "",
      truncated: data.truncated === true,
    };
  }

  async updateSignalReportState(
    reportId: string,
    input:
      | {
          state: "potential";
          snooze_for?: number;
          reset_weight?: boolean;
          error?: string;
          /** Feedback recorded when a reason drove the snooze (e.g. "Already fixed"); omitted for a plain snooze. */
          dismissal_reason?: DismissalReasonOptionValue;
          dismissal_note?: string;
        }
      | {
          state: "suppressed";
          /** When omitted, the server suppresses without creating a dismissal artefact. */
          dismissal_reason?: DismissalReasonOptionValue;
          dismissal_note?: string;
          reset_weight?: boolean;
          error?: string;
        }
      | {
          state: "resolved";
          dismissal_reason: ResolveReasonOptionValue;
          dismissal_note?: string;
        },
  ): Promise<SignalReport> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/projects/${teamId}/signals/reports/${reportId}/state/`,
    );
    const path = `/api/projects/${teamId}/signals/reports/${reportId}/state/`;

    let response: Response;
    try {
      response = await this.api.fetcher.fetch({
        method: "post",
        url,
        path,
        overrides: {
          body: JSON.stringify(input),
        },
      });
    } catch (error) {
      if (input.state === "suppressed" && requestErrorStatus(error) === 409) {
        const currentReport = await this.getSignalReport(reportId).catch(
          () => null,
        );
        const requestedReason = input.dismissal_reason ?? null;
        const requestedNote = input.dismissal_note?.trim() ?? "";
        const feedbackMatches =
          currentReport?.dismissal_reason === requestedReason &&
          (currentReport?.dismissal_note?.trim() ?? "") === requestedNote;
        if (
          currentReport?.status === "suppressed" &&
          ((!requestedReason && !requestedNote) || feedbackMatches)
        ) {
          return currentReport;
        }
      }
      throw error;
    }

    if (!response.ok) {
      const errorText = await response.text();
      throw new Error(errorText || "Failed to update signal report state");
    }

    return (await response.json()) as SignalReport;
  }

  /**
   * Refund a report's billed PR. The server freezes the billing path, archives
   * the report, and kicks off the billing credit when one is due; it also
   * enforces eligibility, so callers only gate for display.
   */
  async refundSignalReport(
    reportId: string,
    input: { reason: SignalReportRefundReason; note?: string },
  ): Promise<SignalReport> {
    const teamId = await this.getTeamId();
    const path = `/api/projects/${teamId}/signals/reports/${reportId}/refund/`;
    const url = new URL(`${this.api.baseUrl}${path}`);

    // The shared fetcher throws `Failed request: [<status>] <json-body>` for any non-2xx, so
    // unwrap that into the endpoint's clean `error` message (e.g. the eligibility failures)
    // rather than surfacing the raw string.
    let response: Response;
    try {
      response = await this.api.fetcher.fetch({
        method: "post",
        url,
        path,
        overrides: {
          body: JSON.stringify(input),
        },
      });
    } catch (error) {
      throw new Error(
        extractRequestErrorMessage(error, "Failed to refund this report's PR"),
      );
    }

    return (await response.json()) as SignalReport;
  }

  /**
   * Edit a report's suggested reviewers. The server appends a new `suggested_reviewers` status
   * artefact (latest-wins), canonicalizes each entry to a lowercase `github_login`, and carries
   * `relevant_commits` / `github_name` forward from the current reviewers for surviving logins.
   * Returns the newly-appended artefact (a fresh id), not the one addressed by `artefactId`.
   */
  async updateSignalReportArtefact(
    reportId: string,
    artefactId: string,
    content: SuggestedReviewerWriteEntry[],
    edit: SuggestedReviewerEdit,
  ): Promise<SuggestedReviewersArtefact> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/projects/${teamId}/signals/reports/${reportId}/artefacts/${artefactId}/`,
    );
    const path = `/api/projects/${teamId}/signals/reports/${reportId}/artefacts/${artefactId}/`;

    const response = await this.api.fetcher.fetch({
      method: "put",
      url,
      path,
      overrides: {
        body: JSON.stringify({ content, ...edit }),
      },
    });

    if (!response.ok) {
      const errorText = await response.text();
      throw new Error(errorText || "Failed to update suggested reviewers");
    }

    const parsed = normalizeSignalReportArtefact(await response.json());
    if (!parsed || parsed.type !== "suggested_reviewers") {
      throw new Error("Unexpected response updating suggested reviewers");
    }
    return parsed as SuggestedReviewersArtefact;
  }

  async setSignalReportReviewers(
    reportId: string,
    content: SuggestedReviewerWriteEntry[],
    edit: SuggestedReviewerEdit,
  ): Promise<SuggestedReviewersArtefact> {
    const teamId = await this.getTeamId();
    const path = `/api/projects/${teamId}/signals/reports/${reportId}/reviewers/`;
    const url = new URL(`${this.api.baseUrl}${path}`);
    const response = await this.api.fetcher.fetch({
      method: "put",
      url,
      path,
      overrides: {
        body: JSON.stringify({ content, ...edit }),
      },
    });

    if (!response.ok) {
      const errorText = await response.text();
      throw new Error(errorText || "Failed to update suggested reviewers");
    }

    const parsed = normalizeSignalReportArtefact(await response.json());
    if (!parsed || parsed.type !== "suggested_reviewers") {
      throw new Error("Unexpected response updating suggested reviewers");
    }
    return parsed as SuggestedReviewersArtefact;
  }

  async deleteSignalReport(reportId: string): Promise<{
    status: "deletion_started" | "already_running";
    report_id: string;
  }> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/projects/${teamId}/signals/reports/${reportId}/`,
    );
    const path = `/api/projects/${teamId}/signals/reports/${reportId}/`;

    const response = await this.api.fetcher.fetch({
      method: "delete",
      url,
      path,
    });

    if (!response.ok) {
      const errorText = await response.text();
      throw new Error(errorText || "Failed to delete signal report");
    }

    return (await response.json()) as {
      status: "deletion_started" | "already_running";
      report_id: string;
    };
  }

  async reingestSignalReport(reportId: string): Promise<{
    status: "reingestion_started" | "already_running";
    report_id: string;
  }> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/projects/${teamId}/signals/reports/${reportId}/reingest/`,
    );
    const path = `/api/projects/${teamId}/signals/reports/${reportId}/reingest/`;

    const response = await this.api.fetcher.fetch({
      method: "post",
      url,
      path,
    });

    if (!response.ok) {
      const errorText = await response.text();
      throw new Error(errorText || "Failed to reingest signal report");
    }

    return (await response.json()) as {
      status: "reingestion_started" | "already_running";
      report_id: string;
    };
  }

  async getSignalTeamConfig(): Promise<SignalTeamConfig> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/projects/${teamId}/signals/config/`,
    );
    const path = `/api/projects/${teamId}/signals/config/`;

    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path,
    });

    if (!response.ok) {
      throw new Error(
        `Failed to fetch signal team config: ${response.statusText}`,
      );
    }

    return (await response.json()) as SignalTeamConfig;
  }

  async updateSignalTeamConfig(
    updates: Partial<{
      default_autostart_priority: string;
      default_slack_notification_channel: string | null;
      autostart_base_branches: Record<string, string>;
      max_reports_per_day: number | null;
    }>,
  ): Promise<SignalTeamConfig> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/projects/${teamId}/signals/config/`,
    );
    const path = `/api/projects/${teamId}/signals/config/`;

    const response = await this.api.fetcher.fetch({
      method: "post",
      url,
      path,
      overrides: {
        body: JSON.stringify(updates),
      },
    });

    if (!response.ok) {
      throw new Error(
        `Failed to update signal team config: ${response.statusText}`,
      );
    }

    return (await response.json()) as SignalTeamConfig;
  }

  async getSignalUserAutonomyConfig(): Promise<SignalUserAutonomyConfig | null> {
    const url = new URL(`${this.api.baseUrl}/api/users/@me/signal_autonomy/`);
    const path = "/api/users/@me/signal_autonomy/";

    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path,
    });

    return (await response.json()) as SignalUserAutonomyConfig;
  }

  async updateSignalUserAutonomyConfig(
    updates: Partial<{
      autostart_priority: string | null;
      slack_notification_integration_id: number | null;
      slack_notification_channel: string | null;
      slack_notification_min_priority: string | null;
    }>,
  ): Promise<SignalUserAutonomyConfig> {
    const url = new URL(`${this.api.baseUrl}/api/users/@me/signal_autonomy/`);
    const path = "/api/users/@me/signal_autonomy/";

    const response = await this.api.fetcher.fetch({
      method: "post",
      url,
      path,
      overrides: {
        body: JSON.stringify(updates),
      },
    });

    if (!response.ok) {
      throw new Error(
        `Failed to update signal user autonomy config: ${response.statusText}`,
      );
    }
    return (await response.json()) as SignalUserAutonomyConfig;
  }

  async getSlackChannelsForIntegration(
    integrationId: number,
    params?: SlackChannelsQueryParams,
  ): Promise<SlackChannelsResponse> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/environments/${teamId}/integrations/${integrationId}/channels/`,
    );
    const search = params?.search?.trim();
    if (search) {
      url.searchParams.set("search", search);
    }
    if (params?.limit != null) {
      url.searchParams.set("limit", String(params.limit));
    }
    if (params?.offset != null) {
      url.searchParams.set("offset", String(params.offset));
    }
    if (params?.channelId) {
      url.searchParams.set("channel_id", params.channelId);
    }
    const path = `/api/environments/${teamId}/integrations/${integrationId}/channels/${url.search}`;

    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path,
    });

    if (!response.ok) {
      throw new Error(`Failed to fetch Slack channels: ${response.statusText}`);
    }
    return (await response.json()) as SlackChannelsResponse;
  }

  async deleteSignalUserAutonomyConfig(): Promise<void> {
    const url = new URL(`${this.api.baseUrl}/api/users/@me/signal_autonomy/`);
    const path = "/api/users/@me/signal_autonomy/";

    const response = await this.api.fetcher.fetch({
      method: "delete",
      url,
      path,
    });

    if (!response.ok) {
      throw new Error(
        `Failed to delete signal user autonomy config: ${response.statusText}`,
      );
    }
  }

  async getMcpServers(): Promise<McpRecommendedServer[]> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/environments/${teamId}/mcp_servers/`,
    );
    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path: `/api/environments/${teamId}/mcp_servers/`,
    });

    if (!response.ok) {
      throw new Error(`Failed to fetch MCP servers: ${response.statusText}`);
    }

    const data = (await response.json()) as {
      results?: McpRecommendedServer[];
    };
    return data.results ?? [];
  }

  /**
   * Object URL for an MCP server's brand icon, proxied from logo.dev by the
   * authenticated `mcp_servers/icon/` endpoint. Returns null when no brand
   * icon exists for the domain (the endpoint 404s so callers render their own
   * fallback glyph, e.g. on self-hosted instances without a logo.dev token).
   */
  async getMcpServerIconUrl(
    domain: string,
    theme?: "light" | "dark",
  ): Promise<string | null> {
    const teamId = await this.getTeamId();
    const path = `/api/environments/${teamId}/mcp_servers/icon/`;
    const url = new URL(`${this.api.baseUrl}${path}`);
    url.searchParams.set("domain", domain);
    if (theme) {
      url.searchParams.set("theme", theme);
    }
    let response: Response;
    try {
      response = await this.api.fetcher.fetch({
        method: "get",
        url,
        path,
      });
    } catch (error) {
      // 404 is the endpoint's definitive "no icon for this domain" answer,
      // not a failure; anything else propagates so callers can retry.
      if (requestErrorStatus(error) === 404) return null;
      throw error;
    }
    const blob = await response.blob();
    return URL.createObjectURL(blob);
  }

  async getMcpServerInstallations(): Promise<McpServerInstallation[]> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/environments/${teamId}/mcp_server_installations/`,
    );
    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path: `/api/environments/${teamId}/mcp_server_installations/`,
    });

    if (!response.ok) {
      throw new Error(
        `Failed to fetch MCP server installations: ${response.statusText}`,
      );
    }

    const data = (await response.json()) as {
      results?: McpServerInstallation[];
    };
    return data.results ?? [];
  }

  async installCustomMcpServer(
    options: {
      name: string;
      url: string;
      auth_type: McpAuthType;
      api_key?: string;
      description?: string;
      client_id?: string;
      client_secret?: string;
      install_source?: "posthog" | "posthog-code";
      posthog_code_callback_url?: string;
    } & McpGatewayInstallSharingOptions,
  ): Promise<McpServerInstallation | Schemas.OAuthRedirectResponse> {
    const teamId = await this.getTeamId();
    const apiUrl = new URL(
      `${this.api.baseUrl}/api/environments/${teamId}/mcp_server_installations/install_custom/`,
    );
    const response = await this.api.fetcher.fetch({
      method: "post",
      url: apiUrl,
      path: `/api/environments/${teamId}/mcp_server_installations/install_custom/`,
      overrides: {
        body: JSON.stringify(options),
      },
    });

    if (!response.ok) {
      const errorData = await response.json().catch(() => ({}));
      throw new Error(
        (errorData as { detail?: string }).detail ??
          `Failed to install MCP server: ${response.statusText}`,
      );
    }

    return (await response.json()) as
      | McpServerInstallation
      | Schemas.OAuthRedirectResponse;
  }

  async updateMcpServerInstallation(
    installationId: string,
    updates: {
      display_name?: string;
      description?: string;
      is_enabled?: boolean;
    },
  ): Promise<McpServerInstallation> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/environments/${teamId}/mcp_server_installations/${installationId}/`,
    );
    const response = await this.api.fetcher.fetch({
      method: "patch",
      url,
      path: `/api/environments/${teamId}/mcp_server_installations/${installationId}/`,
      overrides: {
        body: JSON.stringify(updates),
      },
    });

    if (!response.ok) {
      const errorData = await response.json().catch(() => ({}));
      throw new Error(
        (errorData as { detail?: string }).detail ??
          `Failed to update MCP server: ${response.statusText}`,
      );
    }

    return (await response.json()) as McpServerInstallation;
  }

  async uninstallMcpServer(installationId: string): Promise<void> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/environments/${teamId}/mcp_server_installations/${installationId}/`,
    );
    const response = await this.api.fetcher.fetch({
      method: "delete",
      url,
      path: `/api/environments/${teamId}/mcp_server_installations/${installationId}/`,
    });

    if (!response.ok && response.status !== 204) {
      throw new Error(`Failed to uninstall MCP server: ${response.statusText}`);
    }
  }

  async installMcpTemplate(
    options: {
      template_id: string;
      api_key?: string;
      install_source?: "posthog" | "posthog-code";
      posthog_code_callback_url?: string;
    } & McpGatewayInstallSharingOptions,
  ): Promise<McpServerInstallation | Schemas.OAuthRedirectResponse> {
    const teamId = await this.getTeamId();
    const path = `/api/environments/${teamId}/mcp_server_installations/install_template/`;
    const response = await this.api.fetcher.fetch({
      method: "post",
      url: new URL(`${this.api.baseUrl}${path}`),
      path,
      overrides: { body: JSON.stringify(options) },
    });

    if (!response.ok) {
      const errorData = await response.json().catch(() => ({}));
      throw new Error(
        (errorData as { detail?: string }).detail ??
          `Failed to install MCP template: ${response.statusText}`,
      );
    }

    return (await response.json()) as
      | McpServerInstallation
      | Schemas.OAuthRedirectResponse;
  }

  async authorizeMcpInstallation(options: {
    installation_id: string;
    install_source?: "posthog" | "posthog-code";
    posthog_code_callback_url?: string;
  }): Promise<Schemas.OAuthRedirectResponse> {
    const teamId = await this.getTeamId();
    const path = `/api/environments/${teamId}/mcp_server_installations/authorize/`;
    const url = new URL(`${this.api.baseUrl}${path}`);
    url.searchParams.set("installation_id", options.installation_id);
    if (options.install_source) {
      url.searchParams.set("install_source", options.install_source);
    }
    if (options.posthog_code_callback_url) {
      url.searchParams.set(
        "posthog_code_callback_url",
        options.posthog_code_callback_url,
      );
    }
    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path,
    });

    if (!response.ok) {
      const errorData = await response.json().catch(() => ({}));
      throw new Error(
        (errorData as { detail?: string }).detail ??
          `Failed to authorize MCP installation: ${response.statusText}`,
      );
    }

    return (await response.json()) as Schemas.OAuthRedirectResponse;
  }

  async getMcpInstallationTools(
    installationId: string,
    options: { includeRemoved?: boolean } = {},
  ): Promise<McpInstallationTool[]> {
    const teamId = await this.getTeamId();
    const path = `/api/environments/${teamId}/mcp_server_installations/${installationId}/tools/`;
    const url = new URL(`${this.api.baseUrl}${path}`);
    if (options.includeRemoved) {
      url.searchParams.set("include_removed", "1");
    }
    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path,
    });

    if (!response.ok) {
      throw new Error(
        `Failed to fetch MCP installation tools: ${response.statusText}`,
      );
    }

    const data = (await response.json()) as {
      results?: McpInstallationTool[];
    };
    return data.results ?? [];
  }

  async updateMcpToolApproval(
    installationId: string,
    toolName: string,
    approval_state: McpApprovalState,
  ): Promise<McpInstallationTool> {
    const teamId = await this.getTeamId();
    const path = `/api/environments/${teamId}/mcp_server_installations/${installationId}/tools/${encodeURIComponent(toolName)}/`;
    const response = await this.api.fetcher.fetch({
      method: "patch",
      url: new URL(`${this.api.baseUrl}${path}`),
      path,
      overrides: { body: JSON.stringify({ approval_state }) },
    });

    if (!response.ok) {
      const errorData = await response.json().catch(() => ({}));
      throw new Error(
        (errorData as { detail?: string }).detail ??
          `Failed to update tool approval: ${response.statusText}`,
      );
    }

    return (await response.json()) as McpInstallationTool;
  }

  async refreshMcpInstallationTools(
    installationId: string,
  ): Promise<McpInstallationTool[]> {
    const teamId = await this.getTeamId();
    const path = `/api/environments/${teamId}/mcp_server_installations/${installationId}/tools/refresh/`;
    const response = await this.api.fetcher.fetch({
      method: "post",
      url: new URL(`${this.api.baseUrl}${path}`),
      path,
    });

    if (!response.ok) {
      const errorData = await response.json().catch(() => ({}));
      throw new Error(
        (errorData as { detail?: string }).detail ??
          `Failed to refresh MCP tools: ${response.statusText}`,
      );
    }

    const data = (await response.json()) as {
      results?: McpInstallationTool[];
    };
    return data.results ?? [];
  }

  // ---- MCP gateway (team control plane, behind the `mcp-gateway` flag) ----

  /**
   * JSON request against the team-scoped MCP gateway API. `path` is relative
   * to `/api/projects/{teamId}/` and must keep its trailing slash.
   */
  private async mcpGatewayFetch<T>(args: {
    method: "get" | "post" | "patch" | "delete";
    path: string;
    search?: Record<string, string | number | undefined>;
    body?: unknown;
    errorLabel: string;
  }): Promise<T> {
    const teamId = await this.getTeamId();
    const path = `/api/projects/${teamId}/${args.path}`;
    const url = new URL(`${this.api.baseUrl}${path}`);
    for (const [key, value] of Object.entries(args.search ?? {})) {
      if (value !== undefined) url.searchParams.set(key, String(value));
    }
    const response = await this.api.fetcher.fetch({
      method: args.method,
      url,
      path,
      ...(args.body !== undefined
        ? { overrides: { body: JSON.stringify(args.body) } }
        : {}),
    });
    if (!response.ok && response.status !== 204) {
      const errorData = await response.json().catch(() => ({}));
      throw new Error(
        (errorData as { detail?: string }).detail ??
          `${args.errorLabel}: ${response.statusText}`,
      );
    }
    if (response.status === 204) return undefined as T;
    return (await response.json().catch(() => undefined)) as T;
  }

  async getMcpGatewayConfig(): Promise<TeamMcpGatewayConfig> {
    return this.mcpGatewayFetch({
      method: "get",
      path: "mcp_gateway/config/",
      errorLabel: "Failed to fetch gateway settings",
    });
  }

  async updateMcpGatewaySettings(
    update: TeamMcpGatewayConfigUpdate,
  ): Promise<TeamMcpGatewayConfig> {
    return this.mcpGatewayFetch({
      method: "post",
      path: "mcp_gateway/config/update_settings/",
      body: update,
      errorLabel: "Failed to update gateway settings",
    });
  }

  /**
   * Admin: set the team posture for untouched catalog servers and bulk-apply
   * the same state to every existing gateway row.
   */
  async setAllMcpGatewayServersEnabled(
    enabled: boolean,
  ): Promise<TeamMcpGatewayConfig> {
    return this.mcpGatewayFetch({
      method: "post",
      path: "mcp_gateway/config/set_all_servers_enabled/",
      body: { enabled },
      errorLabel: "Failed to update servers",
    });
  }

  async getMcpGatewayServers(): Promise<McpGatewayServer[]> {
    const data = await this.mcpGatewayFetch<{ results?: McpGatewayServer[] }>({
      method: "get",
      path: "mcp_gateway/servers/",
      search: { limit: 500 },
      errorLabel: "Failed to fetch gateway servers",
    });
    return data.results ?? [];
  }

  async getMcpGatewayServer(serverId: string): Promise<McpGatewayServer> {
    return this.mcpGatewayFetch({
      method: "get",
      path: `mcp_gateway/servers/${serverId}/`,
      errorLabel: "Failed to fetch gateway server",
    });
  }

  async updateMcpGatewayServer(
    serverId: string,
    updates: McpGatewayServerUpdate,
  ): Promise<McpGatewayServer> {
    return this.mcpGatewayFetch({
      method: "patch",
      path: `mcp_gateway/servers/${serverId}/`,
      body: updates,
      errorLabel: "Failed to update gateway server",
    });
  }

  /**
   * Admin: enable or disable a catalog template the team never touched,
   * materializing a gateway row for it (or updating the existing one).
   */
  async setMcpGatewayTemplateEnabled(options: {
    templateId: string;
    enabled: boolean;
  }): Promise<McpGatewayServer> {
    return this.mcpGatewayFetch({
      method: "post",
      path: "mcp_gateway/servers/set_template_enabled/",
      body: { template_id: options.templateId, enabled: options.enabled },
      errorLabel: "Failed to update catalog server",
    });
  }

  /**
   * Disconnect every member and delete the row. The registry is sparse, so a
   * deleted catalog server simply follows the team default again.
   */
  async deleteMcpGatewayServer(serverId: string): Promise<void> {
    await this.mcpGatewayFetch<void>({
      method: "delete",
      path: `mcp_gateway/servers/${serverId}/`,
      errorLabel: "Failed to remove gateway server",
    });
  }

  /** Tool catalog with the effective policy resolved for one scope. */
  async getMcpGatewayToolPolicies(
    serverId: string,
    scope: McpGatewayPolicyScope = {},
  ): Promise<McpResolvedToolPolicy[]> {
    const data = await this.mcpGatewayFetch<{
      results?: McpResolvedToolPolicy[];
    }>({
      method: "get",
      path: `mcp_gateway/servers/${serverId}/tools/`,
      search: {
        scope_type: scope.scope_type,
        scope_user_id: scope.scope_user_id,
        scope_service_account_id: scope.scope_service_account_id,
      },
      errorLabel: "Failed to fetch tool policies",
    });
    return data.results ?? [];
  }

  /** Upsert per-tool states for a scope; returns the re-resolved catalog. */
  async upsertMcpGatewayToolPolicies(
    serverId: string,
    options: McpGatewayPolicyScope & { policies: McpToolPolicyEntry[] },
  ): Promise<McpResolvedToolPolicy[]> {
    const data = await this.mcpGatewayFetch<{
      results?: McpResolvedToolPolicy[];
    }>({
      method: "post",
      path: `mcp_gateway/servers/${serverId}/policies/`,
      body: options,
      errorLabel: "Failed to update tool policies",
    });
    return data.results ?? [];
  }

  async getMcpServiceAccounts(): Promise<McpServiceAccount[]> {
    const data = await this.mcpGatewayFetch<{ results?: McpServiceAccount[] }>({
      method: "get",
      path: "mcp_gateway/service_accounts/",
      search: { limit: 500 },
      errorLabel: "Failed to fetch service accounts",
    });
    return data.results ?? [];
  }

  async getMcpServiceAccount(accountId: string): Promise<McpServiceAccount> {
    return this.mcpGatewayFetch({
      method: "get",
      path: `mcp_gateway/service_accounts/${accountId}/`,
      errorLabel: "Failed to fetch service account",
    });
  }

  /** Returns the full bearer token exactly once. */
  async createMcpServiceAccount(options: {
    name: string;
    description?: string;
  }): Promise<McpServiceAccountWithToken> {
    return this.mcpGatewayFetch({
      method: "post",
      path: "mcp_gateway/service_accounts/",
      body: options,
      errorLabel: "Failed to create service account",
    });
  }

  async updateMcpServiceAccount(
    accountId: string,
    updates: {
      name?: string;
      description?: string;
      status?: McpServiceAccountStatus;
    },
  ): Promise<McpServiceAccount> {
    return this.mcpGatewayFetch({
      method: "patch",
      path: `mcp_gateway/service_accounts/${accountId}/`,
      body: updates,
      errorLabel: "Failed to update service account",
    });
  }

  async deleteMcpServiceAccount(accountId: string): Promise<void> {
    await this.mcpGatewayFetch<void>({
      method: "delete",
      path: `mcp_gateway/service_accounts/${accountId}/`,
      errorLabel: "Failed to delete service account",
    });
  }

  /** Grant or revoke one agent's access to one gateway server. */
  async setMcpServiceAccountAccess(
    accountId: string,
    options: {
      gateway_server_id: string;
      enabled: boolean;
      /**
       * Reach of the caller's own share. The server defaults an omitted
       * scope to "personal", so re-enabling without it resets a team share.
       */
      scope?: McpAgentGrantScope;
      /** Agent-scope tool policies to set alongside the grant. */
      policies?: McpToolPolicyEntry[];
    },
  ): Promise<McpServiceAccount> {
    return this.mcpGatewayFetch({
      method: "post",
      path: `mcp_gateway/service_accounts/${accountId}/access/`,
      body: options,
      errorLabel: "Failed to update agent access",
    });
  }

  async getMcpGatewayMembers(): Promise<McpGatewayMemberSummary[]> {
    const data = await this.mcpGatewayFetch<{
      results?: McpGatewayMemberSummary[];
    }>({
      method: "get",
      path: "mcp_gateway/members/",
      search: { limit: 500 },
      errorLabel: "Failed to fetch gateway members",
    });
    return data.results ?? [];
  }

  /** Turn one gateway server off (or back on) for one member. */
  async setMcpGatewayMemberAccess(
    userId: number,
    options: { gateway_server_id: string; enabled: boolean },
  ): Promise<void> {
    await this.mcpGatewayFetch<void>({
      method: "post",
      path: `mcp_gateway/members/${userId}/set_access/`,
      body: options,
      errorLabel: "Failed to update member access",
    });
  }

  async getMcpGatewayAuditEvents(
    options: {
      quickFilter?: McpAuditQuickFilter;
      actorServiceAccountId?: string;
      limit?: number;
      offset?: number;
    } = {},
  ): Promise<McpAuditPage> {
    const data = await this.mcpGatewayFetch<{
      count?: number;
      results?: McpAuditEvent[];
    }>({
      method: "get",
      path: "mcp_gateway/audit/",
      search: {
        quick_filter: options.quickFilter,
        actor_service_account_id: options.actorServiceAccountId,
        limit: options.limit,
        offset: options.offset,
      },
      errorLabel: "Failed to fetch audit log",
    });
    return { count: data.count ?? 0, results: data.results ?? [] };
  }

  async getMcpGatewayAuditCounts(): Promise<McpAuditCounts> {
    return this.mcpGatewayFetch({
      method: "get",
      path: "mcp_gateway/audit/counts/",
      errorLabel: "Failed to fetch audit counts",
    });
  }

  private parseFetcherError(error: unknown): {
    status: number;
    body: Record<string, unknown>;
  } | null {
    if (!(error instanceof Error)) return null;
    const match = error.message.match(/\[(\d+)\]\s*(.*)/);
    if (!match) return null;
    try {
      return {
        status: Number.parseInt(match[1], 10),
        body: JSON.parse(match[2]) as Record<string, unknown>,
      };
    } catch {
      return { status: Number.parseInt(match[1], 10), body: {} };
    }
  }

  /**
   * Run a cloud-run request, re-throwing a backend 429 usage-limit error as a
   * typed CloudUsageLimitError so the UI can show the upgrade prompt.
   */
  private async withCloudUsageLimitCheck<T>(fn: () => Promise<T>): Promise<T> {
    try {
      return await fn();
    } catch (error) {
      this.throwIfCloudUsageLimit(error);
      throw error;
    }
  }

  private throwIfCloudUsageLimit(error: unknown): void {
    const parsed = this.parseFetcherError(error);
    if (
      parsed &&
      parsed.status === 429 &&
      (parsed.body.code === "usage_limit_exceeded" ||
        parsed.body.code === DESKTOP_BILLING_LIMIT_ERROR_CODE)
    ) {
      const limitType = parsed.body.limit_type;
      throw new CloudUsageLimitError({
        limitType:
          limitType === "burst" || limitType === "sustained" ? limitType : null,
        resetAt:
          typeof parsed.body.reset_at === "string"
            ? parsed.body.reset_at
            : null,
      });
    }
  }

  /**
   * Check if a feature flag is enabled for the current project.
   * Returns true if the flag exists and is active, false otherwise.
   */
  async isFeatureFlagEnabled(flagKey: string): Promise<boolean> {
    try {
      const teamId = await this.getTeamId();
      const url = new URL(
        `${this.api.baseUrl}/api/projects/${teamId}/feature_flags/`,
      );
      url.searchParams.set("key", flagKey);

      const response = await this.api.fetcher.fetch({
        method: "get",
        url,
        path: `/api/projects/${teamId}/feature_flags/`,
      });

      if (!response.ok) {
        log.warn(`Failed to fetch feature flags: ${response.statusText}`);
        return false;
      }

      const data = (await response.json()) as {
        results?: { key: string; active: boolean }[];
      };
      const flags = data.results ?? [];
      const flag = flags.find(
        (f: { key: string; active: boolean }) => f.key === flagKey,
      );

      return flag?.active ?? false;
    } catch (error) {
      log.warn(`Error checking feature flag "${flagKey}":`, error);
      return false;
    }
  }

  // Sandbox Environments

  async listSandboxEnvironments(): Promise<SandboxEnvironment[]> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/projects/${teamId}/sandbox_environments/`,
    );
    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path: `/api/projects/${teamId}/sandbox_environments/`,
    });
    if (!response.ok) {
      throw new Error(
        `Failed to fetch sandbox environments: ${response.statusText}`,
      );
    }
    const data = (await response.json()) as {
      results?: SandboxEnvironment[];
    };
    return data.results ?? [];
  }

  async createSandboxEnvironment(
    input: SandboxEnvironmentInput,
  ): Promise<SandboxEnvironment> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/projects/${teamId}/sandbox_environments/`,
    );
    try {
      const response = await this.api.fetcher.fetch({
        method: "post",
        url,
        path: `/api/projects/${teamId}/sandbox_environments/`,
        overrides: {
          body: JSON.stringify(input),
        },
      });
      return (await response.json()) as SandboxEnvironment;
    } catch (error) {
      if (!(error instanceof ApiRequestError)) throw error;
      throw new Error(
        `Failed to create sandbox environment: ${readFieldErrors(error)}`,
      );
    }
  }

  async updateSandboxEnvironment(
    id: string,
    input: Partial<SandboxEnvironmentInput>,
  ): Promise<SandboxEnvironment> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/projects/${teamId}/sandbox_environments/${id}/`,
    );
    try {
      const response = await this.api.fetcher.fetch({
        method: "patch",
        url,
        path: `/api/projects/${teamId}/sandbox_environments/${id}/`,
        overrides: {
          body: JSON.stringify(input),
        },
      });
      return (await response.json()) as SandboxEnvironment;
    } catch (error) {
      if (!(error instanceof ApiRequestError)) throw error;
      throw new Error(
        `Failed to update sandbox environment: ${readFieldErrors(error)}`,
      );
    }
  }

  async deleteSandboxEnvironment(id: string): Promise<void> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/projects/${teamId}/sandbox_environments/${id}/`,
    );
    const response = await this.api.fetcher.fetch({
      method: "delete",
      url,
      path: `/api/projects/${teamId}/sandbox_environments/${id}/`,
    });
    if (!response.ok) {
      throw new Error(
        `Failed to delete sandbox environment: ${response.statusText}`,
      );
    }
  }

  async listSandboxCustomImages(): Promise<SandboxCustomImage[]> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/projects/${teamId}/sandbox_custom_images/`,
    );
    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path: `/api/projects/${teamId}/sandbox_custom_images/`,
    });
    if (!response.ok) {
      if (response.status === 403) {
        const errorData = (await response.json().catch(() => ({}))) as {
          detail?: string;
        };
        throw new SandboxCustomImagesDisabledError(errorData.detail);
      }
      throw new Error(
        `Failed to fetch sandbox custom images: ${response.statusText}`,
      );
    }
    const data = (await response.json()) as {
      results?: SandboxCustomImage[];
    };
    return data.results ?? [];
  }

  async createSandboxCustomImage(input: {
    name: string;
    description?: string;
    repository?: string | null;
    private?: boolean;
  }): Promise<SandboxCustomImage> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/projects/${teamId}/sandbox_custom_images/`,
    );
    const response = await this.api.fetcher.fetch({
      method: "post",
      url,
      path: `/api/projects/${teamId}/sandbox_custom_images/`,
      overrides: {
        body: JSON.stringify(input),
      },
    });
    if (!response.ok) {
      const errorData = (await response.json().catch(() => ({}))) as {
        detail?: string;
      };
      throw new Error(
        errorData.detail ??
          `Failed to create sandbox custom image: ${response.statusText}`,
      );
    }
    return (await response.json()) as SandboxCustomImage;
  }

  async getSandboxCustomImage(id: string): Promise<SandboxCustomImage> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/projects/${teamId}/sandbox_custom_images/${id}/`,
    );
    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path: `/api/projects/${teamId}/sandbox_custom_images/${id}/`,
    });
    if (!response.ok) {
      throw new Error(
        `Failed to fetch sandbox custom image: ${response.statusText}`,
      );
    }
    return (await response.json()) as SandboxCustomImage;
  }

  async updateSandboxCustomImage(
    id: string,
    input: { name?: string; description?: string },
  ): Promise<SandboxCustomImage> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/projects/${teamId}/sandbox_custom_images/${id}/`,
    );
    const response = await this.api.fetcher.fetch({
      method: "patch",
      url,
      path: `/api/projects/${teamId}/sandbox_custom_images/${id}/`,
      overrides: {
        body: JSON.stringify(input),
      },
    });
    if (!response.ok) {
      const errorData = (await response.json().catch(() => ({}))) as {
        detail?: string;
      };
      throw new Error(
        errorData.detail ??
          `Failed to update sandbox custom image: ${response.statusText}`,
      );
    }
    return (await response.json()) as SandboxCustomImage;
  }

  async ensureSandboxCustomImageBuilderTask(
    id: string,
  ): Promise<SandboxCustomImage> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/projects/${teamId}/sandbox_custom_images/${id}/builder_task/`,
    );
    const response = await this.api.fetcher.fetch({
      method: "post",
      url,
      path: `/api/projects/${teamId}/sandbox_custom_images/${id}/builder_task/`,
      overrides: {
        body: JSON.stringify({}),
      },
    });
    if (!response.ok) {
      const errorData = (await response.json().catch(() => ({}))) as {
        detail?: string;
      };
      throw new Error(
        errorData.detail ??
          `Failed to open image builder session: ${response.statusText}`,
      );
    }
    return (await response.json()) as SandboxCustomImage;
  }

  async buildSandboxCustomImage(
    id: string,
    specYaml?: string | null,
  ): Promise<SandboxCustomImage> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/projects/${teamId}/sandbox_custom_images/${id}/build/`,
    );
    const response = await this.api.fetcher.fetch({
      method: "post",
      url,
      path: `/api/projects/${teamId}/sandbox_custom_images/${id}/build/`,
      overrides: {
        body: JSON.stringify(
          specYaml === undefined ? {} : { spec_yaml: specYaml },
        ),
      },
    });
    if (!response.ok) {
      const errorData = (await response.json().catch(() => ({}))) as {
        detail?: string;
      };
      throw new Error(
        errorData.detail ??
          `Failed to build sandbox custom image: ${response.statusText}`,
      );
    }
    return (await response.json()) as SandboxCustomImage;
  }

  async deleteSandboxCustomImage(id: string): Promise<void> {
    const teamId = await this.getTeamId();
    const url = new URL(
      `${this.api.baseUrl}/api/projects/${teamId}/sandbox_custom_images/${id}/`,
    );
    const response = await this.api.fetcher.fetch({
      method: "delete",
      url,
      path: `/api/projects/${teamId}/sandbox_custom_images/${id}/`,
    });
    if (!response.ok) {
      throw new Error(
        `Failed to delete sandbox custom image: ${response.statusText}`,
      );
    }
  }

  /**
   * Read the clip window and the session-to-clip time map off an export row.
   * The render drops the idle stretches of a session, so a caller cannot treat
   * a session offset as a clip time.
   */
  private parseRecordingExport(row: RecordingExportRow): RecordingExport {
    const context = row.export_context ?? {};
    const startOffsetSeconds = context.start_offset_s ?? context.timestamp ?? 0;
    const endOffsetSeconds =
      context.end_offset_s ??
      (context.duration != null ? startOffsetSeconds + context.duration : null);

    const segments: RecordingClipSegment[] = [];
    for (const period of context.inactivity_periods ?? []) {
      if (period.ts_from_s == null || period.recording_ts_from_s == null) {
        continue;
      }
      segments.push({
        sessionFromSeconds: period.ts_from_s,
        sessionToSeconds: period.ts_to_s ?? null,
        clipFromSeconds: period.recording_ts_from_s,
        clipToSeconds: period.recording_ts_to_s ?? period.recording_ts_from_s,
        active: period.active !== false,
      });
    }
    segments.sort((a, b) => a.sessionFromSeconds - b.sessionFromSeconds);

    return {
      id: row.id,
      startOffsetSeconds,
      endOffsetSeconds,
      clipDurationSeconds: context.video_duration_s ?? null,
      truncated: context.truncated === true,
      segments,
    };
  }

  /** Get one exported recording clip, with the window of the session it covers. */
  async getRecordingExport(
    projectId: number,
    exportId: number,
  ): Promise<RecordingExport | null> {
    const urlPath = `/api/projects/${projectId}/exports/${exportId}/`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path: urlPath,
    });
    if (!response.ok) return null;
    const row = (await response.json()) as RecordingExportRow;
    if (row.has_content === false) return null;
    return this.parseRecordingExport(row);
  }

  /** Find the rendered clip for a session recording, with the window it covers. */
  async findRecordingExport(
    projectId: number,
    sessionRecordingId: string,
  ): Promise<RecordingExport | null> {
    const urlPath = `/api/projects/${projectId}/exports/`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    url.searchParams.set("session_recording_id", sessionRecordingId);
    url.searchParams.set("export_format", "video/mp4");
    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path: urlPath,
    });
    if (!response.ok) return null;
    const data = (await response.json()) as {
      results?: RecordingExportRow[];
    };
    const match = data.results?.find((e) => e.has_content);
    return match ? this.parseRecordingExport(match) : null;
  }

  /** Get the presigned content URL for an exported asset (e.g. rasterized recording). */
  async getExportContentUrl(
    projectId: number,
    exportId: number,
  ): Promise<string | null> {
    const urlPath = `/api/projects/${projectId}/exports/${exportId}/content/`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path: urlPath,
    });
    if (!response.ok) return null;
    const blob = await response.blob();
    return URL.createObjectURL(blob);
  }

  /**
   * Fetch the requesting user's personal LLM spend analysis. `dateFrom` / `dateTo`
   * accept absolute dates (`2026-04-23`) or relative strings (`-7d`, `-1m`), and
   * default to the last 30 days. When `product` is set the tool / model / trace
   * breakdowns are scoped to that `ai_product` (e.g. `posthog_code`); when omitted
   * they aggregate across every product.
   */
  async getPersonalSpendAnalysis(
    options: { dateFrom?: string; dateTo?: string; product?: string } = {},
  ): Promise<SpendAnalysisResponse> {
    const { dateFrom = "-30d", dateTo, product } = options;
    const urlPath = `/api/llm_analytics/@me/spend/`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    url.searchParams.set("date_from", dateFrom);
    if (dateTo) {
      url.searchParams.set("date_to", dateTo);
    }
    if (product) {
      url.searchParams.set("product", product);
    }
    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path: urlPath,
    });
    if (!response.ok) {
      throw new Error(`Failed to fetch spend analysis: ${response.status}`);
    }
    return (await response.json()) as SpendAnalysisResponse;
  }

  /**
   * The signed-in person's own spend limit, as the gateway holds it. A
   * deployment without the gateway wired answers `available: false` rather than
   * failing, so the settings page can say the limit informs only.
   */
  async getUserSpendLimit(): Promise<UserSpendLimit> {
    return parseUserSpendLimit(await this.spendLimitRequest("get"));
  }

  /** Sets the limit; `windowSeconds` is the window it resets over. */
  async setUserSpendLimit(
    limitUsd: number,
    windowSeconds: number,
  ): Promise<UserSpendLimit> {
    return parseUserSpendLimit(
      await this.spendLimitRequest("post", "", {
        limit_usd: String(limitUsd),
        window_seconds: windowSeconds,
      }),
    );
  }

  /** Removes the limit, so nothing holds this person's spend. */
  async clearUserSpendLimit(): Promise<UserSpendLimit> {
    return parseUserSpendLimit(
      await this.spendLimitRequest("delete", "clear/"),
    );
  }

  private async spendLimitRequest(
    method: "get" | "post" | "delete",
    suffix = "",
    body?: Record<string, unknown>,
  ): Promise<unknown> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/projects/${teamId}/ai_gateway/@me/spend_limit/${suffix}`;
    // The shared fetcher throws `Failed request: [<status>] <json-body>` for any
    // non-2xx, so unwrap that into the endpoint's clean message rather than
    // surfacing the raw string in the settings toast.
    try {
      const response = await this.api.fetcher.fetch({
        method,
        url: new URL(`${this.api.baseUrl}${urlPath}`),
        path: urlPath,
        ...(body ? { overrides: { body: JSON.stringify(body) } } : {}),
      });
      return await response.json();
    } catch (error) {
      throw new Error(
        extractRequestErrorMessage(error, "Couldn't update your spend limit."),
      );
    }
  }

  /**
   * Lists the team's LLM skills (latest versions, no bodies).
   * Returns null when the feature is unavailable for this org (the
   * llm-analytics-skills flag gates the endpoint server-side with a 403).
   * `category` narrows to one exact server-owned category (e.g. "scout"
   * for Signals scouts); omit it to list every category.
   */
  async listLlmSkills(
    options: { category?: string } = {},
  ): Promise<LlmSkillListItem[] | null> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/environments/${teamId}/llm_skills/`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    if (options.category !== undefined) {
      url.searchParams.set("category", options.category);
    }
    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path: urlPath,
    });
    if (response.status === 403) return null;
    if (!response.ok) {
      throw new Error(`Failed to fetch team skills: ${response.statusText}`);
    }
    const data = (await response.json()) as { results?: LlmSkillListItem[] };
    return data.results ?? [];
  }

  /**
   * Fetches the latest version of a team skill, including body and file manifest.
   * The endpoint caps an unpaged body at its own page length, so follow
   * `body_next_offset` to the end and return the whole body to every caller.
   */
  async getLlmSkillByName(name: string): Promise<LlmSkill> {
    const first = await this.getLlmSkillBodyPage(name);
    const pages = [first.body];
    let offset = first.body_next_offset;
    while (offset != null) {
      // Pin the version: a publish between pages would otherwise splice two bodies.
      const page = await this.getLlmSkillBodyPage(name, {
        offset,
        version: first.version,
      });
      pages.push(page.body);
      // An offset that does not advance would page forever; the length check below
      // then reports the short body.
      const next = page.body_next_offset;
      offset = next != null && next > offset ? next : null;
    }

    const body = pages.join("");
    const total = first.body_total_length;
    if (total != null && body.length !== total) {
      throw new Error(
        `Failed to fetch team skill: got ${body.length} of ${total} characters of the body of "${name}"`,
      );
    }
    return { ...first, body, body_next_offset: null };
  }

  private async getLlmSkillBodyPage(
    name: string,
    paging?: { offset: number; version: number },
  ): Promise<LlmSkill> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/environments/${teamId}/llm_skills/name/${encodeURIComponent(name)}`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    if (paging) {
      url.searchParams.set("body_offset", String(paging.offset));
      url.searchParams.set("version", String(paging.version));
    }
    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path: urlPath,
    });
    if (!response.ok) {
      throw new Error(`Failed to fetch team skill: ${response.statusText}`);
    }
    return (await response.json()) as LlmSkill;
  }

  /** Creates a brand-new team skill (version 1). */
  async createLlmSkill(input: {
    name: string;
    description: string;
    body: string;
    files?: LlmSkillFileInput[];
    metadata?: Record<string, unknown>;
  }): Promise<LlmSkill> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/environments/${teamId}/llm_skills/`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    const response = await this.api.fetcher.fetch({
      method: "post",
      url,
      path: urlPath,
      overrides: { body: JSON.stringify(input) },
    });
    if (!response.ok) {
      const errorData = (await response.json().catch(() => ({}))) as {
        detail?: string;
      };
      throw new Error(
        errorData.detail ??
          `Failed to create team skill: ${response.statusText}`,
      );
    }
    return (await response.json()) as LlmSkill;
  }

  /**
   * Publishes a new version of an existing team skill. `base_version` must
   * match the current latest version (409 otherwise).
   */
  async publishLlmSkillVersion(
    name: string,
    input: {
      body: string;
      description?: string;
      files?: LlmSkillFileInput[];
      metadata?: Record<string, unknown>;
      base_version: number;
    },
  ): Promise<LlmSkill> {
    const teamId = await this.getTeamId();
    const urlPath = `/api/environments/${teamId}/llm_skills/name/${encodeURIComponent(name)}`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    const response = await this.api.fetcher.fetch({
      method: "patch",
      url,
      path: urlPath,
      overrides: { body: JSON.stringify(input) },
    });
    if (!response.ok) {
      const errorData = (await response.json().catch(() => ({}))) as {
        detail?: string;
      };
      throw new Error(
        errorData.detail ??
          `Failed to publish team skill: ${response.statusText}`,
      );
    }
    return (await response.json()) as LlmSkill;
  }

  /** Fetches one companion file of a team skill. */
  async getLlmSkillFile(name: string, filePath: string): Promise<LlmSkillFile> {
    const teamId = await this.getTeamId();
    const encodedPath = filePath.split("/").map(encodeURIComponent).join("/");
    const urlPath = `/api/environments/${teamId}/llm_skills/name/${encodeURIComponent(name)}/files/${encodedPath}`;
    const url = new URL(`${this.api.baseUrl}${urlPath}`);
    const response = await this.api.fetcher.fetch({
      method: "get",
      url,
      path: urlPath,
    });
    if (!response.ok) {
      throw new Error(
        `Failed to fetch team skill file: ${response.statusText}`,
      );
    }
    return (await response.json()) as LlmSkillFile;
  }

  /**
   * Runs a read-only HogQL query against the team's project and returns the raw
   * result grid. Backs the agent observability rollups (`$ai_*` events the
   * runner captures into this team's own project). The endpoint can answer 200
   * with an `error` field; that's surfaced as a throw.
   */
  async runHogQLQuery(query: string): Promise<HogQLGrid> {
    const teamId = await this.getTeamId();
    const path = `/api/projects/${teamId}/query/`;
    const url = new URL(`${this.api.baseUrl}${path}`);
    const response = await this.api.fetcher.fetch({
      method: "post",
      url,
      path,
      overrides: {
        body: JSON.stringify({ query: { kind: "HogQLQuery", query } }),
      },
    });
    const data = (await response.json()) as {
      results?: unknown[][];
      columns?: string[];
      error?: string | null;
    };
    if (data.error) {
      throw new Error(data.error);
    }
    return { results: data.results ?? [], columns: data.columns ?? [] };
  }

  async runQuery(
    query: Record<string, unknown>,
    options?: { refresh?: "blocking" | false },
  ): Promise<Record<string, unknown>> {
    const teamId = await this.getTeamId();
    const path = `/api/projects/${teamId}/query/`;
    const url = new URL(`${this.api.baseUrl}${path}`);
    const refresh = options?.refresh === false ? null : "blocking";
    const response = await this.api.fetcher.fetch({
      method: "post",
      url,
      path,
      overrides: {
        body: JSON.stringify({ query, ...(refresh ? { refresh } : {}) }),
      },
    });
    const data = (await response.json()) as Record<string, unknown>;
    if (typeof data.error === "string" && data.error) {
      throw new Error(data.error);
    }
    return data;
  }

  /**
   * The insight's identity and query node, by short id. Backs saved-insight
   * chart cards in agent messages: the caller plans and runs the query.
   */
  async getInsightDefinition(shortId: string): Promise<{
    name: string | null;
    description: string | null;
    query: unknown;
    response: Record<string, unknown> | null;
  } | null> {
    const projectId = (await this.getTeamId()).toString();
    try {
      const insight = await this.api.get(
        "/api/projects/{project_id}/insights/{id}/",
        {
          path: { project_id: projectId, id: shortId },
          query: { refresh: "blocking" },
        },
      );
      return {
        name: insight.name || insight.derived_name || null,
        description: insight.description || null,
        query: insight.query ?? null,
        response:
          insight.result === null || insight.result === undefined
            ? null
            : {
                results: insight.result,
                columns: insight.columns ?? [],
              },
      };
    } catch (error) {
      if (requestErrorStatus(error) === 404) return null;
      throw error;
    }
  }

  /**
   * The insight's name and description by short id. Reads the cache only, so
   * a reference card never runs the insight's query.
   */
  async getInsightSummary(shortId: string): Promise<{
    name: string | null;
    description: string | null;
  } | null> {
    const projectId = (await this.getTeamId()).toString();
    try {
      const urlPath = `/api/projects/${projectId}/insights/${encodeURIComponent(shortId)}/`;
      const url = new URL(`${this.api.baseUrl}${urlPath}`);
      url.searchParams.set("basic", "true");
      url.searchParams.set("refresh", "force_cache");
      const response = await this.api.fetcher.fetch({
        method: "get",
        url,
        path: urlPath,
      });
      const insight = (await response.json()) as Pick<
        Schemas.Insight,
        "name" | "derived_name" | "description"
      >;
      return {
        name: insight.name || insight.derived_name || null,
        description: insight.description || null,
      };
    } catch (error) {
      if (requestErrorStatus(error) === 404) return null;
      throw error;
    }
  }

  /**
   * Resolves an `evidence:<kind>/<id>` citation from an agent message to a
   * small live summary of the object it points at. Returns null for kinds
   * without a lookup and for ids that don't resolve, so the caller can fall
   * back to a static reference. Query-backed kinds (hogql, insight) resolve
   * in the UI instead, where chart shaping lives.
   */
  /** Names of the cohorts a cohort's criteria reference, so the criteria read as prose. */
  private async resolveCohortNames(
    projectId: string,
    filters: unknown,
  ): Promise<Map<string, string>> {
    const ids = referencedCohortIds(filters).slice(0, MAX_RESOLVED_COHORTS);
    const entries = await Promise.all(
      ids.map((id) =>
        this.api
          .get("/api/projects/{project_id}/cohorts/{id}/", {
            path: { project_id: projectId, id: Number(id) },
          })
          .then((cohort) => [id, cohort.name ?? id] as const)
          .catch(() => null),
      ),
    );
    return new Map(entries.filter((entry) => entry !== null));
  }

  /**
   * People behind the distinct ids a flag targets, keyed by distinct id. A
   * lookup that fails leaves its id unresolved so the raw id still renders.
   */

  private async resolveFlagPeople(
    projectId: string,
    flag: Schemas.FeatureFlag,
  ): Promise<Map<string, ResolvedPerson>> {
    const ids = targetedDistinctIds(flag).slice(0, MAX_RESOLVED_FLAG_PEOPLE);
    if (ids.length === 0) return new Map();
    try {
      // One batched call instead of one request per id: the persons list
      // endpoint hydrates an actors query per call and shares a per-user
      // throttle with every other person preview.
      const response = await this.api.post(
        "/api/projects/{project_id}/persons/batch_by_distinct_ids/",
        {
          path: { project_id: projectId },
          query: {},
          // The spec mislabels the body as a full person record; the endpoint
          // reads a distinct_ids array.
          body: { distinct_ids: ids } as unknown as Schemas.PersonRecord,
        },
      );
      const results =
        response && typeof response === "object" && "results" in response
          ? (response as { results: Record<string, unknown> }).results
          : {};
      const people = new Map<string, ResolvedPerson>();
      for (const distinctId of ids) {
        const person = results[distinctId];
        if (!isRecord(person)) continue;
        const uuid = typeof person.uuid === "string" ? person.uuid : null;
        if (!uuid) continue;
        const properties = isPropertyRecord(person.properties)
          ? person.properties
          : {};
        const email =
          typeof properties.email === "string" ? properties.email : null;
        const name = typeof person.name === "string" ? person.name : null;
        people.set(distinctId, {
          uuid,
          name: name || email || distinctId,
          email,
        });
      }
      return people;
    } catch {
      return new Map();
    }
  }

  async getEvidencePreview(
    kind: string,
    id: string,
  ): Promise<EvidencePreview | null> {
    const projectId = (await this.getTeamId()).toString();
    const numericId = /^\d+$/.test(id) ? Number(id) : null;

    switch (kind) {
      case "flag": {
        let flag: Schemas.FeatureFlag | undefined;
        if (numericId !== null) {
          flag = await this.api.get(
            "/api/projects/{project_id}/feature_flags/{id}/",
            { path: { project_id: projectId, id: numericId } },
          );
        } else {
          // Agents often cite flags by key; the API only retrieves by
          // numeric id, so find the exact key through the list search.
          const page = await this.api.get(
            "/api/projects/{project_id}/feature_flags/",
            { path: { project_id: projectId }, query: { search: id } },
          );
          flag = page.results.find((entry) => entry.key === id);
        }
        if (!flag) return null;
        // Depth: PostHog's own staleness verdict, whether anything still
        // evaluates the flag (7-day call volume), and the people behind any
        // distinct ids the flag targets directly, so the page can name them.
        const [status, volume, people] = await Promise.all([
          this.api
            .get("/api/projects/{project_id}/feature_flags/{id}/status/", {
              path: { project_id: projectId, id: flag.id },
            })
            .catch(() => null),
          this.runQuery({
            kind: "HogQLQuery",
            query: `SELECT toDate(timestamp) AS day, count() FROM events WHERE event = '$feature_flag_called' AND properties.$feature_flag = '${hogqlEscape(flag.key)}' AND timestamp >= now() - INTERVAL 7 DAY GROUP BY day ORDER BY day`,
          }).catch(() => ({})),
          this.resolveFlagPeople(projectId, flag),
        ]);
        return decorateFlagPreview(
          shapeFlagPreview(flag, people),
          status,
          gridRows(volume),
        );
      }
      case "experiment": {
        if (numericId === null) return null;
        const experiment = await this.api.get(
          "/api/projects/{project_id}/experiments/{id}/",
          { path: { project_id: projectId, id: numericId } },
        );
        const preview = shapeExperimentPreview(experiment);
        const primaryQueries = experimentMetricQueries(experiment, "primary");
        const secondaryQueries = experimentMetricQueries(
          experiment,
          "secondary",
        );
        if (!experiment.start_date) {
          return {
            ...preview,
            experimentResults: shapeExperimentResults(experiment, null, [], []),
          };
        }

        const runMetricQuery = async (
          metric: unknown,
        ): Promise<ExperimentMetricQueryResult> => {
          if (!metric || typeof metric !== "object") {
            return { response: null };
          }
          try {
            const response = await this.runQuery(
              {
                kind: "ExperimentQuery",
                metric,
                experiment_id: numericId,
              },
              { refresh: false },
            );
            return {
              response: response as Schemas.ExperimentQueryResponse,
            };
          } catch {
            return { response: null };
          }
        };

        const exposureQuery = experiment.feature_flag
          ? this.runQuery(
              {
                kind: "ExperimentExposureQuery",
                experiment_id: numericId,
                experiment_name: experiment.name,
                exposure_criteria: experiment.exposure_criteria,
                feature_flag: experiment.feature_flag,
                start_date: experiment.start_date,
                end_date: experiment.end_date,
                holdout: experiment.holdout,
              },
              { refresh: false },
            ).catch(() => null)
          : Promise.resolve(null);
        const [exposureResponse, primaryResults, secondaryResults] =
          await Promise.all([
            exposureQuery,
            Promise.all(primaryQueries.map(runMetricQuery)),
            Promise.all(secondaryQueries.map(runMetricQuery)),
          ]);

        const experimentExposureResponse =
          exposureResponse as Schemas.ExperimentExposureQueryResponse | null;
        return {
          ...preview,
          experimentResults: shapeExperimentResults(
            experiment,
            experimentExposureResponse,
            primaryResults,
            secondaryResults,
          ),
          chart: shapeExperimentExposureChart(experimentExposureResponse),
        };
      }
      case "error": {
        // The issue's identity plus its 30-day activity: total events, users
        // affected, and a daily-occurrence spark answering "still firing?".
        const scope = `event = '$exception' AND properties.$exception_issue_id = '${hogqlEscape(id)}' AND timestamp >= now() - INTERVAL 30 DAY`;
        const [issue, totals, daily] = await Promise.all([
          this.api.get(
            "/api/projects/{project_id}/error_tracking/issues/{id}/",
            { path: { project_id: projectId, id }, query: {} },
          ),
          this.runQuery({
            kind: "HogQLQuery",
            query: `SELECT count(), uniq(person_id) FROM events WHERE ${scope}`,
          }).catch(() => ({})),
          this.runQuery({
            kind: "HogQLQuery",
            query: `SELECT toDate(timestamp) AS day, count() FROM events WHERE ${scope} GROUP BY day ORDER BY day`,
          }).catch(() => ({})),
        ]);
        if (!("id" in issue))
          throw new Error("This issue moved. Open it in PostHog.");
        const preview = shapeErrorIssuePreview(issue);
        const totalRow = gridRows(totals)[0];
        const facts = [...(preview.facts ?? [])];
        const users = totalRow ? Number(totalRow[1]) : 0;
        const events = totalRow ? Number(totalRow[0]) : 0;
        if (Number.isFinite(users) && users > 0) {
          facts.unshift(
            `${compactCount(users)} users · ${compactCount(events)} events (30d)`,
          );
        }
        const stats = [
          ...(preview.stats ?? []),
          ...(users > 0
            ? [
                { label: "Users in 30 days", value: compactCount(users) },
                { label: "Events in 30 days", value: compactCount(events) },
              ]
            : []),
        ];
        const dailyRows = gridRows(daily);
        const points = dailySparkPoints(dailyRows);
        return {
          ...preview,
          facts,
          stats,
          spark:
            points.length > 1
              ? {
                  points,
                  labels: dailySparkLabels(dailyRows),
                  render: "bar" as const,
                }
              : undefined,
        };
      }
      case "event": {
        // Verify the event against its definition (also yields the id that
        // makes the reference clickable), then chart its 14-day volume.
        const definition = await this.api
          .get("/api/projects/{project_id}/event_definitions/by_name/", {
            path: { project_id: projectId },
            query: { name: id },
          })
          .catch(() => null);
        if (!definition) return null;
        const volume = await this.runQuery({
          kind: "HogQLQuery",
          query: `SELECT toDate(timestamp) AS day, count() FROM events WHERE event = '${hogqlEscape(id)}' AND timestamp >= now() - INTERVAL 14 DAY GROUP BY day ORDER BY day`,
        }).catch(() => ({}));
        const preview = shapeEventDefinitionPreview(definition);
        const volumeRows = gridRows(volume);
        const points = dailySparkPoints(volumeRows);
        const total = points.reduce((sum, value) => sum + value, 0);
        return {
          ...preview,
          facts:
            total > 0 ? [`${compactCount(total)} events (14d)`] : undefined,
          stats: [
            ...(total > 0
              ? [{ label: "Events in 14 days", value: compactCount(total) }]
              : []),
            ...(preview.stats ?? []),
          ],
          spark:
            points.length > 1
              ? {
                  points,
                  labels: dailySparkLabels(volumeRows),
                  render: "line" as const,
                }
              : undefined,
        };
      }
      case "ticket": {
        const ticket = await this.api.get(
          "/api/projects/{project_id}/conversations/tickets/{id}/",
          { path: { project_id: projectId, id } },
        );
        return shapeTicketPreview(ticket);
      }
      case "report": {
        const report = await this.getSignalReport(id);
        return report ? shapeInboxReportPreview(report) : null;
      }
      case "person": {
        if (/^[0-9a-f]{8}-[0-9a-f-]{27,}$/i.test(id)) {
          // A UUID-shaped id can be a person uuid or a UUID-shaped distinct id
          // (posthog-js writes anonymous distinct ids as UUIDs). Retrieve-by-id
          // matches only the person uuid, so a 404 (no such uuid) or 400 (the id
          // isn't a valid person uuid) means fall through and resolve it as a
          // distinct id below rather than giving up.
          const person = await this.api
            .get("/api/projects/{project_id}/persons/{id}/", {
              path: { project_id: projectId, id },
              query: {},
            })
            .catch((error) => {
              const status = requestErrorStatus(error);
              if (status === 404 || status === 400) return null;
              throw error;
            });
          if (person) return shapePersonPreview(person);
        }
        const page = await this.api.get("/api/projects/{project_id}/persons/", {
          path: { project_id: projectId },
          query: { search: id },
        });
        const person = page.results?.find(
          (candidate) =>
            candidate.uuid === id || candidate.distinct_ids?.includes(id),
        );
        return person ? shapePersonPreview(person) : null;
      }
      case "replay": {
        const recording = await this.api.get(
          "/api/projects/{project_id}/session_recordings/{id}/",
          { path: { project_id: projectId, id } },
        );
        return shapeRecordingPreview(recording);
      }
      case "survey": {
        const [survey, stats] = await Promise.all([
          this.api.get("/api/projects/{project_id}/surveys/{id}/", {
            path: { project_id: projectId, id },
          }),
          this.api
            .get("/api/projects/{project_id}/surveys/{id}/stats/", {
              path: { project_id: projectId, id },
              query: {},
            })
            .catch(() => null),
        ]);
        return decorateSurveyPreview(
          shapeSurveyPreview(survey),
          stats as Record<string, unknown> | null,
        );
      }
      case "trace": {
        const rollup = await this.runQuery({
          kind: "HogQLQuery",
          query: `SELECT count(), round(sum(toFloat(properties.$ai_total_cost_usd)), 3), round(sum(toFloat(properties.$ai_latency)), 1), groupUniqArray(properties.$ai_model), countIf(toString(properties.$ai_is_error) IN ('true', '1')) FROM events WHERE event IN ('$ai_generation', '$ai_embedding') AND properties.$ai_trace_id = '${hogqlEscape(id)}'`,
        });
        const row = gridRows(rollup)[0];
        return row ? shapeTracePreview(row) : null;
      }
      case "dashboard": {
        if (numericId === null) return null;
        const dashboard = await this.api.get(
          "/api/projects/{project_id}/dashboards/{id}/",
          { path: { project_id: projectId, id: numericId }, query: {} },
        );
        return shapeDashboardPreview(dashboard);
      }
      case "cohort": {
        if (numericId === null) return null;
        const cohort = await this.api.get(
          "/api/projects/{project_id}/cohorts/{id}/",
          { path: { project_id: projectId, id: numericId } },
        );
        return shapeCohortPreview(
          cohort,
          await this.resolveCohortNames(projectId, cohort.filters),
        );
      }
      case "action": {
        if (numericId === null) return null;
        const [action, volume, totals] = await Promise.all([
          this.api.get("/api/projects/{project_id}/actions/{id}/", {
            path: { project_id: projectId, id: numericId },
            query: {},
          }),
          this.runQuery({
            kind: "HogQLQuery",
            query: `SELECT toDate(timestamp) AS day, count() FROM events WHERE matchesAction(${numericId}) AND timestamp >= now() - INTERVAL 14 DAY GROUP BY day ORDER BY day`,
          }).catch(() => ({})),
          this.runQuery({
            kind: "HogQLQuery",
            query: `SELECT count(), uniq(person_id), max(timestamp) FROM events WHERE matchesAction(${numericId}) AND timestamp >= now() - INTERVAL 30 DAY`,
          }).catch(() => ({})),
        ]);
        const preview = shapeActionPreview(action);
        const volumeRows = gridRows(volume);
        const points = dailySparkPoints(volumeRows);
        const total = points.reduce((sum, value) => sum + value, 0);
        const facts = [...(preview.facts ?? [])];
        if (total > 0) facts.unshift(`${compactCount(total)} matches (14d)`);
        const totalsRow = gridRows(totals)[0];
        const matches30d = totalsRow ? Number(totalsRow[0]) : 0;
        const users30d = totalsRow ? Number(totalsRow[1]) : 0;
        const lastSeen =
          totalsRow && typeof totalsRow[2] === "string" && matches30d > 0
            ? totalsRow[2]
            : null;
        if (users30d > 0) facts.push(`${compactCount(users30d)} users (30d)`);
        return {
          ...preview,
          facts,
          stats: [
            ...(total > 0
              ? [{ label: "Matches in 14 days", value: compactCount(total) }]
              : []),
            ...(users30d > 0
              ? [{ label: "Users in 30 days", value: compactCount(users30d) }]
              : []),
            ...(lastSeen
              ? [{ label: "Last seen", value: formatDay(lastSeen) }]
              : []),
          ],
          spark:
            points.length > 1
              ? {
                  points,
                  labels: dailySparkLabels(volumeRows),
                  render: "line" as const,
                }
              : undefined,
          sections: [
            ...activitySection([
              [
                "Matches in 30 days",
                matches30d > 0 ? compactCount(matches30d) : null,
              ],
              [
                "Unique users in 30 days",
                users30d > 0 ? compactCount(users30d) : null,
              ],
              ["Last seen", lastSeen ? formatDay(lastSeen) : null],
            ]),
            ...(preview.sections ?? []),
          ],
        };
      }
      case "eval": {
        const evaluation = await this.api.get(
          "/api/projects/{project_id}/evaluations/{id}/",
          { path: { project_id: projectId, id } },
        );
        return shapeEvaluationPreview(evaluation);
      }
      default:
        return null;
    }
  }
}