Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

124 KB
Raw Blame
/**
 * API endpoint wrappers: one function per API.
 * DTO types come from @adelie/server/api (**type import only**, resolved via
 * tsconfig paths to the server contract file types.ts; must not be a value import — server
 * code must not enter the browser bundle).
 */
import type {
  AdminPasswordResetRequest,
  AdminUserCreateRequest,
  AdminUserCreateResponse,
  AdminUsersResponse,
  AgentApiKeyCreateRequest,
  AgentApiKeyCreateResponse,
  AgentApiResponse,
  AgentApiUpdateRequest,
  AgentConfigResponse,
  AgentConfigUpdateRequest,
  AgentCreateRequest,
  AgentCreateResponse,
  AgentDeleteResponse,
  AgentDeletionResponse,
  AgentHooksResponse,
  AgentImportRequest,
  AgentImportResponse,
  AgentKernelUpdateResponse,
  AgentPluginsInstallResponse,
  AgentSchedulesConfigDto,
  AgentSkillsConfigDto,
  AgentSkillsResponse,
  AgentsResponse,
  AgentVaultConfigDto,
  AllProjectSchedulesResponse,
  ApprovalDecisionRequest,
  AsrConfigResponse,
  AsrConfigUpdateRequest,
  AsrTestRequest,
  AsrTestResponse,
  AsrTranscribeRequest,
  AsrTranscribeResponse,
  AuthLoginRequest,
  AuthResponse,
  BenchmarkCasesResponse,
  BenchmarkCreateRequest,
  BenchmarkCreateResponse,
  BenchmarksResponse,
  CaseMaterial,
  ChatDefaultsDto,
  CommandPolicyDto,
  CommandPolicyRuleDto,
  DefaultModelResponse,
  DefaultModelUpdateRequest,
  DesktopPrivacyPane,
  DesktopUpdateStatusResponse,
  DirAccessResponse,
  DirCreateResponse,
  DirDeleteResponse,
  DirectorySkillsResponse,
  DirListResponse,
  EndpointModelListRequest,
  EndpointModelListResponse,
  FeedbackConfigResponse,
  FeedbackRequest,
  FeedbackResponse,
  FeishuBindingPutRequest,
  FeishuBindingResponse,
  FeishuTestRequest,
  FeishuTestResponse,
  FilesCreateRequest,
  FilesMoveRequest,
  FilesStatRequest,
  FilesStatResponse,
  FilesWriteRequest,
  GoalResponse,
  ImportedThemesResponse,
  ThemeDownloadRequest,
  ThemeImportResponse,
  ThemeRegistryImportRequest,
  ThemeRegistryResponse,
  ThemeUploadRequest,
  InstallResponse,
  MachinesResponse,
  McpServerTestResponse,
  MemberAddRequest,
  MemberAddResponse,
  MembersResponse,
  MemoryFileResponse,
  MemoryFilesResponse,
  MemoryImportRequest,
  MemoryImportResponse,
  MemoryOverviewResponse,
  MemoryScopeExport,
  MeResponse,
  MessagesResponse,
  MessagingBindingsResponse,
  MessagingChannel,
  MessagingTestMessageResponse,
  ModelBalanceResponse,
  ModelOAuthCodeResponse,
  ModelOAuthStartRequest,
  ModelOAuthStartResponse,
  ModelOAuthStatusResponse,
  PlatformAuthFlowStatusResponse,
  PlatformAuthStartResponse,
  PlatformModelSyncResponse,
  ModelProtocolDetectRequest,
  ModelProtocolDetectResponse,
  MachinesUseResponse,
  SshHostRequest,
  SshHostResponse,
  ModelsResponse,
  ModelsUpdateRequest,
  ModelTestRequest,
  ModelTestResponse,
  ModelUserKeyAssignRequest,
  ModelUserKeyAssignResponse,
  ModelVisionDetectRequest,
  ModelVisionDetectResponse,
  OrganizationCreateRequest,
  OrganizationDetail,
  OrganizationPatchRequest,
  OrganizationSettings,
  OrganizationsResponse,
  OrgCalendarResponse,
  OrgCalendarUpsertRequest,
  OrgCalendarWriteResponse,
  OrgChannelCreateRequest,
  OrgChannelDetail,
  OrgChannelItem,
  OrgChannelMemberRequest,
  OrgChannelMessage,
  OrgChannelMessageSendRequest,
  OrgChannelMessagesResponse,
  OrgChannelPatchRequest,
  OrgChannelReadRequest,
  OrgChannelsResponse,
  OrgChartResponse,
  OrgDeskResponse,
  OrgEmployeeItem,
  OrgEmployeePatchRequest,
  OrgFinanceResponse,
  OrgHandbookFileResponse,
  OrgHandbookFilesResponse,
  OrgHandbookResponse,
  OrgHireRequest,
  OrgSessionsResponse,
  OrgTicketAttachRequest,
  OrgTicketBlockRequest,
  OrgTicketCreateRequest,
  OrgTicketDetail,
  OrgTicketMoveRequest,
  OrgTicketProgressRequest,
  OrgTicketsResponse,
  OrgTicketStartRequest,
  OrgTicketStartResponse,
  OrgTicketUpdateRequest,
  PasswordChangeRequest,
  PluginDirectoryResponse,
  PluginDownloadRequest,
  PluginFilesResponse,
  PluginImportResponse,
  PluginInstallRequest,
  PluginLibraryResponse,
  PluginUploadRequest,
  PrefsResponse,
  ProjectCreateRequest,
  ProjectCreateResponse,
  ProjectSchedulesResponse,
  ProjectsResponse,
  ProjectUpdateRequest,
  ProjectUpdateResponse,
  QQBindingPutRequest,
  QQBindingResponse,
  QQScanPollResponse,
  QQScanStartResponse,
  QQTestRequest,
  QQTestResponse,
  RecalledMessageResponse,
  RestartResponse,
  RetryNowResponse,
  ScheduleItem,
  SchedulesResponse,
  ScheduleUpsertRequest,
  SemanticIdSuggestRequest,
  SemanticIdSuggestResponse,
  ProxyProbeProvider,
  ProxyProbeResponse,
  ProxyProbeTargetsResponse,
  ServerSettingsResponse,
  ServerSettingsUpdateRequest,
  SessionCategory,
  SessionContextResponse,
  SessionCreateRequest,
  SessionCreateResponse,
  SessionForkRequest,
  SessionForkResponse,
  SessionPatchRequest,
  SessionProcessesResponse,
  SessionResponse,
  PluginIndexResponse,
  PluginConfigResponse,
  PluginConfigActionResponse,
  PluginConfigUpdateRequest,
  PluginReadmeResponse,
  SessionsResponse,
  SessionSwitchModelRequest,
  SessionBatchPageRequest,
  SessionsBatchRequest,
  SessionsBatchResponse,
  SessionTracesResponse,
  SkillArchiveInstallRequest,
  SteerRequest,
  StorageApplyRequest,
  StorageApplyResponse,
  StoragePinRequest,
  StoragePlanResponse,
  StoragePlansResponse,
  StoragePurgeResponse,
  StorageReportResponse,
  StorageRestoreResponse,
  StorageSettingsResponse,
  StorageSettingsUpdateRequest,
  StorageTrashResponse,
  SubagentMessageResponse,
  TaskCreateRequest,
  TaskCreateResponse,
  TelegramBindingPutRequest,
  TelegramBindingResponse,
  TelegramTestRequest,
  TelegramTestResponse,
  TraceAnalysisResponse,
  TraceEventsResponse,
  TraceImportRequest,
  TraceImportResponse,
  UiPrefs,
  UpdateCheckResponse,
  UpdateJobStatus,
  UpdateProfileRequest,
  UpdateProfileResponse,
  DesktopLoginItemPatch,
  DesktopLoginItemStatusResponse,
  DesktopPetPatch,
  DesktopPetStatusResponse,
  DesktopTrayPatch,
  DesktopTrayStatusResponse,
  HookArchiveInstallRequest,
  UsageErrorIgnoreAdded,
  UsageErrorIgnoreWrite,
  UsageErrorIgnores,
  UsageErrorKind,
  UsageErrorsClearResponse,
  UsageErrorsPage,
  UsageGranularity,
  UsageGroupBy,
  UsageModelTotals,
  UsageResponse,
  UsageSessionDays,
  RunningSessionsResponse,
  VaultResponse,
  VaultUpdateRequest,
  UserVaultAssignRequest,
  UserVaultImportRequest,
  InstalledPluginsResponse,
  VersionHistoryDiffResponse,
  VersionHistoryResponse,
  WorkflowInfo,
  WorkflowVersion,
  VersionRollbackResponse,
  VersionResponse,
  WeChatBindingPutRequest,
  WeChatBindingResponse,
  WeChatScanPollResponse,
  WeChatScanStartResponse,
  WeChatTestResponse,
  WorkspaceFilesResponse,
  WorkspaceSearchResponse,
  ContributionsResponse,
  BuiltinBrowserHistoryResponse,
  BuiltinBrowserImportRequest,
  BuiltinBrowserImportResult,
  BuiltinBrowserImportSourcesResponse,
  BuiltinBrowserSettings,
  BuiltinBrowserStatus,
  BuiltinBrowserTab,
  DesktopBrowserCommand,
} from "@adelie/server/api";
import type { MCPServerConfig } from "@adelie/core/interfaces";
import type { RunRequest } from "@adelie/amsp";
import { apiFetch, apiFetchStream, apiFetchWithMeta } from "./client";
import { machineForSession, rememberSessionMachine } from "../lib/session-machines";
import { apiUrl } from "../lib/server-context";
import { activityCursorParam } from "../lib/session-grouping";
import type { ActivityKey } from "../lib/session-grouping";

// Auth & user -----------------------------------------------------------------

export const login = (body: AuthLoginRequest) =>
  apiFetch<AuthResponse>("/api/auth/login", { method: "POST", body });

export const logout = () => apiFetch<void>("/api/auth/logout", { method: "POST", body: {} });

/**
 * The data root's install identity (public — no session needed, which is the point: the web
 * app asks before it knows whether anyone is signed in). See lib/install-scope.ts.
 */
export const getInstall = () => apiFetch<InstallResponse>("/api/install");

export const getMe = () => apiFetch<MeResponse>("/api/me");

export const changePassword = (body: PasswordChangeRequest) =>
  apiFetch<void>("/api/me/password", { method: "PUT", body });

/**
 * Nickname and avatar, as a patch: an absent field keeps what is stored, `null` clears it.
 * The response carries the updated user, which the caller feeds straight back into the auth
 * state so the sidebar's avatar and name change without a second round trip.
 */
export const updateProfile = (body: UpdateProfileRequest) =>
  apiFetch<UpdateProfileResponse>("/api/me/profile", { method: "PUT", body });

export const getPrefs = () => apiFetch<PrefsResponse>("/api/me/prefs");

export const putPrefs = (prefs: UiPrefs) =>
  apiFetch<PrefsResponse>("/api/me/prefs", { method: "PUT", body: prefs });

// Admin user management (admin only) -----------------------------------------------------

export const adminListUsers = () => apiFetch<AdminUsersResponse>("/api/admin/users");

export const adminCreateUser = (body: AdminUserCreateRequest) =>
  apiFetch<AdminUserCreateResponse>("/api/admin/users", { method: "POST", body });

export const adminResetPassword = (userId: string, body: AdminPasswordResetRequest) =>
  apiFetch<void>(`/api/admin/users/${encodeURIComponent(userId)}/password`, {
    method: "POST",
    body,
  });

export const adminDeleteUser = (userId: string) =>
  apiFetch<void>(`/api/admin/users/${encodeURIComponent(userId)}`, { method: "DELETE" });

/** Server-global settings (admin only): currently the "use system HTTP proxy" switch. */
export const adminGetSettings = () => apiFetch<ServerSettingsResponse>("/api/admin/settings");

/**
 * Speech input (admin only): the provider site, model and key the server transcribes the
 * composer's recording with. The read is masked — it carries `hasKey`, never the key.
 */
export const getAsrConfig = () => apiFetch<AsrConfigResponse>("/api/asr/config");

/** Stores the speech-model settings; an omitted or empty `apiKey` keeps the stored one. */
export const putAsrConfig = (body: AsrConfigUpdateRequest) =>
  apiFetch<AsrConfigResponse>("/api/asr/config", { method: "PUT", body });

/**
 * Asks the configured service whether it will take this site, this model and this key: one whole
 * task with no audio in it. An omitted field falls back to what is stored, so a check may be run
 * on a form that has not been saved. `ok: false` is the check's answer, not a failed request.
 */
export const testAsrConfig = (body: AsrTestRequest) =>
  apiFetch<AsrTestResponse>("/api/asr/test", { method: "POST", body });

/**
 * Transcribes one recording (any signed-in user — the admin configured the key). The audio
 * rides base64 because it is binary, as every other binary body in this API does.
 */
export const asrTranscribe = (body: AsrTranscribeRequest) =>
  apiFetch<AsrTranscribeResponse>("/api/asr/transcribe", { method: "POST", body });

/*
 * Plugin configuration is kept by each server in its own database, so `server` names the
 * machine whose settings are read or written — through this server's tunnel to it — and null
 * is this server's own. Nothing copies these values between machines.
 */

/** Every loaded plugin that declares a configuration, with its schema and masked values (admin). */
export const adminGetPluginConfig = (server: string | null = null) =>
  apiFetch<PluginConfigResponse>("/api/admin/plugin-config", { server });

/** One package's update (admin): omitted fields keep their value, a masked secret sent back keeps the stored one. */
export const adminPutPluginConfig = (
  body: PluginConfigUpdateRequest,
  server: string | null = null,
) => apiFetch<PluginConfigResponse>("/api/admin/plugin-config", { method: "PUT", body, server });

/** Runs one settings group's action (admin): what a deployment must DO on the machine, once. */
export const adminRunPluginConfigAction = (
  body: { name: string; action: string },
  server: string | null = null,
) =>
  apiFetch<PluginConfigActionResponse>("/api/admin/plugin-config/action", {
    method: "POST",
    body,
    server,
  });

/** Omitted fields keep their current value; applies immediately (no restart). */
export const adminPutSettings = (body: ServerSettingsUpdateRequest) =>
  apiFetch<ServerSettingsResponse>("/api/admin/settings", { method: "PUT", body });

/**
 * What the reachability probe would request — name and exact URL per provider — without
 * requesting it. Served rather than held as a frontend constant so the listed URLs cannot
 * drift from the ones actually fetched.
 */
export const adminGetProxyProbeTargets = () =>
  apiFetch<ProxyProbeTargetsResponse>("/api/admin/settings/proxy-probe");

/**
 * Measures the server's own outbound path to ONE of those targets, unauthenticated. One
 * request per provider so each row can be filled the moment its own answer arrives; the
 * provider id is the only thing sent, and the server matches it against the same fixed list.
 */
export const adminProbeProxy = (provider: ProxyProbeProvider) =>
  apiFetch<ProxyProbeResponse>(`/api/admin/settings/proxy-probe/${provider}`, { method: "POST" });

/**
 * The data root's storage ledger (admin): what is on disk, by class, with the entries that
 * matched a cleanup rule. A measurement and nothing more — the server moves and deletes no file
 * to answer this, and no route executes a cleanup on the strength of the report it returns.
 */
export const adminGetStorageReport = () => apiFetch<StorageReportResponse>("/api/admin/storage");

/**
 * The cleanup mode, machine-wide like the root it describes: `enabled` is off until a person turns
 * it on, and every route that writes — scanning out a bill, pinning, moving, purging — is refused
 * with 409 `storage_mode_off` while it is off. `pins` are the paths a person decided to keep.
 */
export const adminGetStorageSettings = () =>
  apiFetch<StorageSettingsResponse>("/api/admin/storage/settings");

/** An omitted field keeps its stored value; the response is the mode as it now stands. */
export const adminUpdateStorageSettings = (body: StorageSettingsUpdateRequest) =>
  apiFetch<StorageSettingsResponse>("/api/admin/storage/settings", { method: "PUT", body });

/**
 * Writes a bill out of the ledger: a walk of the whole root, and a POST because it creates a file
 * (the plan), not because it moves anything. The bill is a snapshot of one instant, reviewed
 * before anything acts on it — nothing scans on a timer, so this is only ever somebody's click.
 */
export const adminScanStorage = () =>
  apiFetch<StoragePlanResponse>("/api/admin/storage/plans", { method: "POST", body: {} });

/** The recent bills, newest first — so a page reload can find the one the server still holds. */
export const adminListStoragePlans = () =>
  apiFetch<StoragePlansResponse>("/api/admin/storage/plans");

/** One bill, as it stands now (`usable` / `expired` are computed at read time, not stored). */
export const adminGetStoragePlan = (planId: string) =>
  apiFetch<StoragePlanResponse>(`/api/admin/storage/plans/${encodeURIComponent(planId)}`);

/**
 * Keeps one path out of every later bill, or lets it back in. The plan in the path is read first,
 * so pinning an entry of a bill that is gone is told so rather than answered with a settings blob.
 */
export const adminPinStoragePath = (planId: string, body: StoragePinRequest) =>
  apiFetch<StorageSettingsResponse>(`/api/admin/storage/plans/${encodeURIComponent(planId)}/pin`, {
    method: "POST",
    body,
  });

/**
 * Moves the approved entries into the trash — the only route that changes the data root, and it
 * needs a bill's id, **that bill's own fingerprint** and an explicit path list. A fingerprint the
 * server does not hold a bill for, a bill already spent, or one past its day is refused, so what
 * moves is exactly what somebody read and ticked.
 */
export const adminApplyStoragePlan = (body: StorageApplyRequest) =>
  apiFetch<StorageApplyResponse>("/api/admin/storage/apply", { method: "POST", body });

/** What moves have put aside: measured now, so a listing never lies about what is on disk. */
export const adminGetStorageTrash = () =>
  apiFetch<StorageTrashResponse>("/api/admin/storage/trash");

/** Puts one trash entry's trees back where they came from, refusing whatever is in the way. */
export const adminRestoreStorageTrash = (id: string) =>
  apiFetch<StorageRestoreResponse>("/api/admin/storage/trash/restore", {
    method: "POST",
    body: { id },
  });

/**
 * The one deletion in the API: with an id it removes that trash entry, without one only the
 * entries past the retention. It never reaches anything that is not already in the trash, and
 * nothing calls it on a timer.
 */
export const adminPurgeStorageTrash = (id?: string) =>
  apiFetch<StoragePurgeResponse>("/api/admin/storage/trash/purge", {
    method: "POST",
    body: id === undefined ? {} : { id },
  });

// Project & members --------------------------------------------------------------

export const listProjects = () => apiFetch<ProjectsResponse>("/api/projects");

export const createProject = (body: ProjectCreateRequest) =>
  apiFetch<ProjectCreateResponse>("/api/projects", { method: "POST", body });

/** Rename a Project's display name (owner); the id is immutable. */
export const updateProject = (projectId: string, body: ProjectUpdateRequest) =>
  apiFetch<ProjectUpdateResponse>(`/api/projects/${encodeURIComponent(projectId)}`, {
    method: "PATCH",
    body,
  });

export const deleteProject = (projectId: string) =>
  apiFetch<void>(`/api/projects/${encodeURIComponent(projectId)}`, { method: "DELETE" });

export const listMembers = (projectId: string) =>
  apiFetch<MembersResponse>(`/api/projects/${encodeURIComponent(projectId)}/members`);

export const addMember = (projectId: string, body: MemberAddRequest) =>
  apiFetch<MemberAddResponse>(`/api/projects/${encodeURIComponent(projectId)}/members`, {
    method: "POST",
    body,
  });

export const removeMember = (projectId: string, username: string) =>
  apiFetch<void>(
    `/api/projects/${encodeURIComponent(projectId)}/members/${encodeURIComponent(username)}`,
    { method: "DELETE" },
  );

/** New-chat defaults ([default_chat]): member-readable prefill for the draft page. */
export const getChatDefaults = (projectId: string) =>
  apiFetch<ChatDefaultsDto>(`/api/projects/${encodeURIComponent(projectId)}/chat-defaults`);

/** Whole-block replace (owner): an omitted key clears it; returns the stored block. */
export const putChatDefaults = (projectId: string, body: ChatDefaultsDto) =>
  apiFetch<ChatDefaultsDto>(`/api/projects/${encodeURIComponent(projectId)}/chat-defaults`, {
    method: "PUT",
    body,
  });

/** Sandbox command policy ([command_policy]): member-readable; carries the factory set for "restore defaults". */
export const getCommandPolicy = (projectId: string) =>
  apiFetch<CommandPolicyDto>(`/api/projects/${encodeURIComponent(projectId)}/command-policy`);

/** Whole-block replace (owner): the full rule list is required and gets materialized into the config. */
export const putCommandPolicy = (
  projectId: string,
  body: { enabled: boolean; rules: CommandPolicyRuleDto[] },
) =>
  apiFetch<CommandPolicyDto>(`/api/projects/${encodeURIComponent(projectId)}/command-policy`, {
    method: "PUT",
    body,
  });

// Model configuration -------------------------------------------------------------------

export const getModels = (projectId: string) =>
  apiFetch<ModelsResponse>(`/api/projects/${encodeURIComponent(projectId)}/models`);

export const putModels = (projectId: string, body: ModelsUpdateRequest) =>
  apiFetch<ModelsResponse>(`/api/projects/${encodeURIComponent(projectId)}/models`, {
    method: "PUT",
    body,
  });

/** Narrow default-model switch (owner): flips the same default_model the models page maintains, without resending the table. */
export const putDefaultModel = (projectId: string, body: DefaultModelUpdateRequest) =>
  apiFetch<DefaultModelResponse>(`/api/projects/${encodeURIComponent(projectId)}/models/default`, {
    method: "PUT",
    body,
  });

/**
 * One of the caller's own global secrets (the account menu's user keys), copied onto every model
 * of a provider group as its api_key. The request names the entry, never its value: only the
 * server can read the plaintext, so the copy happens there. A copy, not a link — editing the
 * global entry afterwards means assigning again.
 */
export const assignUserKeyToModels = (projectId: string, body: ModelUserKeyAssignRequest) =>
  apiFetch<ModelUserKeyAssignResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/models/assign-user-key`,
    { method: "POST", body },
  );

/**
 * A group's account balance, read by the server with the group's stored key (the key never
 * comes back). `force` skips the server's 60 s cache — the page's refresh click.
 */
export const getModelBalance = (projectId: string, provider: string, force = false) =>
  apiFetch<ModelBalanceResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/models/balance?provider=${encodeURIComponent(provider)}${force ? "&force=1" : ""}`,
  );

/** Connectivity test: model reference (provider, modelId) is passed in the request body (may include an unsaved apiKey / baseUrl). */
export const testModel = (projectId: string, body: ModelTestRequest) =>
  apiFetch<ModelTestResponse>(`/api/projects/${encodeURIComponent(projectId)}/models/test`, {
    method: "POST",
    body,
  });

/** Protocol auto-detection for a custom base URL: probes openai-responses → ant-messages → openai-chat and returns the first protocol the endpoint serves. */
export const detectProtocol = (projectId: string, body: ModelProtocolDetectRequest) =>
  apiFetch<ModelProtocolDetectResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/models/detect`,
    { method: "POST", body },
  );

/** Endpoint model listing: given a base URL plus the protocol /detect reported, returns every model id the endpoint serves (the add-group import). */
export const listEndpointModels = (projectId: string, body: EndpointModelListRequest) =>
  apiFetch<EndpointModelListResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/models/list`,
    { method: "POST", body },
  );

/** Vision probe: sends one 1x1 image on this model's credential and reports whether it was accepted (a real, billed completion — unlike the protocol probes). */
export const detectVision = (projectId: string, body: ModelVisionDetectRequest) =>
  apiFetch<ModelVisionDetectResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/models/detect-vision`,
    { method: "POST", body },
  );

// Provider key minting (owner) ----------------------------------------------------------

/**
 * Opens an authorization flow for a provider group that publishes one, and returns the page
 * to send the user to. The PKCE verifier and the key it eventually mints stay on the server;
 * this side only ever holds the flow id.
 */
export const startModelOAuth = (projectId: string, body: ModelOAuthStartRequest) =>
  apiFetch<ModelOAuthStartResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/model-oauth/start`,
    { method: "POST", body },
  );

/** Where a flow stands; 404 once it has expired. */
export const getModelOAuthStatus = (projectId: string, flowId: string) =>
  apiFetch<ModelOAuthStatusResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/model-oauth/${encodeURIComponent(flowId)}`,
  );

/** Redeems a code the user pasted, for when the provider's redirect cannot reach the harness. */
export const submitModelOAuthCode = (projectId: string, flowId: string, code: string) =>
  apiFetch<ModelOAuthCodeResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/model-oauth/${encodeURIComponent(flowId)}/code`,
    { method: "POST", body: { code } },
  );

// Bridge-authorized groups (owner) -----------------------------------------------
//
// Penguin Go and ModelScope both hand a group an API key by creating a server-side flow,
// polling it, and reporting the same six states and seven failure codes; only the route and
// the name of the "this flow is gone" code differ. Each group therefore gets one descriptor
// here rather than four loose exports, and the dialog they share takes one as a prop — a
// third such group is an entry in this section, not a third copy of the dialog.

export interface KeyAuthEndpoints {
  /**
   * The code the server answers with once a flow no longer exists (expired or unknown). The
   * dialog drops its handle on it and offers a fresh start instead of a retry.
   */
  flowNotFoundCode: string;
  start: (projectId: string) => Promise<PlatformAuthStartResponse>;
  status: (projectId: string, flowId: string) => Promise<PlatformAuthFlowStatusResponse>;
  retryApply: (projectId: string, flowId: string) => Promise<PlatformAuthFlowStatusResponse>;
  cancel: (projectId: string, flowId: string) => Promise<{ ok: boolean }>;
}

function keyAuth(route: string, flowNotFoundCode: string): KeyAuthEndpoints {
  const prefix = (projectId: string): string =>
    `/api/projects/${encodeURIComponent(projectId)}/${route}`;
  const flow = (projectId: string, flowId: string): string =>
    `${prefix(projectId)}/${encodeURIComponent(flowId)}`;
  return {
    flowNotFoundCode,
    start: (projectId) =>
      apiFetch<PlatformAuthStartResponse>(`${prefix(projectId)}/start`, {
        method: "POST",
        body: {},
      }),
    status: (projectId, flowId) =>
      apiFetch<PlatformAuthFlowStatusResponse>(`${flow(projectId, flowId)}/status`),
    retryApply: (projectId, flowId) =>
      apiFetch<PlatformAuthFlowStatusResponse>(`${flow(projectId, flowId)}/retry`, {
        method: "POST",
        body: {},
      }),
    cancel: (projectId, flowId) =>
      apiFetch<{ ok: boolean }>(`${flow(projectId, flowId)}/cancel`, { method: "POST", body: {} }),
  };
}

/** Penguin Go's relay authorization. */
export const platformAuthEndpoints = keyAuth("platform-auth", "platform_auth_flow_not_found");

/** ModelScope's, run through the harness's own authorization bridge. */
export const modelScopeAuthEndpoints = keyAuth("modelscope-auth", "modelscope_auth_flow_not_found");

export const syncPlatformModels = (projectId: string) =>
  apiFetch<PlatformModelSyncResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/platform-auth/sync`,
    { method: "POST", body: {} },
  );

// Vault environment variables (Agent-level) -------------------------------------------------------

export const getVault = (projectId: string, agentId: string) =>
  apiFetch<VaultResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}/vault`,
  );

export const putVault = (projectId: string, agentId: string, body: VaultUpdateRequest) =>
  apiFetch<VaultResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}/vault`,
    { method: "PUT", body },
  );

/** Inserts the {{VAULT}} placeholder into the agent's prompt template — migrating a legacy hardcoded # Vault section verbatim when one is present (idempotent, owner-only). */
export const insertVaultPlaceholder = (projectId: string, agentId: string) =>
  apiFetch<AgentVaultConfigDto>(
    `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}/vault/template-placeholder`,
    { method: "POST", body: {} },
  );

// The signed-in user's own vault (user-level: `<root>/users/<userId>/.vault.toml`) ---------------
// No Project in the path: it is the account's own table, readable and writable by nobody else.

export const getUserVault = () => apiFetch<VaultResponse>("/api/me/vault");

/** Whole-table replace, the same body as {@link putVault}: keys absent from the body are deleted, an entry without a value keeps the stored one. */
export const putUserVault = (body: VaultUpdateRequest) =>
  apiFetch<VaultResponse>("/api/me/vault", { method: "PUT", body });

/** Imports a whole pasted JSON object into the table (merged: a same-named key is overwritten, the rest stay); the server parses and validates it, so a bad entry comes back as a 400 naming it. */
export const importUserVault = (body: UserVaultImportRequest) =>
  apiFetch<VaultResponse>("/api/me/vault/import", { method: "POST", body });

/** Copies the named keys from the caller's own user vault into this agent's vault — a one-off copy (same key overwrites, the agent's other entries stay). */
export const assignUserVaultToAgent = (
  projectId: string,
  agentId: string,
  body: UserVaultAssignRequest,
) =>
  apiFetch<VaultResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}/vault/assign-user-vault`,
    { method: "POST", body },
  );

/** Inserts the {{SKILLS}} placeholder into the agent's prompt template — migrating a legacy hardcoded # Skills section verbatim when one is present (idempotent). */
export const insertSkillsPlaceholder = (projectId: string, agentId: string) =>
  apiFetch<AgentSkillsConfigDto>(
    `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}/skills/template-placeholder`,
    { method: "POST", body: {} },
  );

/** Inserts the {{SCHEDULES}} placeholder into the agent's prompt template (idempotent, owner-only; Schedules has no legacy section to migrate). */
export const insertSchedulesPlaceholder = (projectId: string, agentId: string) =>
  apiFetch<AgentSchedulesConfigDto>(
    `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}/schedules/template-placeholder`,
    { method: "POST", body: {} },
  );

// Memory (Agent-level, agent_state/memory/) -------------------------------------------------

/** Base path of an Agent's Memory API; the scope key and file name are single path segments (never a path). */
const memoryBase = (projectId: string, agentId: string) =>
  `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}/memory`;

const memoryFilesBase = (projectId: string, agentId: string, scopeKey: string) =>
  `${memoryBase(projectId, agentId)}/scopes/${encodeURIComponent(scopeKey)}/files`;

export const getMemoryOverview = (projectId: string, agentId: string) =>
  apiFetch<MemoryOverviewResponse>(memoryBase(projectId, agentId));

/** Inserts the {{MEMORY}} placeholder into the agent's prompt template (idempotent) — the explicit adoption path for an agent created before Memory. */
export const insertMemoryPlaceholder = (projectId: string, agentId: string) =>
  apiFetch<MemoryOverviewResponse>(`${memoryBase(projectId, agentId)}/template-placeholder`, {
    method: "POST",
    body: {},
  });

export const getMemoryFiles = (projectId: string, agentId: string, scopeKey: string) =>
  apiFetch<MemoryFilesResponse>(memoryFilesBase(projectId, agentId, scopeKey));

export const getMemoryFile = (projectId: string, agentId: string, scopeKey: string, name: string) =>
  apiFetch<MemoryFileResponse>(
    `${memoryFilesBase(projectId, agentId, scopeKey)}/${encodeURIComponent(name)}`,
  );

export const deleteMemoryFile = (
  projectId: string,
  agentId: string,
  scopeKey: string,
  name: string,
) =>
  apiFetch<void>(`${memoryFilesBase(projectId, agentId, scopeKey)}/${encodeURIComponent(name)}`, {
    method: "DELETE",
  });

const memoryScopeBase = (projectId: string, agentId: string, scopeKey: string) =>
  `${memoryBase(projectId, agentId)}/scopes/${encodeURIComponent(scopeKey)}`;

/**
 * One scope as a transfer document. Fetched as ordinary JSON rather than followed as a download
 * link so a failure arrives as an ApiError and is shown in the group that asked — a bare
 * `<a download>` would save the error body as a file (the skills tab hit the same wall). The server
 * still sets Content-Disposition, for anyone opening the URL directly.
 */
export const exportMemoryScope = (projectId: string, agentId: string, scopeKey: string) =>
  apiFetch<MemoryScopeExport>(`${memoryScopeBase(projectId, agentId, scopeKey)}/export`);

/** Writes a transfer document into one scope (owner only); `confirm` is required by the modes that would destroy something. */
export const importMemoryScope = (
  projectId: string,
  agentId: string,
  scopeKey: string,
  body: MemoryImportRequest,
) =>
  apiFetch<MemoryImportResponse>(`${memoryScopeBase(projectId, agentId, scopeKey)}/import`, {
    method: "POST",
    body,
  });

// Agent & its configuration ----------------------------------------------------------------

/**
 * A project's Agents. With a machine, THAT machine's — Agents are per-server, so a Session
 * created on one can only name an Agent that exists there.
 */
export const listAgents = (projectId: string, machineId?: string | null) =>
  apiFetch<AgentsResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/agents`,
    machineId === undefined ? {} : { server: machineId },
  );

export const createAgent = (projectId: string, body: AgentCreateRequest) =>
  apiFetch<AgentCreateResponse>(`/api/projects/${encodeURIComponent(projectId)}/agents`, {
    method: "POST",
    body,
  });

export const getAgentConfig = (projectId: string, agentId: string) =>
  apiFetch<AgentConfigResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}/config`,
  );

export const putAgentConfig = (
  projectId: string,
  agentId: string,
  body: AgentConfigUpdateRequest,
) =>
  apiFetch<AgentConfigResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}/config`,
    { method: "PUT", body },
  );

/** Probes one MCP Server entry's reachability (server-side connect + tool discovery; nothing is saved). */
export const testAgentMcpServer = (projectId: string, agentId: string, body: MCPServerConfig) =>
  apiFetch<McpServerTestResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}/config/mcp-test`,
    { method: "POST", body },
  );

/** Overwrite system_config.yaml with the current defaults (keeps only name/description/version). */
export const resetAgentConfig = (projectId: string, agentId: string) =>
  apiFetch<AgentConfigResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}/config/reset`,
    { method: "POST" },
  );

/** Smart-merge the config up to the current defaults generation (customizations kept and reported); non-destructive sibling of resetAgentConfig. */
export const kernelUpdateAgentConfig = (projectId: string, agentId: string) =>
  apiFetch<AgentKernelUpdateResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}/config/kernel-update`,
    { method: "POST" },
  );

// An Agent's public API (the stream itself is AMSP under /api/amsp/v1; these are its settings) ---

const agentApiBase = (projectId: string, agentId: string) =>
  `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}/api`;

/** The Agent's API switch, keyless switch, approval mode and keys (any member may read them). */
export const getAgentApi = (projectId: string, agentId: string) =>
  apiFetch<AgentApiResponse>(agentApiBase(projectId, agentId));

/** Changes the given settings and keeps the rest (owner only). */
export const putAgentApi = (projectId: string, agentId: string, body: AgentApiUpdateRequest) =>
  apiFetch<AgentApiResponse>(agentApiBase(projectId, agentId), { method: "PUT", body });

/** Mints a key (owner only): the answer is the one place the secret is ever shown. */
export const createAgentApiKey = (
  projectId: string,
  agentId: string,
  body: AgentApiKeyCreateRequest,
) =>
  apiFetch<AgentApiKeyCreateResponse>(`${agentApiBase(projectId, agentId)}/keys`, {
    method: "POST",
    body,
  });

/** Deletes a key for good (owner only): a program presenting it is refused from the next request on. */
export const deleteAgentApiKey = (projectId: string, agentId: string, keyId: string) =>
  apiFetch<void>(`${agentApiBase(projectId, agentId)}/keys/${encodeURIComponent(keyId)}`, {
    method: "DELETE",
  });

/**
 * Runs the Agent once through its API for the owner's sign-in (the API tab's Try it): the body is
 * the public runs route's, and the answer the same AMSP event stream, handed back unread for
 * `readSse` (or the same JSON refusal, as an ApiError).
 */
export const tryAgentApi = (
  projectId: string,
  agentId: string,
  body: RunRequest,
  opts: { signal?: AbortSignal } = {},
) =>
  apiFetchStream(`${agentApiBase(projectId, agentId)}/try`, {
    method: "POST",
    body,
    ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
  });

// Session ---------------------------------------------------------------------

/**
 * Optional paging (absent = full unfiltered list): the store requests `limit+1` per page to
 * detect "has more". `category` filters server-side (paging applies within the category);
 * `workspaceGroup` narrows the same way to one Workspace group, so a group can page its own
 * stream; `withCounts` asks for per-category totals over the whole list alongside the page.
 *
 * The sidebar pages in activity order with a cursor (`order: "activity"` + `before`), never by
 * offset: activity reorders the list while it is being read, and an offset page would skip a row
 * that moved above it. A server that predates `order` ignores both parameters and answers in
 * creation order — the next page then repeats rows the pool already holds, deduplicated by id.
 */
export const listSessions = (
  projectId: string,
  agentId: string,
  opts?: {
    /** Rows to skip, in creation order. Exclusive with `before`. */
    offset?: number;
    limit: number;
    /** `activity`: last activity first, ties by id descending (code-point order) — the sidebar's order. Omitted: creation order. */
    order?: "created" | "activity";
    /** Activity order only: rows strictly below this key — the last row of the previous page. */
    before?: ActivityKey;
    category?: SessionCategory;
    /** One Workspace group's rows only: its path, or the merged temporary group's sentinel (session-grouping.ts). */
    workspaceGroup?: string;
    withCounts?: boolean;
    /** The user's own rows only: an organization's desk, ticket and sub-sessions leave the page and the totals together (the development list's contract). */
    excludeOrg?: boolean;
  },
  /**
   * Which machine to ask. This path is NOT session-scoped, so nothing about it can be routed
   * from an id — it asks a server which Sessions IT has, and only the caller knows which
   * servers are worth asking. Omitted (or null) means this one.
   */
  machineId?: string | null,
) => {
  const qs = opts
    ? `?limit=${opts.limit}` +
      (opts.offset !== undefined ? `&offset=${opts.offset}` : "") +
      (opts.order ? `&order=${opts.order}` : "") +
      (opts.before ? `&before=${encodeURIComponent(activityCursorParam(opts.before))}` : "") +
      (opts.category ? `&category=${opts.category}` : "") +
      (opts.workspaceGroup ? `&workspaceGroup=${encodeURIComponent(opts.workspaceGroup)}` : "") +
      (opts.withCounts ? "&counts=1" : "") +
      (opts.excludeOrg ? "&excludeOrg=1" : "")
    : "";
  return apiFetch<SessionsResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}/sessions${qs}`,
    { server: machineId ?? null },
  );
};

/**
 * A whole sidebar reload in one round trip: every (Agent, page) pair the sidebar wants,
 * asked in a single POST instead of one GET each.
 *
 * The split matters on a Project with several Agents (and several machines): as individual
 * requests they were fired all at once and serialised by the browser's six-connections-per-host
 * limit, so the conversation pane's own message read queued behind dozens of list calls.
 * One request keeps every answer separate — `results` lines up with `requests`, and an Agent
 * this server does not host comes back as `ok: false, reason: "absent"` rather than failing
 * the batch.
 */
export const batchSessions = (
  projectId: string,
  requests: SessionBatchPageRequest[],
  machineId?: string | null,
) =>
  apiFetch<SessionsBatchResponse>(`/api/projects/${encodeURIComponent(projectId)}/sessions/batch`, {
    method: "POST",
    body: { requests } satisfies SessionsBatchRequest,
    server: machineId ?? null,
  });

/** Server directory browsing: `path` is an absolute path; empty means start from the server's home directory. */
/**
 * Browses directories. With no machine, this server's own filesystem; with one, THAT
 * machine's — listed by this server over ssh, so picking a workspace on another machine
 * needs no second login to that machine's own server.
 *
 * `places` asks a home request (empty `path`) for the machine's standard folders and its
 * locations (drives, volumes, mounts) as well. Only this server discovers them, so the flag
 * goes on the local route alone; a machine reached over ssh answers with its folders only.
 */
export const listDirs = (
  projectId: string,
  path = "",
  machineId?: string | null,
  opts?: { places?: boolean },
) => {
  const places = opts?.places === true ? "&places=1" : "";
  return machineId === undefined || machineId === null
    ? apiFetch<DirListResponse>(
        `/api/projects/${encodeURIComponent(projectId)}/dirs?path=${encodeURIComponent(path)}${places}`,
      )
    : apiFetch<DirListResponse>(
        `/api/projects/${encodeURIComponent(projectId)}/machines/${encodeURIComponent(machineId)}/dirs?path=${encodeURIComponent(path)}`,
      );
};

/**
 * Makes one folder inside `parent` (the picker's "New folder"). `name` is a single segment, not
 * a path, and only this server can be asked: a machine browsed over ssh lists folders, and the
 * picker offers no "New folder" while it is browsing one.
 */
export const createDir = (projectId: string, parent: string, name: string) =>
  apiFetch<DirCreateResponse>(`/api/projects/${encodeURIComponent(projectId)}/dirs`, {
    method: "POST",
    body: { parent, name },
  });

/**
 * Removes one EMPTY folder (the picker's "Delete"): `path` is absolute and names the folder
 * itself rather than a name inside another. The server refuses anything but an empty folder —
 * it never deletes a tree, a file, the root, or the Project's own directory and its parents —
 * and only this server can be asked, like New folder.
 */
export const deleteDir = (projectId: string, path: string) =>
  apiFetch<DirDeleteResponse>(`/api/projects/${encodeURIComponent(projectId)}/dirs`, {
    method: "DELETE",
    body: { path },
  });

/**
 * Asks the desktop shell to read a folder macOS refused, in the app's own name — what makes
 * macOS ask the user. Always this server: only the shell that started it can be asked. The
 * answer waits on the user's reply to that prompt.
 */
export const requestDirAccess = (projectId: string, path: string) =>
  apiFetch<DirAccessResponse>(`/api/projects/${encodeURIComponent(projectId)}/dirs/access`, {
    method: "POST",
    body: { path },
    server: null,
  });

/**
 * Skills a directory carries under `.agents/skills` / `.claude/skills`: what picking it at Agent
 * creation would offer to install. `path` must be absolute.
 */
export const listDirectorySkills = (projectId: string, path: string) =>
  apiFetch<DirectorySkillsResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/dir-skills?path=${encodeURIComponent(path)}`,
  );

/**
 * Creates a Session on the machine that owns its workspace.
 *
 * The Session is created THERE because that is where its workspace is: that server runs the
 * agent, holds the messages, writes the trace. The id it hands back is recorded against that
 * machine, so every later call about the Session routes itself without any call site knowing
 * (see lib/session-machines.ts).
 *
 * `machineId` is the workspace's, not a preference — a path names a different directory on
 * every machine, so creating a Session for `/srv/app` on the wrong one is not a degraded
 * result, it is a different request.
 */
export const createSession = async (
  projectId: string,
  agentId: string,
  body: SessionCreateRequest,
  machineId?: string | null,
) => {
  const created = await apiFetch<SessionCreateResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}/sessions`,
    { method: "POST", body, server: machineId ?? null },
  );
  rememberSessionMachine(created.session.sessionId, machineId ?? null);
  return created;
};

export const forkSession = (sessionId: string, body: SessionForkRequest) =>
  apiFetch<SessionForkResponse>(`/api/sessions/${encodeURIComponent(sessionId)}/fork`, {
    method: "POST",
    body,
  });

/**
 * One Session's row. `machineId` names the server to ask when the caller knows and the id map
 * does not yet — a Session the list has never fetched, announced by a machine's own event
 * stream. Omitted, the id routes itself (lib/session-machines.ts).
 */
export const getSession = (sessionId: string, machineId?: string | null) =>
  apiFetch<SessionResponse>(
    `/api/sessions/${encodeURIComponent(sessionId)}`,
    machineId === undefined ? {} : { server: machineId },
  );

export const patchSession = (sessionId: string, body: SessionPatchRequest) =>
  apiFetch<SessionResponse>(`/api/sessions/${encodeURIComponent(sessionId)}`, {
    method: "PATCH",
    body,
  });

export const deleteSession = (sessionId: string) =>
  apiFetch<void>(`/api/sessions/${encodeURIComponent(sessionId)}`, { method: "DELETE" });

// Messaging bindings ----------------------------------------------------------

/** The channel-agnostic read: every saved channel config + status (the channel-aware editor's load + poll). */
export const getMessagingBinding = (sessionId: string) =>
  apiFetch<MessagingBindingsResponse>(`/api/sessions/${encodeURIComponent(sessionId)}/messaging`);

/** Saves Feishu credentials only — the connection toggle is setMessagingBindingState (an enabled binding restarts on save so config and connection never diverge). */
export const putFeishuBinding = (sessionId: string, body: FeishuBindingPutRequest) =>
  apiFetch<FeishuBindingResponse>(
    `/api/sessions/${encodeURIComponent(sessionId)}/messaging/feishu`,
    { method: "PUT", body },
  );

/** Saves the Telegram token only — the same save/enable split as the Feishu PUT. */
export const putTelegramBinding = (sessionId: string, body: TelegramBindingPutRequest) =>
  apiFetch<TelegramBindingResponse>(
    `/api/sessions/${encodeURIComponent(sessionId)}/messaging/telegram`,
    { method: "PUT", body },
  );

/** Saves the QQ App ID / App Secret pair only — the same save/enable split as the Feishu PUT. */
export const putQQBinding = (sessionId: string, body: QQBindingPutRequest) =>
  apiFetch<QQBindingResponse>(`/api/sessions/${encodeURIComponent(sessionId)}/messaging/qq`, {
    method: "PUT",
    body,
  });

/**
 * Saves the WeChat delivery preferences. No credential rides along: this channel's token
 * comes only from a scan, so a PUT before one answers 400 `wechat_token_required`.
 */
export const putWeChatBinding = (sessionId: string, body: WeChatBindingPutRequest) =>
  apiFetch<WeChatBindingResponse>(
    `/api/sessions/${encodeURIComponent(sessionId)}/messaging/wechat`,
    { method: "PUT", body },
  );

/** The connection toggle, which is also the bind/unbind: enable connects with the STORED credentials (409 `another_channel_enabled` while the other channel is enabled, 409 `account_enabled_elsewhere` while another conversation has this bot enabled), disable releases the account. */
export const setMessagingBindingState = (
  sessionId: string,
  channel: MessagingChannel,
  enabled: boolean,
) =>
  apiFetch<FeishuBindingResponse | TelegramBindingResponse | QQBindingResponse>(
    `/api/sessions/${encodeURIComponent(sessionId)}/messaging/${channel}/state`,
    { method: "POST", body: { enabled } },
  );

/** Feishu credential probe with the form's draft values; omitted fields fall back to the stored binding. */
export const testFeishuBinding = (sessionId: string, body: FeishuTestRequest) =>
  apiFetch<FeishuTestResponse>(
    `/api/sessions/${encodeURIComponent(sessionId)}/messaging/feishu/test`,
    { method: "POST", body },
  );

/** Telegram credential probe (`getMe`); success additionally names the bot's @username. */
export const testTelegramBinding = (sessionId: string, body: TelegramTestRequest) =>
  apiFetch<TelegramTestResponse>(
    `/api/sessions/${encodeURIComponent(sessionId)}/messaging/telegram/test`,
    { method: "POST", body },
  );

/**
 * Starts a QQ scan-to-connect flow. The response carries the URL to render as a QR code and
 * a task handle — never the AES key that decrypts the App Secret, which stays on the server.
 */
export const startQQScan = (sessionId: string) =>
  apiFetch<QQScanStartResponse>(
    `/api/sessions/${encodeURIComponent(sessionId)}/messaging/qq/scan`,
    {
      method: "POST",
      body: {},
    },
  );

/** One poll of a scan. `completed` means the server already decrypted and SAVED the credentials. */
export const pollQQScan = (sessionId: string, taskId: string) =>
  apiFetch<QQScanPollResponse>(
    `/api/sessions/${encodeURIComponent(sessionId)}/messaging/qq/scan/poll`,
    { method: "POST", body: { taskId } },
  );

/** Drops a scan the user walked away from, so its key is forgotten rather than left to expire. */
export const cancelQQScan = (sessionId: string, taskId: string) =>
  apiFetch<void>(`/api/sessions/${encodeURIComponent(sessionId)}/messaging/qq/scan/cancel`, {
    method: "POST",
    body: { taskId },
  });

/**
 * Starts a WeChat scan-to-connect flow — the ONLY way to bind this channel. The response
 * carries the URL to render as a QR code and a task handle; the platform's own poll handle,
 * which is what collects the bot token, stays on the server.
 */
export const startWeChatScan = (sessionId: string) =>
  apiFetch<WeChatScanStartResponse>(
    `/api/sessions/${encodeURIComponent(sessionId)}/messaging/wechat/scan`,
    { method: "POST", body: {} },
  );

/** One poll of a scan. `completed` means the server has already SAVED the credential. */
export const pollWeChatScan = (sessionId: string, taskId: string) =>
  apiFetch<WeChatScanPollResponse>(
    `/api/sessions/${encodeURIComponent(sessionId)}/messaging/wechat/scan/poll`,
    { method: "POST", body: { taskId } },
  );

/**
 * Submits the pairing code WeChat showed on the phone. It rides the NEXT poll rather than a
 * request of its own, so this only records it — a wrong code surfaces as the poll asking again.
 */
export const verifyWeChatScan = (sessionId: string, taskId: string, verifyCode: string) =>
  apiFetch<void>(`/api/sessions/${encodeURIComponent(sessionId)}/messaging/wechat/scan/verify`, {
    method: "POST",
    body: { taskId, verifyCode },
  });

/** Drops a scan the user walked away from, so its handle is forgotten rather than left to expire. */
export const cancelWeChatScan = (sessionId: string, taskId: string) =>
  apiFetch<void>(`/api/sessions/${encodeURIComponent(sessionId)}/messaging/wechat/scan/cancel`, {
    method: "POST",
    body: { taskId },
  });

/** WeChat credential probe of the STORED binding; there is no draft to send and no account label back. */
export const testWeChatBinding = (sessionId: string) =>
  apiFetch<WeChatTestResponse>(
    `/api/sessions/${encodeURIComponent(sessionId)}/messaging/wechat/test`,
    { method: "POST", body: {} },
  );

/** QQ credential probe (the access-token exchange); the platform names no account, so success carries no label. */
export const testQQBinding = (sessionId: string, body: QQTestRequest) =>
  apiFetch<QQTestResponse>(`/api/sessions/${encodeURIComponent(sessionId)}/messaging/qq/test`, {
    method: "POST",
    body,
  });

/** Short fixed text to the binding's last known chat (409 `feishu_no_chat` / `telegram_no_chat` / `qq_no_chat` before one exists; on QQ the send can still fail with 502 when no recent QQ message can be replied to). */
export const sendMessagingTestMessage = (sessionId: string, channel: MessagingChannel) =>
  apiFetch<MessagingTestMessageResponse>(
    `/api/sessions/${encodeURIComponent(sessionId)}/messaging/${channel}/test-message`,
    { method: "POST", body: {} },
  );

/** Windowed history request: the newest N units (tail), or the N units before a cursor. */
export type MessagesPageQuery =
  { kind: "tail"; limit: number } | { kind: "before"; cursor: string; limit: number };

/**
 * History rebuild. Carries the server's clock at read time (see ApiFetchMeta.serverNowMs)
 * alongside the messages: a Task still running has no Trace entry for the event currently in
 * flight, so its elapsed can only be measured by differencing this against the Task's first
 * message timestamp — both server-side values, so no client clock offset enters the result
 * (see pushMessages).
 *
 * With `page`, requests a WINDOW instead of the full transcript (tail-first loading /
 * scroll-up backfill — see stream-controller): the response then carries
 * `MessagesResponse.page`. Omitted = the legacy full read (the resync fallback path).
 */
export const getMessages = (sessionId: string, page?: MessagesPageQuery) => {
  const qs =
    page === undefined
      ? ""
      : page.kind === "tail"
        ? `?tailLimit=${page.limit}`
        : `?before=${encodeURIComponent(page.cursor)}&limit=${page.limit}`;
  return apiFetchWithMeta<MessagesResponse>(
    `/api/sessions/${encodeURIComponent(sessionId)}/messages${qs}`,
  ).then(({ data, serverNowMs }) => ({ ...data, serverNowMs }));
};

// Task execution, approval, abort, compaction ------------------------------------------------------

export const postTask = (sessionId: string, body: TaskCreateRequest) =>
  apiFetch<TaskCreateResponse>(`/api/sessions/${encodeURIComponent(sessionId)}/tasks`, {
    method: "POST",
    body,
  });

export const getGoal = (sessionId: string) =>
  apiFetch<GoalResponse>(`/api/sessions/${encodeURIComponent(sessionId)}/goal`);

export const postApproval = (
  sessionId: string,
  toolCallId: string,
  body: ApprovalDecisionRequest,
) =>
  apiFetch<void>(
    `/api/sessions/${encodeURIComponent(sessionId)}/approvals/${encodeURIComponent(toolCallId)}`,
    { method: "POST", body },
  );

/**
 * Hands one EXECUTING tool call back as a background task, so the turn closes and the
 * conversation carries on (404 tool_call_not_found when the call already finished — a benign
 * race the caller just ignores; 409 tool_not_detachable when the tool has no background form).
 */
export const postToolCallBackground = (sessionId: string, toolCallId: string) =>
  apiFetch<void>(
    `/api/sessions/${encodeURIComponent(sessionId)}/tool-calls/${encodeURIComponent(toolCallId)}/background`,
    { method: "POST", body: {} },
  );

export const postAbort = (sessionId: string) =>
  apiFetch<void>(`/api/sessions/${encodeURIComponent(sessionId)}/abort`, {
    method: "POST",
    body: {},
  });

/** "Retry now" on the reconnect countdown: skips the remaining backoff wait server-side (skipped:false is the benign "no wait in progress" case — e.g. the timer elapsed in a race — never an error). */
export const postRetryNow = (sessionId: string) =>
  apiFetch<RetryNowResponse>(`/api/sessions/${encodeURIComponent(sessionId)}/retry-now`, {
    method: "POST",
    body: {},
  });

/** Background processes the conversation started (details popover list); an evicted/never-loaded runtime reports an empty list. */
export const getSessionProcesses = (sessionId: string) =>
  apiFetch<SessionProcessesResponse>(`/api/sessions/${encodeURIComponent(sessionId)}/processes`);

/** Stops one background process (404 process_not_found when it already exited or the runtime is gone — callers just refresh). */
export const killSessionProcess = (sessionId: string, processId: string) =>
  apiFetch<void>(
    `/api/sessions/${encodeURIComponent(sessionId)}/processes/${encodeURIComponent(processId)}/kill`,
    { method: "POST", body: {} },
  );

/** Removes one EXITED background process entry from the list (409 process_running while it still runs — stopping is the kill route's job; 404 when it is already gone — callers just refresh). */
export const removeSessionProcess = (sessionId: string, processId: string) =>
  apiFetch<void>(
    `/api/sessions/${encodeURIComponent(sessionId)}/processes/${encodeURIComponent(processId)}`,
    { method: "DELETE" },
  );

/** Mid-run steering: queues a message for the running Task (delivered between turns as a standalone `[user_steering]` user message); 409 not_running when no Task is in progress. */
export const postSteer = (sessionId: string, body: SteerRequest) =>
  apiFetch<void>(`/api/sessions/${encodeURIComponent(sessionId)}/steer`, {
    method: "POST",
    body,
  });

/** Panel message to one subagent child (#272) — a user input on the child, whatever its state: steered mid-run, started on an idle child, resumed when the released session was revived (the child runs at its own Session's thinking level; pin it with patchSession). 404 subagent_gone when nothing can be revived, 409 subagent_busy when the child cannot take it right now. */
export const messageSubagent = (sessionId: string, childSessionId: string, text: string) =>
  apiFetch<SubagentMessageResponse>(
    `/api/sessions/${encodeURIComponent(sessionId)}/subagents/${encodeURIComponent(childSessionId)}/message`,
    { method: "POST", body: { text } },
  );

/** Panel stop for one subagent child (#272): aborts only its CURRENT run — the session survives for follow-ups (202 aborted; 204 when already idle/unknown). */
export const abortSubagent = (sessionId: string, childSessionId: string) =>
  apiFetch<void>(
    `/api/sessions/${encodeURIComponent(sessionId)}/subagents/${encodeURIComponent(childSessionId)}/abort`,
    { method: "POST", body: {} },
  );

/** Recall an undelivered steering message back to the composer (#287): returns its original content; 409 not_pending once it was delivered to the model. */
export const recallSteer = (sessionId: string, steerId: string) =>
  apiFetch<RecalledMessageResponse>(
    `/api/sessions/${encodeURIComponent(sessionId)}/steer/${encodeURIComponent(steerId)}`,
    { method: "DELETE" },
  );

/** Recall a queued follow-up task back to the composer (#287): returns its original content (+ queued thinking level); 409 follow_up_started once it already auto-started. */
export const recallFollowUp = (sessionId: string, followUpId: string) =>
  apiFetch<RecalledMessageResponse>(
    `/api/sessions/${encodeURIComponent(sessionId)}/follow-ups/${encodeURIComponent(followUpId)}`,
    { method: "DELETE" },
  );

export const postCompact = (sessionId: string) =>
  // Same shape as tasks: the response carries the actual current session_id (a new id after self-healing; the frontend updates its route accordingly).
  apiFetch<TaskCreateResponse>(`/api/sessions/${encodeURIComponent(sessionId)}/compact`, {
    method: "POST",
    body: {},
  });

/**
 * Switch this Session to another model in place. Two success shapes: **202** with a
 * {@link TaskCreateResponse} — the switch compacts on the current model first and streams like
 * `/compact`; the new context's `session_meta` follows a completed compaction, and it is what
 * says the Session switched — or **200** with a {@link SessionResponse} when the Session never
 * ran and switched inside the request. Only the latter carries `session`.
 */
export const switchSessionModel = (sessionId: string, body: SessionSwitchModelRequest) =>
  apiFetch<TaskCreateResponse | SessionResponse>(
    `/api/sessions/${encodeURIComponent(sessionId)}/switch-model`,
    { method: "POST", body },
  );

/**
 * Composition of the Session's current model context (the chat page's context-ring detail panel).
 * A snapshot read from the newest Trace shard on each call, not a live counter: the figures are
 * estimates whose value is the *shares* they give the measured occupancy.
 */
export const getSessionContext = (sessionId: string) =>
  apiFetch<SessionContextResponse>(`/api/sessions/${encodeURIComponent(sessionId)}/context`);

// Trace browsing & performance analysis -----------------------------------------------------------

export const getSessionTraces = (sessionId: string) =>
  apiFetch<SessionTracesResponse>(`/api/sessions/${encodeURIComponent(sessionId)}/traces`);

export const getTraceEvents = (sessionId: string, index: number, offset: number, limit: number) =>
  apiFetch<TraceEventsResponse>(`/api/sessions/${encodeURIComponent(sessionId)}/traces/${index}`, {
    query: { offset, limit },
  });

export const getTraceAnalysis = (sessionId: string, index: number) =>
  apiFetch<TraceAnalysisResponse>(
    `/api/sessions/${encodeURIComponent(sessionId)}/traces/${index}/analysis`,
  );

// Agent-level Trace details (read-only, independent of sessions-table registration): the Trace
// page's directory tree comes from an Agent-level scan (including subagent child Sessions and
// Sessions created by the CLI); details go through the Agent-level endpoint to avoid 404s for
// unregistered sessions.

export const getAgentTraceEvents = (
  projectId: string,
  agentId: string,
  sessionId: string,
  index: number,
  offset: number,
  limit: number,
) =>
  // These name a Session without SAYING so in a way the routing rule can read: the rule is
  // over the path, and only `/api/sessions/<id>/…` declares its Session. So each of the three
  // Trace calls passes the owner explicitly — sent to this server instead, they asked about a
  // Session that lives on a machine, which truthfully has no such Trace file here, and the
  // panel reported the Trace as gone while it sat on the machine intact.
  apiFetch<TraceEventsResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}` +
      `/traces/${encodeURIComponent(sessionId)}/${index}`,
    { query: { offset, limit }, server: machineForSession(sessionId) },
  );

export const getAgentTraceAnalysis = (
  projectId: string,
  agentId: string,
  sessionId: string,
  index: number,
) =>
  apiFetch<TraceAnalysisResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}` +
      `/traces/${encodeURIComponent(sessionId)}/${index}/analysis`,
    { server: machineForSession(sessionId) },
  );

/** Trace file download URL: the server sets Content-Disposition attachment, usable directly in <a download>. */
export const agentTraceDownloadUrl = (
  projectId: string,
  agentId: string,
  sessionId: string,
  index: number,
): string =>
  // A browser-followed URL, so the proxy prefix has to be IN it — there is no request here
  // for the routing rule to act on.
  apiUrl(
    `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}` +
      `/traces/${encodeURIComponent(sessionId)}/${index}/download`,
    machineForSession(sessionId),
  );

/**
 * Whole-Session export URL: every shard of the Session as one bundle file, for import on another
 * install. A plain browser-followed URL like the per-file download, so it is usable directly in
 * `<a download>`.
 */
export const agentTraceBundleExportUrl = (
  projectId: string,
  agentId: string,
  sessionId: string,
): string =>
  apiUrl(
    `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}` +
      `/traces/${encodeURIComponent(sessionId)}/export`,
    machineForSession(sessionId),
  );

/**
 * Imports a Trace file (owner only): a single `.jsonl` Trace, or a whole-Session `.json` bundle
 * exported from another install. The response says where it landed (sessionId / index / date /
 * shard count).
 */
export const importAgentTrace = (projectId: string, agentId: string, body: TraceImportRequest) =>
  apiFetch<TraceImportResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}/traces/import`,
    { method: "POST", body },
  );

// Usage statistics ----------------------------------------------------------------------

/**
 * The browser's own offset east of UTC, in minutes. The error table folds a day's repeats into
 * one row, and the day it folds by is the reader's rather than the server's.
 */
const viewerUtcOffsetMinutes = (): string => String(-new Date().getTimezoneOffset());

/**
 * One page of the cost center's error table (newest first). The dashboard response already
 * carries the first page; this is for paging back to earlier ones without refetching the
 * whole aggregate. Takes the dashboard's date/agent filter (and its trailing window, when one
 * is on) only — the model filter never applied to errors.
 */
export const getUsageErrors = (
  projectId: string,
  params: {
    offset: number;
    limit: number;
    from?: string;
    to?: string;
    /** The trailing window narrowing those dates; both or neither. */
    fromTs?: string;
    toTs?: string;
    agentId?: string;
    /** Narrow to one category; the cost-center badge asks for `unexpected` with `limit: 1`. */
    kind?: UsageErrorKind;
    /** Read the other side of the Project's ignore rules: the records a rule covers, which every other read leaves out. */
    ignored?: boolean;
  },
) =>
  apiFetch<UsageErrorsPage>(`/api/projects/${encodeURIComponent(projectId)}/usage/errors`, {
    query: {
      offset: String(params.offset),
      limit: String(params.limit),
      from: params.from,
      to: params.to,
      fromTs: params.fromTs,
      toTs: params.toTs,
      agentId: params.agentId,
      kind: params.kind,
      ignored: params.ignored === true ? "1" : undefined,
      utcOffsetMinutes: viewerUtcOffsetMinutes(),
    },
  });

/**
 * Empties the cost center's error table for the filter the panel is showing — the same dates,
 * trailing window, Agent and category the reads take, so what goes is what was on screen (for
 * an admin, the unattributed rows an admin's panel shows included). Owner only. Answers how
 * many rows were deleted.
 *
 * `until` is the newest record the confirmation's own read could see: the delete stops there,
 * so the number the dialog named is the number that goes even when a record lands in between.
 */
export const clearUsageErrors = (
  projectId: string,
  params: {
    from?: string;
    to?: string;
    fromTs?: string;
    toTs?: string;
    until?: string;
    agentId?: string;
    /** Narrow to one category; the panel sends whatever its table is showing. */
    kind?: UsageErrorKind;
    /** The ignore side the table is showing: `true` clears the rows a rule covers, absent the rows no rule covers. */
    ignored?: boolean;
  },
) =>
  apiFetch<UsageErrorsClearResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/usage/errors`,
    {
      method: "DELETE",
      query: {
        from: params.from,
        to: params.to,
        fromTs: params.fromTs,
        toTs: params.toTs,
        until: params.until,
        agentId: params.agentId,
        kind: params.kind,
        ignored: params.ignored === true ? "1" : undefined,
      },
    },
  );

/**
 * The Project's ignore rules — the error classes nothing in the panel's default view shows, each
 * with how many records it covers and when the newest of them was. Owner only: the panel reports
 * the count to everyone (the dashboard's `errors.ignored`), but managing the rules is the same
 * kind of act as clearing, so it draws the same line.
 */
export const getUsageErrorIgnores = (projectId: string) =>
  apiFetch<UsageErrorIgnores>(
    `/api/projects/${encodeURIComponent(projectId)}/usage/errors/ignores`,
  );

/**
 * Silences one class of errors. Nothing is deleted — the rule only decides which records the reads
 * select — so this is undoable, and the answer says how many records it covers in the range the
 * caller was looking at, which is what the caller reports having just hidden. A class the Project
 * already ignores is a 409.
 *
 * The range rides along because the number is scoped to it: the same range the table on screen
 * was read with, so "隐藏 349 条" names the rows that just left it.
 */
export const ignoreUsageErrors = (
  projectId: string,
  body: UsageErrorIgnoreWrite,
  params: { from?: string; to?: string; fromTs?: string; toTs?: string; agentId?: string } = {},
) =>
  apiFetch<UsageErrorIgnoreAdded>(
    `/api/projects/${encodeURIComponent(projectId)}/usage/errors/ignores`,
    {
      method: "POST",
      body,
      query: {
        from: params.from,
        to: params.to,
        fromTs: params.fromTs,
        toTs: params.toTs,
        agentId: params.agentId,
      },
    },
  );

/** Removes one rule, re-exposing every record it covered — the whole of the undo, since nothing was deleted. */
export const unignoreUsageErrors = (projectId: string, id: number) =>
  apiFetch<{ removed: boolean }>(
    `/api/projects/${encodeURIComponent(projectId)}/usage/errors/ignores/${String(id)}`,
    { method: "DELETE" },
  );

/**
 * Lifetime Token total per Model, unfiltered. The models page shows each card what it has
 * spent; it is a separate request from the model list so a stats failure costs the figure and
 * not the page.
 */
export const getUsageModelTotals = (projectId: string) =>
  apiFetch<UsageModelTotals>(`/api/projects/${encodeURIComponent(projectId)}/usage/model-totals`);

/**
 * Usage by calendar day, each day split by Session — the account menu's run record. One request
 * for the whole list: the Sessions are named server-side (titles included), so the dialog needs
 * no follow-up lookup for a conversation the sidebar has not loaded.
 */
export const getUsageSessionDays = (projectId: string, days: number) =>
  apiFetch<UsageSessionDays>(`/api/projects/${encodeURIComponent(projectId)}/usage/session-days`, {
    query: { days },
  });

/**
 * The Sessions this server is running right now in this Project. One project-level read rather
 * than a per-Agent list filter: the account menu asks "what is running anywhere", and the
 * sidebar's paged lists cannot answer it for a group nobody expanded.
 */
export const getRunningSessions = (projectId: string) =>
  apiFetch<RunningSessionsResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/sessions/running`,
  );

export const getUsage = (
  projectId: string,
  params: {
    from?: string;
    to?: string;
    /** Trailing-window bounds (ISO timestamps, together or not at all): refine the range down to instants; required for minute granularity. */
    fromTs?: string;
    toTs?: string;
    groupBy: UsageGroupBy;
    /** Time-series precision for the response's `series`; the server defaults to day. */
    granularity?: UsageGranularity;
    agentId?: string;
    /** Model filter is always a whole pair — both fields or neither; a model is never referenced by id alone. */
    provider?: string;
    modelId?: string;
  },
) =>
  apiFetch<UsageResponse>(`/api/projects/${encodeURIComponent(projectId)}/usage`, {
    query: {
      from: params.from,
      to: params.to,
      fromTs: params.fromTs,
      toTs: params.toTs,
      groupBy: params.groupBy,
      granularity: params.granularity,
      agentId: params.agentId,
      provider: params.provider,
      modelId: params.modelId,
      utcOffsetMinutes: viewerUtcOffsetMinutes(),
    },
  });

// Agent deletion & Workspace files --------------------------------------------------

/**
 * Deletes an Agent. The answer carries the background removal of its files to follow; a server
 * from before that removal moved to the background answers 204 once everything is gone, which
 * reads as undefined here.
 */
export const deleteAgent = (projectId: string, agentId: string) =>
  apiFetch<AgentDeleteResponse | undefined>(
    `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}`,
    { method: "DELETE" },
  );

/** Where a delete's background removal stands (404 `agent_deletion_not_found` once it is unknown). */
export const getAgentDeletion = (projectId: string, deletionId: string) =>
  apiFetch<AgentDeletionResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/agent-deletions/${encodeURIComponent(deletionId)}`,
  );

export const listWorkspaceFiles = (sessionId: string, path: string) =>
  apiFetch<WorkspaceFilesResponse>(`/api/sessions/${sessionId}/files`, { query: { path } });

/** File content URL (inline preview / download=1 triggers download; usable directly in <a>/<img>/fetch). */
/**
 * File content URL (inline preview / download=1 triggers download; usable directly in
 * <a>/<img>/<iframe>/fetch).
 *
 * Routed like every other Session call, by hand: this is a URL, not a call, so it never
 * passes through the fetch wrapper that applies the rule (lib/session-machines.ts). Left
 * bare, every preview, image, PDF and download of a Session that lives on a machine asked
 * THIS server for a Session it does not have — and the workspace browser reports the
 * resulting failure as "preview not supported for this type", since a file it cannot read
 * is indistinguishable from one it cannot render.
 */
export const workspaceFileUrl = (sessionId: string, path: string, download = false): string =>
  apiUrl(
    `/api/sessions/${sessionId}/files/content?path=${encodeURIComponent(path)}${download ? "&download=1" : ""}`,
    machineForSession(sessionId),
  );

/**
 * A .docx's text as Markdown, extracted by the server (see the route's own comment): the Files
 * panel renders it through its Markdown pipeline, so a Word document previews in any client —
 * no office suite, no download.
 */
export const workspaceFileTextUrl = (sessionId: string, path: string): string =>
  apiUrl(
    `/api/sessions/${sessionId}/files/preview-text?path=${encodeURIComponent(path)}`,
    machineForSession(sessionId),
  );

/**
 * "Open in a new tab" for a Workspace html file: an App-origin link that mints a signed
 * token and 302s to the separate preview origin, where the page gets a real origin with
 * working storage, cookies and third-party embeds.
 *
 * A link (not a fetch + `window.open`) on purpose — opening a tab after an await trips
 * popup blockers, and a script-opened window keeps an `opener` handle back to the App,
 * which is precisely the reference the separate origin exists to deny. Use it with
 * `rel="noopener noreferrer"`.
 *
 * Falls back server-side to the sandboxed same-origin preview when the deployment has no
 * usable preview origin; `previewIsolated` from /api/me says so in advance.
 */
export const workspaceFilePreviewUrl = (sessionId: string, path: string): string =>
  `/api/sessions/${sessionId}/files/preview-redirect?path=${encodeURIComponent(path)}`;

/**
 * Opens the file's directory in the machine's own file manager, selecting the file where the
 * platform allows. Only the desktop shell's own window may ask: the server answers 404 when it
 * was not spawned by a shell and 403 `desktop_shell_only` for a browser session beside one,
 * since it cannot tell that browser from a remote one (see lib/account-menu.ts).
 */
export const revealWorkspaceFile = (sessionId: string, path: string) =>
  apiFetch<void>(`/api/sessions/${sessionId}/files/reveal`, { method: "POST", query: { path } });

/**
 * Writes a Workspace file whole. `ifVersion` is the marker a previous read returned in its
 * `ETag`: pass it and the write is refused with 409 `file_changed` unless the file is still
 * the one that was read (the editor's save); leave it out and the write creates or replaces
 * unconditionally (uploads, which read no version).
 *
 * Resolves to the version the write produced — the marker the next save of the same file
 * carries — or null from a server that does not say.
 */
export const uploadWorkspaceFile = (
  sessionId: string,
  path: string,
  dataBase64: string,
  ifVersion?: string,
): Promise<string | null> =>
  apiFetchWithMeta<void>(`/api/sessions/${sessionId}/files/content`, {
    method: "PUT",
    body: { dataBase64, ifVersion } satisfies FilesWriteRequest,
    query: { path },
  }).then((res) => res.etag);

/**
 * Creates one empty text file or one folder. Missing parent directories are made; anything
 * already at the path is refused with 409 `target_exists` and nothing is written.
 */
export const createWorkspaceEntry = (sessionId: string, body: FilesCreateRequest) =>
  apiFetch<void>(`/api/sessions/${sessionId}/files/create`, { method: "POST", body });

/**
 * Moves or renames a Workspace file or folder. `ifVersion` (see {@link uploadWorkspaceFile})
 * guards a file SOURCE: pass it and the move is refused with 409 `file_changed` unless the file
 * is still the one that was read. A folder moves whole and takes none. The destination has no
 * such marker — nothing read it — so an occupied destination is 409 `target_exists` rather than
 * an overwrite, and a folder cannot move into itself. `to`'s parent directory is created when it
 * is missing.
 */
export const moveWorkspaceFile = (sessionId: string, body: FilesMoveRequest) =>
  apiFetch<void>(`/api/sessions/${sessionId}/files/move`, { method: "POST", body });

/**
 * Deletes a Workspace file. `ifVersion` is the same marker a write carries: with it, a file
 * the Agent rewrote since the panel read it is refused with 409 `file_changed` instead of
 * being removed. Files only — a directory is a 400.
 */
export const deleteWorkspaceFile = (sessionId: string, path: string, ifVersion?: string) =>
  apiFetch<void>(`/api/sessions/${sessionId}/files/content`, {
    method: "DELETE",
    query: { path, ifVersion },
  });

/**
 * Searches the whole Workspace by entry name (case-insensitive substring), breadth-first from
 * the root so the shallowest matches come first. `truncated` says a cap stopped the walk: the
 * hits are then the most relevant ones rather than all of them. An empty query is a 400 — the
 * caller decides what an empty search box shows, and it is never "every file".
 */
export const searchWorkspaceFiles = (sessionId: string, q: string) =>
  apiFetch<WorkspaceSearchResponse>(`/api/sessions/${sessionId}/files/search`, { query: { q } });

// Workspace files by directory ----------------------------------------------------------------

/**
 * A directory the Files panel addresses by its absolute path rather than through a Session: the
 * new-chat draft's chosen folder and a sidebar Workspace group, where no Session exists yet.
 * Access is the Project's; the directory must exist. `machineId` is the machine it is on (null:
 * this server) — a path names a directory only together with it.
 */
export interface WorkspaceDir {
  projectId: string;
  workspace: string;
  machineId: string | null;
}

const workspaceDirBase = (dir: WorkspaceDir): string =>
  `/api/projects/${encodeURIComponent(dir.projectId)}/workspace-files`;

export const listWorkspaceDirFiles = (dir: WorkspaceDir, path: string) =>
  apiFetch<WorkspaceFilesResponse>(workspaceDirBase(dir), {
    query: { workspace: dir.workspace, path },
    server: dir.machineId,
  });

/** File content URL, as {@link workspaceFileUrl}; the machine's proxy prefix rides in the URL itself. */
export const workspaceDirFileUrl = (dir: WorkspaceDir, path: string, download = false): string =>
  apiUrl(
    `${workspaceDirBase(dir)}/content?workspace=${encodeURIComponent(dir.workspace)}&path=${encodeURIComponent(path)}${download ? "&download=1" : ""}`,
    dir.machineId,
  );

/**
 * "Open in a new tab" for an HTML file of a directory: the same-origin sandboxed preview, since
 * the separate preview origin's tokens name a Session.
 */
export const workspaceDirPreviewUrl = (dir: WorkspaceDir, path: string): string =>
  apiUrl(
    `${workspaceDirBase(dir)}/content?workspace=${encodeURIComponent(dir.workspace)}&path=${encodeURIComponent(path)}&preview=1`,
    dir.machineId,
  );

/** A .docx's text as Markdown for a directory's Workspace, as {@link workspaceFileTextUrl}. */
export const workspaceDirFileTextUrl = (dir: WorkspaceDir, path: string): string =>
  apiUrl(
    `${workspaceDirBase(dir)}/preview-text?workspace=${encodeURIComponent(dir.workspace)}&path=${encodeURIComponent(path)}`,
    dir.machineId,
  );

/** As {@link uploadWorkspaceFile}: resolves to the version written, or null when the server does not say. */
export const writeWorkspaceDirFile = (
  dir: WorkspaceDir,
  path: string,
  dataBase64: string,
  ifVersion?: string,
): Promise<string | null> =>
  apiFetchWithMeta<void>(`${workspaceDirBase(dir)}/content`, {
    method: "PUT",
    body: { dataBase64, ifVersion } satisfies FilesWriteRequest,
    query: { workspace: dir.workspace, path },
    server: dir.machineId,
  }).then((res) => res.etag);

export const createWorkspaceDirEntry = (dir: WorkspaceDir, body: FilesCreateRequest) =>
  apiFetch<void>(`${workspaceDirBase(dir)}/create`, {
    method: "POST",
    body,
    query: { workspace: dir.workspace },
    server: dir.machineId,
  });

export const moveWorkspaceDirFile = (dir: WorkspaceDir, body: FilesMoveRequest) =>
  apiFetch<void>(`${workspaceDirBase(dir)}/move`, {
    method: "POST",
    body,
    query: { workspace: dir.workspace },
    server: dir.machineId,
  });

export const deleteWorkspaceDirFile = (dir: WorkspaceDir, path: string, ifVersion?: string) =>
  apiFetch<void>(`${workspaceDirBase(dir)}/content`, {
    method: "DELETE",
    query: { workspace: dir.workspace, path, ifVersion },
    server: dir.machineId,
  });

export const searchWorkspaceDirFiles = (dir: WorkspaceDir, q: string) =>
  apiFetch<WorkspaceSearchResponse>(`${workspaceDirBase(dir)}/search`, {
    query: { workspace: dir.workspace, q },
    server: dir.machineId,
  });

export const revealWorkspaceDirFile = (dir: WorkspaceDir, path: string) =>
  apiFetch<void>(`${workspaceDirBase(dir)}/reveal`, {
    method: "POST",
    query: { workspace: dir.workspace, path },
    server: dir.machineId,
  });

/** Batch file-existence check (message file cards): both out-of-bounds and missing paths simply don't appear in `existing`; always returns 200. */
export const statSessionFiles = (sessionId: string, paths: string[]) =>
  apiFetch<FilesStatResponse>(`/api/sessions/${sessionId}/files/stat`, {
    method: "POST",
    body: { paths } satisfies FilesStatRequest,
  });

// Scheduled tasks ----------------------------------------------------------------------

export const listSchedules = (projectId: string, agentId: string) =>
  apiFetch<SchedulesResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}/schedules`,
  );

/** Every agent's scheduled tasks in the Project, each stamped with its agent: what the session list's marks read. */
export const listProjectSchedules = (projectId: string) =>
  apiFetch<ProjectSchedulesResponse>(`/api/projects/${encodeURIComponent(projectId)}/schedules`);

/** Every Project the account may reach, each with its own tasks: the page's cross-Project overview, in one read-only request. */
export const listAllSchedules = () => apiFetch<AllProjectSchedulesResponse>("/api/schedules");

export const createSchedule = (
  projectId: string,
  agentId: string,
  body: ScheduleUpsertRequest & { name: string },
) =>
  apiFetch<ScheduleItem>(
    `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}/schedules`,
    { method: "POST", body },
  );

export const updateSchedule = (
  projectId: string,
  agentId: string,
  name: string,
  body: ScheduleUpsertRequest,
) =>
  apiFetch<ScheduleItem>(
    `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}` +
      `/schedules/${encodeURIComponent(name)}`,
    { method: "PUT", body },
  );

export const deleteSchedule = (projectId: string, agentId: string, name: string) =>
  apiFetch<void>(
    `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}` +
      `/schedules/${encodeURIComponent(name)}`,
    { method: "DELETE" },
  );

// Plugin library, and an Agent's installed skills and hook packages ----------------------------

/** Plugin library (available to any logged-in user): groups, each plugin's manifest and the metadata of its skills — never SKILL.md bodies or hook scripts. */
export const getPluginLibrary = () => apiFetch<PluginLibraryResponse>("/api/plugins");

/** Everything one library plugin ships as text keyed by path (skills' files, hook scripts), for the plugin detail view's file browser. */
export const getPluginFiles = (plugin: string) =>
  apiFetch<PluginFilesResponse>(`/api/plugins/${encodeURIComponent(plugin)}/files`);

/**
 * The user plugin directory: its absolute path and the names of the plugins currently inside
 * it — where an import lands and what a delete removes from, and therefore the one line the
 * page shows about it. Answers whether or not the directory exists yet.
 */
export const getPluginDirectory = () => apiFetch<PluginDirectoryResponse>("/api/plugins/directory");

/**
 * Imports one plugin from an uploaded zip (base64), admin-only like every write into the
 * directory. The archive carries `plugin.json` plus its `skills/`, `hooks/` and `icon.svg`;
 * 409 `plugin_exists` when a user plugin of that name is already installed and `overwrite` is
 * not set. 201 answers with the plugin as the library now lists it, plus where it landed.
 */
export const importPluginArchive = (body: PluginUploadRequest) =>
  apiFetch<PluginImportResponse>("/api/plugins/upload", { method: "POST", body });

/**
 * The same import, fetched server-side from an address or an npm package: a zip or `.tgz` link, a
 * GitHub repository (`https://github.com/<owner>/<repo>`, default branch), a GitHub tree URL
 * (`…/tree/<ref>/<subdir>`, whose subdirectory is the plugin root), or a package name
 * (`@scope/name[@version]`, `npm:@scope/name`, an npmjs.com package page) — installed under the
 * package's own name, without its scope. Same 409 `plugin_exists` as the upload, the same
 * admin-only gate, and its own codes for what npm can answer (404 `npm_package_not_found`,
 * 404 `npm_version_not_found`, 400 `npm_registry_failed`, 400 `integrity_failed`).
 */
export const importPluginFromUrl = (body: PluginDownloadRequest) =>
  apiFetch<PluginImportResponse>("/api/plugins/download", { method: "POST", body });

/** Deletes one user plugin from the library and from disk (admin-only); 409 `plugin_builtin` for a built-in name, 404 `unknown_plugin` for one the library does not hold. */
export const deletePlugin = (plugin: string) =>
  apiFetch<void>(`/api/plugins/${encodeURIComponent(plugin)}`, { method: "DELETE" });

/** Zip download URL for one library plugin (server sets Content-Disposition attachment): the card's export, which round-trips through importPluginArchive. */
export const pluginArchiveUrl = (plugin: string): string =>
  `/api/plugins/${encodeURIComponent(plugin)}/archive`;

/**
 * Installs whole library plugins — each one's skills and hook package; an already-installed
 * plugin is overwritten with the library content (i.e. updated). 201 returns the Agent's
 * refreshed installed lists.
 */
export const installAgentPlugins = (projectId: string, agentId: string, names: string[]) =>
  apiFetch<AgentPluginsInstallResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}/plugins`,
    { method: "POST", body: { names } satisfies PluginInstallRequest },
  );

/** Plugin index (available to any logged-in user): the merged index of every configured registry. */
export const getPluginIndex = () => apiFetch<PluginIndexResponse>("/api/plugins/registry");

export const getPluginReadme = (name: string) =>
  apiFetch<PluginReadmeResponse>(`/api/plugins/registry/readme?name=${encodeURIComponent(name)}`);

export const getAgentSkills = (projectId: string, agentId: string) =>
  apiFetch<AgentSkillsResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}/skills`,
  );

export const getAgentHooks = (projectId: string, agentId: string) =>
  apiFetch<AgentHooksResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}/hooks`,
  );

/** Uninstalls one hook package (deletes agent_state/hooks/<name>/ whole); 204, 404 not_found when it is not installed. */
export const uninstallAgentHook = (projectId: string, agentId: string, name: string) =>
  apiFetch<void>(
    `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}` +
      `/hooks/${encodeURIComponent(name)}`,
    { method: "DELETE" },
  );

/** Installs one hook package from an uploaded zip (base64); 409 hook_exists unless overwrite; 201 returns the latest installed list. */
export const installAgentHookArchive = (
  projectId: string,
  agentId: string,
  body: HookArchiveInstallRequest,
) =>
  apiFetch<AgentHooksResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}` +
      `/hooks/archive`,
    { method: "POST", body },
  );

/** Zip download URL for one installed hook package (server sets Content-Disposition attachment); the export round-trips through installAgentHookArchive. */
export const agentHookArchiveUrl = (projectId: string, agentId: string, name: string): string =>
  `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}` +
  `/hooks/${encodeURIComponent(name)}/archive`;

/** Installs one skill from an uploaded zip (base64); 409 skill_exists unless overwrite; 201 returns the latest installed list. */
export const installAgentSkillArchive = (
  projectId: string,
  agentId: string,
  body: SkillArchiveInstallRequest,
) =>
  apiFetch<AgentSkillsResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}` +
      `/skills/archive`,
    { method: "POST", body },
  );

/** Zip download URL for one installed skill (server sets Content-Disposition attachment); the export round-trips through installAgentSkillArchive. */
export const agentSkillArchiveUrl = (projectId: string, agentId: string, name: string): string =>
  `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}` +
  `/skills/${encodeURIComponent(name)}/archive`;

export const removeAgentSkill = (projectId: string, agentId: string, name: string) =>
  apiFetch<void>(
    `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}` +
      `/skills/${encodeURIComponent(name)}`,
    { method: "DELETE" },
  );

// Benchmarks (scores, manual creation and deletion) -------------------------------------------
// Benchmarks sit at the Project level, beside agents rather than under one: a Benchmark can
// evaluate many agents, so no agent id travels in these paths.

/**
 * A Project's Benchmarks as ONE server holds them. A `benchmarks/` directory is written on
 * whichever machine created or evaluated the Benchmark, so the Evaluation Center asks this
 * server and each machine it holds, then merges the answers (lib/benchmark-merge.ts). The path
 * is not Session-scoped, so nothing about it can be routed from an id — the machine is passed.
 */
export const listBenchmarks = (projectId: string, machineId?: string | null) =>
  apiFetch<BenchmarksResponse>(`/api/projects/${encodeURIComponent(projectId)}/benchmarks`, {
    server: machineId ?? null,
  });

export const listBenchmarkCases = (
  projectId: string,
  benchmarkId: string,
  machineId?: string | null,
) =>
  apiFetch<BenchmarkCasesResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/benchmarks/${encodeURIComponent(benchmarkId)}` +
      `/cases`,
    { server: machineId ?? null },
  );

/** Creates a Benchmark by hand (owner only); the server writes the on-disk layout. 409 `benchmark_exists` on a taken id. */
export const createBenchmark = (projectId: string, body: BenchmarkCreateRequest) =>
  apiFetch<BenchmarkCreateResponse>(`/api/projects/${encodeURIComponent(projectId)}/benchmarks`, {
    method: "POST",
    body,
  });

/** Removes a Benchmark directory whole — cases, config and scoreboard (owner only; 204). */
export const deleteBenchmark = (projectId: string, benchmarkId: string) =>
  apiFetch<void>(
    `/api/projects/${encodeURIComponent(projectId)}/benchmarks/${encodeURIComponent(benchmarkId)}`,
    { method: "DELETE" },
  );

const benchmarkCaseFilesPath = (
  projectId: string,
  benchmarkId: string,
  caseId: string,
  material: CaseMaterial,
) =>
  `/api/projects/${encodeURIComponent(projectId)}/benchmarks/${encodeURIComponent(benchmarkId)}` +
  `/cases/${encodeURIComponent(caseId)}` +
  `${material === "rubric" ? "/rubric" : ""}/files`;

export const listBenchmarkCaseFiles = (
  projectId: string,
  benchmarkId: string,
  caseId: string,
  path: string,
  material: CaseMaterial,
  machineId?: string | null,
) =>
  apiFetch<WorkspaceFilesResponse>(
    benchmarkCaseFilesPath(projectId, benchmarkId, caseId, material),
    { query: { path }, server: machineId ?? null },
  );

export const benchmarkCaseFileUrl = (
  projectId: string,
  benchmarkId: string,
  caseId: string,
  path: string,
  material: CaseMaterial,
  options?: { download?: boolean; preview?: boolean; machineId?: string | null },
): string => {
  const base = `${benchmarkCaseFilesPath(
    projectId,
    benchmarkId,
    caseId,
    material,
  )}/content?path=${encodeURIComponent(path)}`;
  return (
    // A browser-followed URL (an <img> src, a download link), so the proxy prefix has to be
    // IN it — there is no request here for a routing rule to act on.
    apiUrl(base, options?.machineId ?? null) +
    (options?.download ? "&download=1" : "") +
    (options?.preview && !options.download ? "&preview=1" : "")
  );
};

// Agent State snapshot export / import ------------------------------------------------------

/** Snapshot bundle (tar.gz) download URL: the server sets Content-Disposition attachment, usable directly in <a download>. */
export const agentExportUrl = (projectId: string, agentId: string): string =>
  `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}/export`;

export const importAgent = (projectId: string, agentId: string, body: AgentImportRequest) =>
  apiFetch<AgentImportResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}/import`,
    { method: "POST", body },
  );

// Machines (admin only) ----------------------------------------------------------------

/**
 * The server's ssh hosts, the version it would install, and the running or last install
 * job. The Machines page polls this while a job runs — the progress lines live on the job,
 * not on the event channel, because they belong to the one page that is waiting for them.
 */
export const getMachines = (projectId: string) =>
  apiFetch<MachinesResponse>(`/api/projects/${encodeURIComponent(projectId)}/machines`);

/**
 * Re-probes the installed machines' servers (one ssh round trip each, server-side) and
 * answers the refreshed list. A POST because it spends those round trips — a GET that
 * spawns processes is one a prefetch or a proxy may fire on its own.
 */
export const probeMachines = (projectId: string) =>
  apiFetch<MachinesResponse>(`/api/projects/${encodeURIComponent(projectId)}/machines/probe`, {
    method: "POST",
    body: {},
  });

/**
 * Starts an install on a machine and gives it to this Project; answers the list with the
 * running job. `replaceProgram` answers a job that came back asking for it — installing the
 * program over there even though its version already matches, and restarting it.
 */
/**
 * Brings machines into use — install or update if needed, start, connect, sync — as one
 * queued batch (202). `refused` names the ones that could be turned down without any ssh.
 * `replaceProgram` answers a job that came back asking for it.
 */
export const useMachines = (projectId: string, machineIds: string[], replaceProgram = false) =>
  apiFetch<MachinesUseResponse>(`/api/projects/${encodeURIComponent(projectId)}/machines/use`, {
    method: "POST",
    body: replaceProgram
      ? { machines: machineIds, replaceProgram: true }
      : { machines: machineIds },
  });

/** Appends a host block to this server's ~/.ssh/config; answers the machines list, which now names it (201). */
export const addSshHost = (projectId: string, host: SshHostRequest) =>
  apiFetch<MachinesResponse>(`/api/projects/${encodeURIComponent(projectId)}/machines/ssh-hosts`, {
    method: "POST",
    body: host,
  });

/** A host's ssh block read back, and whether this app wrote it (only then may it be rewritten). */
export const getSshHost = (projectId: string, alias: string) =>
  apiFetch<SshHostResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/machines/ssh-hosts/${encodeURIComponent(alias)}`,
  );

/** Rewrites a block this app wrote; answers the machines list. */
export const updateSshHost = (
  projectId: string,
  alias: string,
  host: Omit<SshHostRequest, "alias">,
) =>
  apiFetch<MachinesResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/machines/ssh-hosts/${encodeURIComponent(alias)}`,
    { method: "PUT", body: host },
  );

/** Lets machines go: connections dropped, Project membership released; the install stays. */
export const stopUsingMachines = (projectId: string, machineIds: string[]) =>
  apiFetch<MachinesResponse>(`/api/projects/${encodeURIComponent(projectId)}/machines/stop-using`, {
    method: "POST",
    body: { machines: machineIds },
  });

export const installOnMachine = (projectId: string, machineId: string, replaceProgram = false) =>
  apiFetch<MachinesResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/machines/${encodeURIComponent(machineId)}/install`,
    { method: "POST", body: replaceProgram ? { replaceProgram: true } : {} },
  );

/** Brings that machine's server up and holds a tunnel to it (202, long-running). */
export const connectMachine = (projectId: string, machineId: string) =>
  apiFetch<MachinesResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/machines/${encodeURIComponent(machineId)}/connect`,
    { method: "POST", body: {} },
  );

/** Drops a machine from this Project. The install stays — another Project may be using it. */
export const releaseMachine = (projectId: string, machineId: string) =>
  apiFetch<MachinesResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/machines/${encodeURIComponent(machineId)}/release`,
    { method: "POST", body: {} },
  );

/** Drops the tunnel; the remote server keeps running. */
/** Restarts that machine's server so what runs there matches what is on its disk. */
export const restartMachine = (projectId: string, machineId: string) =>
  apiFetch<MachinesResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/machines/${encodeURIComponent(machineId)}/restart`,
    { method: "POST", body: {} },
  );

export const disconnectMachine = (projectId: string, machineId: string) =>
  apiFetch<MachinesResponse>(
    `/api/projects/${encodeURIComponent(projectId)}/machines/${encodeURIComponent(machineId)}/disconnect`,
    { method: "POST", body: {} },
  );

// Version & self-update ----------------------------------------------------------------

export const getVersion = () => apiFetch<VersionResponse>("/api/version");
/** The harness versions this data root has committed, newest first, and the current one. */
export const getVersionHistory = () => apiFetch<VersionHistoryResponse>("/api/version/history");
/** Push a kept version back (admin); the swap follows the 202. */
export const rollbackVersion = (id: string) =>
  apiFetch<VersionRollbackResponse>("/api/version/history/rollback", {
    method: "POST",
    body: { id },
  });
/** A recorded interface table by hash — the module tree a version was built from. */
export const getVersionIfacesTable = (hash: string) =>
  apiFetch<unknown>(`/api/version/history/ifaces/${encodeURIComponent(hash)}`);
/** What changed between two stored interface tables; either hash may be "none". */
export const getVersionHistoryDiff = (from: string, to: string) =>
  apiFetch<VersionHistoryDiffResponse>(
    `/api/version/history/diff?from=${encodeURIComponent(from)}&to=${encodeURIComponent(to)}`,
  );

/** `force` (the manual "check for updates" action) bypasses the server's TTL cache. */
export const checkUpdate = (force = false) =>
  apiFetch<UpdateCheckResponse>(`/api/version/update-check${force ? "?force=1" : ""}`);

/** Admin only: the self-update job's status — polled while it runs. */
export const getUpdateJob = () => apiFetch<UpdateJobStatus>("/api/version/update");

/** Admin only: starts the self-update job (`penguin update` on the server host, in the background) and answers with its status. */
export const startUpdateJob = () =>
  apiFetch<UpdateJobStatus>("/api/version/update", { method: "POST", body: {} });

/** Admin only: asks the supervised server process to restart into the installed release. */
export const restartServer = () =>
  apiFetch<RestartResponse>("/api/version/restart", { method: "POST", body: {} });

// Feedback (the sidebar's entry) --------------------------------------------------------

/** Whether this install has a feedback backend. The entry renders only where it does. */
export const getFeedbackConfig = () => apiFetch<FeedbackConfigResponse>("/api/feedback");

/** Files one submission; `id` names the item the backend created, when it reported one. */
export const sendFeedback = (body: FeedbackRequest) =>
  apiFetch<FeedbackResponse>("/api/feedback", { method: "POST", body });

// Desktop client update (desktop-shell sessions only) ----------------------------------

export const getDesktopUpdate = () => apiFetch<DesktopUpdateStatusResponse>("/api/desktop/update");

export const desktopUpdateCheck = () =>
  apiFetch<void>("/api/desktop/update/check", { method: "POST", body: {} });

export const desktopUpdateDownload = () =>
  apiFetch<void>("/api/desktop/update/download", { method: "POST", body: {} });

export const desktopUpdateInstall = () =>
  apiFetch<void>("/api/desktop/update/install", { method: "POST", body: {} });

// ---------------------------------------------------------------------------
// Company mode: organizations (one wrapper per route of routes/organizations.ts)
// ---------------------------------------------------------------------------

/** Base path of one Project's organizations, or of one organization when `orgId` is given. */
const orgBase = (projectId: string, orgId?: string) =>
  `/api/projects/${encodeURIComponent(projectId)}/organizations${
    orgId === undefined ? "" : `/${encodeURIComponent(orgId)}`
  }`;

export const listOrganizations = (projectId: string) =>
  apiFetch<OrganizationsResponse>(orgBase(projectId));

export const createOrganization = (projectId: string, body: OrganizationCreateRequest) =>
  apiFetch<OrganizationDetail>(orgBase(projectId), { method: "POST", body });

/**
 * A semantic id for a display name — a Project's, an Agent's, a Benchmark's, an organization's or
 * a channel's, by `kind` — from the default model of the Project in the path, with an ASCII
 * fallback and a dated placeholder behind it.
 */
export const suggestSemanticId = (projectId: string, body: SemanticIdSuggestRequest) =>
  apiFetch<SemanticIdSuggestResponse>(`/api/projects/${encodeURIComponent(projectId)}/suggest-id`, {
    method: "POST",
    body,
  });

export const getOrganization = (projectId: string, orgId: string) =>
  apiFetch<OrganizationDetail>(orgBase(projectId, orgId));

export const patchOrganization = (
  projectId: string,
  orgId: string,
  body: OrganizationPatchRequest,
) => apiFetch<OrganizationSettings>(orgBase(projectId, orgId), { method: "PATCH", body });

/**
 * Owner only. The organization itself goes — to the Project's trash, restorable by hand; its
 * employees' Agents and its desk and ticket Sessions are left as they are.
 */
export const deleteOrganization = (projectId: string, orgId: string) =>
  apiFetch<void>(orgBase(projectId, orgId), { method: "DELETE" });

export const getOrgChart = (projectId: string, orgId: string) =>
  apiFetch<OrgChartResponse>(`${orgBase(projectId, orgId)}/chart`);

export const hireOrgEmployee = (projectId: string, orgId: string, body: OrgHireRequest) =>
  apiFetch<OrgEmployeeItem>(`${orgBase(projectId, orgId)}/employees`, { method: "POST", body });

export const patchOrgEmployee = (
  projectId: string,
  orgId: string,
  agentId: string,
  body: OrgEmployeePatchRequest,
) =>
  apiFetch<OrgEmployeeItem>(
    `${orgBase(projectId, orgId)}/employees/${encodeURIComponent(agentId)}`,
    { method: "PATCH", body },
  );

export const leaveOrganization = (projectId: string, orgId: string, agentId: string) =>
  apiFetch<void>(`${orgBase(projectId, orgId)}/employees/${encodeURIComponent(agentId)}`, {
    method: "DELETE",
  });

/** The employee's desk session, opened on demand (GET creates it when there is none). */
export const getOrgDesk = (projectId: string, orgId: string, agentId: string) =>
  apiFetch<OrgDeskResponse>(
    `${orgBase(projectId, orgId)}/employees/${encodeURIComponent(agentId)}/desk`,
  );

/** A fresh desk session for the employee (the old one stays as an ordinary Session). */
export const renewOrgDesk = (projectId: string, orgId: string, agentId: string) =>
  apiFetch<OrgDeskResponse>(
    `${orgBase(projectId, orgId)}/employees/${encodeURIComponent(agentId)}/desk`,
    { method: "POST", body: {} },
  );

export const getOrgHandbook = (projectId: string, orgId: string) =>
  apiFetch<OrgHandbookResponse>(`${orgBase(projectId, orgId)}/handbook`);

export const putOrgHandbook = (projectId: string, orgId: string, content: string) =>
  apiFetch<OrgHandbookResponse>(`${orgBase(projectId, orgId)}/handbook`, {
    method: "PUT",
    body: { content },
  });

/** A handbook file's URL: the path is relative to `handbook/`, so each segment is encoded and the `/` between them kept. */
const handbookFileUrl = (projectId: string, orgId: string, path: string) =>
  `${orgBase(projectId, orgId)}/handbook/files/${path.split("/").map(encodeURIComponent).join("/")}`;

export const listOrgHandbookFiles = (projectId: string, orgId: string) =>
  apiFetch<OrgHandbookFilesResponse>(`${orgBase(projectId, orgId)}/handbook/files`);

export const getOrgHandbookFile = (projectId: string, orgId: string, path: string) =>
  apiFetch<OrgHandbookFileResponse>(handbookFileUrl(projectId, orgId, path));

export const putOrgHandbookFile = (
  projectId: string,
  orgId: string,
  path: string,
  content: string,
) =>
  apiFetch<OrgHandbookFileResponse>(handbookFileUrl(projectId, orgId, path), {
    method: "PUT",
    body: { content },
  });

export const deleteOrgHandbookFile = (projectId: string, orgId: string, path: string) =>
  apiFetch<void>(handbookFileUrl(projectId, orgId, path), { method: "DELETE" });

export const listOrgCalendar = (projectId: string, orgId: string) =>
  apiFetch<OrgCalendarResponse>(`${orgBase(projectId, orgId)}/calendar`);

export const createOrgCalendarEvent = (
  projectId: string,
  orgId: string,
  body: OrgCalendarUpsertRequest & { agentId: string; name: string },
) =>
  apiFetch<OrgCalendarWriteResponse>(`${orgBase(projectId, orgId)}/calendar`, {
    method: "POST",
    body,
  });

export const updateOrgCalendarEvent = (
  projectId: string,
  orgId: string,
  agentId: string,
  name: string,
  body: OrgCalendarUpsertRequest,
) =>
  apiFetch<OrgCalendarWriteResponse>(
    `${orgBase(projectId, orgId)}/calendar/${encodeURIComponent(agentId)}/${encodeURIComponent(name)}`,
    { method: "PUT", body },
  );

export const deleteOrgCalendarEvent = (
  projectId: string,
  orgId: string,
  agentId: string,
  name: string,
) =>
  apiFetch<void>(
    `${orgBase(projectId, orgId)}/calendar/${encodeURIComponent(agentId)}/${encodeURIComponent(name)}`,
    { method: "DELETE" },
  );

export const listOrgTickets = (projectId: string, orgId: string) =>
  apiFetch<OrgTicketsResponse>(`${orgBase(projectId, orgId)}/tickets`);

export const getOrgTicket = (projectId: string, orgId: string, ticketId: string) =>
  apiFetch<OrgTicketDetail>(`${orgBase(projectId, orgId)}/tickets/${encodeURIComponent(ticketId)}`);

export const createOrgTicket = (projectId: string, orgId: string, body: OrgTicketCreateRequest) =>
  apiFetch<OrgTicketDetail>(`${orgBase(projectId, orgId)}/tickets`, { method: "POST", body });

export const updateOrgTicket = (
  projectId: string,
  orgId: string,
  ticketId: string,
  body: OrgTicketUpdateRequest,
) =>
  apiFetch<OrgTicketDetail>(
    `${orgBase(projectId, orgId)}/tickets/${encodeURIComponent(ticketId)}`,
    { method: "PUT", body },
  );

/** `…/tickets/:ticketId/<action>` POST helper shared by the six ticket actions. */
const ticketAction = <T>(
  projectId: string,
  orgId: string,
  ticketId: string,
  action: string,
  body: unknown,
) =>
  apiFetch<T>(`${orgBase(projectId, orgId)}/tickets/${encodeURIComponent(ticketId)}/${action}`, {
    method: "POST",
    body,
  });

export const moveOrgTicket = (
  projectId: string,
  orgId: string,
  ticketId: string,
  body: OrgTicketMoveRequest,
) => ticketAction<OrgTicketDetail>(projectId, orgId, ticketId, "move", body);

export const blockOrgTicket = (
  projectId: string,
  orgId: string,
  ticketId: string,
  body: OrgTicketBlockRequest,
) => ticketAction<OrgTicketDetail>(projectId, orgId, ticketId, "block", body);

export const unblockOrgTicket = (projectId: string, orgId: string, ticketId: string) =>
  ticketAction<OrgTicketDetail>(projectId, orgId, ticketId, "unblock", {});

export const progressOrgTicket = (
  projectId: string,
  orgId: string,
  ticketId: string,
  body: OrgTicketProgressRequest,
) => ticketAction<OrgTicketDetail>(projectId, orgId, ticketId, "progress", body);

export const startOrgTicket = (
  projectId: string,
  orgId: string,
  ticketId: string,
  body: OrgTicketStartRequest = {},
) => ticketAction<OrgTicketStartResponse>(projectId, orgId, ticketId, "start", body);

export const attachOrgTicket = (
  projectId: string,
  orgId: string,
  ticketId: string,
  body: OrgTicketAttachRequest,
) => ticketAction<OrgTicketDetail>(projectId, orgId, ticketId, "attach", body);

const channelBase = (projectId: string, orgId: string, channelId: string) =>
  `${orgBase(projectId, orgId)}/channels/${encodeURIComponent(channelId)}`;

/** The organization's channels: the all-hands one first, then by name. */
export const listOrgChannels = (projectId: string, orgId: string) =>
  apiFetch<OrgChannelsResponse>(`${orgBase(projectId, orgId)}/channels`);

export const createOrgChannel = (projectId: string, orgId: string, body: OrgChannelCreateRequest) =>
  apiFetch<OrgChannelItem>(`${orgBase(projectId, orgId)}/channels`, { method: "POST", body });

export const getOrgChannel = (projectId: string, orgId: string, channelId: string) =>
  apiFetch<OrgChannelDetail>(channelBase(projectId, orgId, channelId));

export const patchOrgChannel = (
  projectId: string,
  orgId: string,
  channelId: string,
  body: OrgChannelPatchRequest,
) => apiFetch<OrgChannelItem>(channelBase(projectId, orgId, channelId), { method: "PATCH", body });

export const addOrgChannelMember = (
  projectId: string,
  orgId: string,
  channelId: string,
  body: OrgChannelMemberRequest,
) =>
  apiFetch<OrgChannelDetail>(`${channelBase(projectId, orgId, channelId)}/members`, {
    method: "POST",
    body,
  });

/** Removes a member; `principal` is the literal `agent:<id>` / `user:<id>`, encoded into the path. */
export const removeOrgChannelMember = (
  projectId: string,
  orgId: string,
  channelId: string,
  principal: string,
) =>
  apiFetch<void>(
    `${channelBase(projectId, orgId, channelId)}/members/${encodeURIComponent(principal)}`,
    { method: "DELETE" },
  );

/** One day of a channel (today in the organization's timezone when `date` is omitted). */
export const getOrgChannelMessages = (
  projectId: string,
  orgId: string,
  channelId: string,
  date?: string,
) =>
  apiFetch<OrgChannelMessagesResponse>(`${channelBase(projectId, orgId, channelId)}/messages`, {
    query: { date },
  });

export const sendOrgChannelMessage = (
  projectId: string,
  orgId: string,
  channelId: string,
  body: OrgChannelMessageSendRequest,
) =>
  apiFetch<OrgChannelMessage>(`${channelBase(projectId, orgId, channelId)}/messages`, {
    method: "POST",
    body,
  });

export const readOrgChannel = (
  projectId: string,
  orgId: string,
  channelId: string,
  body: OrgChannelReadRequest,
) => apiFetch<void>(`${channelBase(projectId, orgId, channelId)}/read`, { method: "POST", body });

/** Budget and spend for one `yyyy-mm` period (the current one when omitted). */
export const getOrgFinance = (projectId: string, orgId: string, period?: string) =>
  apiFetch<OrgFinanceResponse>(`${orgBase(projectId, orgId)}/finance`, {
    query: { period },
  });

export const getOrgSessions = (projectId: string, orgId: string) =>
  apiFetch<OrgSessionsResponse>(`${orgBase(projectId, orgId)}/sessions`);
// Desktop tray icon (desktop-shell sessions only) --------------------------------------

/** What the shell last pushed; `status` is null until that first push, which reads as on. */
export const getDesktopTray = () => apiFetch<DesktopTrayStatusResponse>("/api/desktop/tray");

/**
 * Relays a tray change to the shell, which applies it and pushes the new state back.
 *
 * A patch rather than a snapshot: Settings › Appearance writes the switch, and the locale
 * provider writes the UI language whenever it changes, and neither knows the other's value.
 */
export const setDesktopTray = (patch: DesktopTrayPatch) =>
  apiFetch<void>("/api/desktop/tray", { method: "PUT", body: patch });

/** Has the desktop shell open System Settings at a Privacy & Security pane (macOS). */
export const openPrivacySettings = (pane: DesktopPrivacyPane) =>
  apiFetch<void>("/api/desktop/privacy-settings", {
    method: "POST",
    body: { pane },
    server: null,
  });

// Desktop pet (desktop-shell sessions only) --------------------------------------------

/** What the shell last pushed; `status` is null until that first push, which reads as off. */
export const getDesktopPet = () => apiFetch<DesktopPetStatusResponse>("/api/desktop/pet");

/**
 * Relays the pet switch to the shell, which opens or closes the window at once and pushes the
 * new state back. Settings › Appearance writes it, and so does the pet window's own "hide me"
 * row — the same field through the same route, so the two can never disagree.
 */
export const setDesktopPet = (patch: DesktopPetPatch) =>
  apiFetch<void>("/api/desktop/pet", { method: "PUT", body: patch });

// Desktop sign-in entry (desktop-shell sessions only, Windows) --------------------------

/**
 * What Windows itself says about starting the app when the user signs in, as the shell last read
 * it. `status` is null until that first read lands, and `status.supported` is false wherever there
 * is no entry to manage (every non-Windows platform, and a dev shell) — both of which the
 * Appearance page renders as no row at all, because there is no honest default for a switch that
 * is really a registry value.
 */
export const getDesktopLoginItem = () =>
  apiFetch<DesktopLoginItemStatusResponse>("/api/desktop/login-item");

/** Relays the sign-in switch to the shell, which writes the entry and pushes back what Windows says. */
export const setDesktopLoginItem = (patch: DesktopLoginItemPatch) =>
  apiFetch<void>("/api/desktop/login-item", { method: "PUT", body: patch });

// ---- Workflows (an Agent's own extension packages, served as tabs beside the chat) ----
const workflowsBase = (projectId: string, agentId: string) =>
  `/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agentId)}/workflows`;
/**
 * `machineId` on each of these: an Agent's workflows live where its state directory does, so
 * the workflows of an Agent that only a machine has are asked of THAT machine's server.
 */
export const getWorkflows = (projectId: string, agentId: string, machineId: string | null = null) =>
  apiFetch<{ workflows: WorkflowInfo[] }>(workflowsBase(projectId, agentId), {
    server: machineId,
  });
/** Re-import the folder now (the server also does this whenever a file changes). */
export const reloadWorkflow = (
  projectId: string,
  agentId: string,
  workflowId: string,
  machineId: string | null = null,
) =>
  apiFetch<{ workflow: WorkflowInfo }>(
    `${workflowsBase(projectId, agentId)}/${encodeURIComponent(workflowId)}/reload`,
    { method: "POST", body: {}, server: machineId },
  );
export const getWorkflowHistory = (
  projectId: string,
  agentId: string,
  workflowId: string,
  machineId: string | null = null,
) =>
  apiFetch<{ versions: WorkflowVersion[] }>(
    `${workflowsBase(projectId, agentId)}/${encodeURIComponent(workflowId)}/history`,
    { server: machineId },
  );
/** Restore a recorded version's files (state.json is kept) and reload. */
export const rollbackWorkflow = (
  projectId: string,
  agentId: string,
  workflowId: string,
  revision: string,
  machineId: string | null = null,
) =>
  apiFetch<{ workflow: WorkflowInfo }>(
    `${workflowsBase(projectId, agentId)}/${encodeURIComponent(workflowId)}/rollback`,
    { method: "POST", body: { revision }, server: machineId },
  );
/** Delete the folder and the versions recorded for it; nothing of the workflow is kept. */
export const removeWorkflow = (
  projectId: string,
  agentId: string,
  workflowId: string,
  machineId: string | null = null,
) =>
  apiFetch<void>(`${workflowsBase(projectId, agentId)}/${encodeURIComponent(workflowId)}`, {
    method: "DELETE",
    server: machineId,
  });

// ---- The plugins a Project asks for, and the confinement agent commands run under ----
/**
 * A Project's plugin list. Project-scoped because machines are lent to Projects, so this is
 * what says which machines a plugin has to reach; what the process RUNS is the union over
 * the Projects, since loading is per process (see the server's plugin/loader.ts).
 */
const pluginsPath = (projectId: string) =>
  `/api/projects/${encodeURIComponent(projectId)}/plugins/installed`;
/**
 * `server` reads a machine's own list through this server's tunnel — what it actually runs —
 * and null reads this server's, which holds the Project's tables for the whole fleet.
 */
export const getInstalledPlugins = (projectId: string, server: string | null = null) =>
  apiFetch<InstalledPluginsResponse>(pluginsPath(projectId), { server });
/** Admin only; applied without a restart where the runtime can re-assemble the App. */
export const putInstalledPlugins = (projectId: string, plugins: readonly string[]) =>
  apiFetch<InstalledPluginsResponse>(pluginsPath(projectId), {
    method: "PUT",
    body: { plugins },
  });
/**
 * Admin only: asks this Project for a plugin the build ships — in the shared table, or with
 * `machineId` in that machine's own table — refused for one it does not, so the list never
 * names a package that is not on the machine; then re-assembles the App where it runs here.
 */
export const installPlugin = (
  projectId: string,
  specifier: string,
  machineId: string | null = null,
) =>
  apiFetch<InstalledPluginsResponse>(pluginsPath(projectId), {
    method: "POST",
    body: machineId === null ? { specifier } : { specifier, machineId },
  });
/**
 * Admin only: drops it from every table of this Project, or with `machineId` from that
 * machine's own table; nothing on disk changes.
 */
export const uninstallPlugin = (
  projectId: string,
  specifier: string,
  machineId: string | null = null,
) =>
  apiFetch<InstalledPluginsResponse>(
    `${pluginsPath(projectId)}?specifier=${encodeURIComponent(specifier)}${
      machineId === null ? "" : `&machineId=${encodeURIComponent(machineId)}`
    }`,
    { method: "DELETE" },
  );

// ---- The built-in browser (desktop app only; every route is admin-only) ----
/**
 * Always this server's: the pages live in the desktop shell this server was spawned by, so a
 * machine's browser routes would drive a shell that is not on this screen.
 */
const builtinBrowserPath = (rest: string) => `/api/builtin-browser${rest}`;

/** What the storage-clearing route takes (the shell's own clear-data command). */
export type BuiltinBrowserStorage = Extract<
  DesktopBrowserCommand,
  { op: "clear-data" }
>["storages"][number];

/** Whether the browser can be driven at all, and its tabs as they stand. */
export const getBuiltinBrowserStatus = () =>
  apiFetch<BuiltinBrowserStatus>(builtinBrowserPath("/status"), { server: null });
/**
 * A new tab, at `url` or else at the homepage (blank without one). The server asks this window
 * (over the user channel) to create the page, and answers once the page is claimed — so this
 * resolves after the tab exists.
 */
export const openBuiltinBrowserTab = (body: { url?: string; activate?: boolean }) =>
  apiFetch<{ tab: BuiltinBrowserTab }>(builtinBrowserPath("/tabs"), {
    method: "POST",
    body,
    server: null,
  });
/** Ties a page this window created to the open request it answers; 409 when another window was first. */
export const claimBuiltinBrowserTab = (requestId: string, tabId: number) =>
  apiFetch<void>(builtinBrowserPath("/tabs/claim"), {
    method: "POST",
    body: { requestId, tabId },
    server: null,
  });
/** The user brought a tab to the front: it is also the one an agent's next command acts on. */
export const activateBuiltinBrowserTab = (tabId: number) =>
  apiFetch<{ tab: BuiltinBrowserTab }>(builtinBrowserPath(`/tabs/${tabId}/activate`), {
    method: "POST",
    server: null,
  });
/** The tab this window shows on screen, or none: the server leaves that one unthrottled. */
export const setBuiltinBrowserOnScreen = (tabId: number | null) =>
  apiFetch<void>(builtinBrowserPath("/tabs/on-screen"), {
    method: "POST",
    body: { tabId },
    server: null,
  });
export const closeBuiltinBrowserTab = (tabId: number) =>
  apiFetch<void>(builtinBrowserPath(`/tabs/${tabId}`), { method: "DELETE", server: null });
/** The system browsers' profiles on this computer that can be imported from. */
export const getBuiltinBrowserImportSources = () =>
  apiFetch<BuiltinBrowserImportSourcesResponse>(builtinBrowserPath("/import/sources"), {
    server: null,
  });
export const importIntoBuiltinBrowser = (body: BuiltinBrowserImportRequest) =>
  apiFetch<BuiltinBrowserImportResult>(builtinBrowserPath("/import"), {
    method: "POST",
    body,
    server: null,
  });
/** The browser's settings — its homepage. The server's own file: no desktop shell needed. */
export const getBuiltinBrowserSettings = () =>
  apiFetch<BuiltinBrowserSettings>(builtinBrowserPath("/settings"), { server: null });
/** Replaces them; answers them as stored (a bare host given its scheme). */
export const putBuiltinBrowserSettings = (settings: BuiltinBrowserSettings) =>
  apiFetch<BuiltinBrowserSettings>(builtinBrowserPath("/settings"), {
    method: "PUT",
    body: settings,
    server: null,
  });
/** History matching `q` (address and title), most visited first. */
export const searchBuiltinBrowserHistory = (q: string, limit: number) =>
  apiFetch<BuiltinBrowserHistoryResponse>(builtinBrowserPath("/history"), {
    query: { q, limit },
    server: null,
  });
export const clearBuiltinBrowserHistory = () =>
  apiFetch<void>(builtinBrowserPath("/history"), { method: "DELETE", server: null });
export const clearBuiltinBrowserData = (storages: BuiltinBrowserStorage[]) =>
  apiFetch<void>(builtinBrowserPath("/clear-data"), {
    method: "POST",
    body: { storages },
    server: null,
  });

// ---- Themes this installation imported (a data root's own `themes/` directory) ----
/**
 * What this installation put in its data root's `themes/`, plus the files that would not read and
 * why. The server reads the directory on every request, so a file added, edited or deleted shows up
 * on the next read; the stylesheet the browser links from `<head>` is `/api/themes.css`, which the
 * app never fetches itself — the server turns the same files into CSS for it.
 *
 * This server's own directory, never a machine's: the sheet is linked by the page the server just
 * served, so the two would otherwise describe different machines.
 */
export const getImportedThemes = () =>
  apiFetch<ImportedThemesResponse>("/api/themes", { server: null });

/**
 * Import a theme from a file the operator picked: the theme JSON, base64 in the body — the same
 * shape the plugin, skill and hook imports take. 201 returns the file it was written to (the
 * theme's own id plus `.json`) and the theme as data. Admin-only, and 409 `theme_exists` when a
 * file already provides that theme's id — the retry sends the same body with `overwrite: true`.
 */
export const importThemeArchive = (body: ThemeUploadRequest) =>
  apiFetch<ThemeImportResponse>("/api/themes/upload", { method: "POST", body, server: null });

/**
 * The same import, fetched by the server from an http(s) address — the server is what can reach
 * it. Read by the same reader the upload path uses, so a link to a theme JSON installs what
 * picking that file installs. Answers the same 409 (and the same `overwrite` retry) plus 400
 * `unsupported_url`, 400 `blocked_url` (a local or private host) and 400 `download_failed`.
 * Admin-only.
 */
export const importThemeFromUrl = (body: ThemeDownloadRequest) =>
  apiFetch<ThemeImportResponse>("/api/themes/download", { method: "POST", body, server: null });

/**
 * The catalogue a remote theme registry publishes (npmmirror's copy of the theme package, or
 * whatever `ADELIE_THEME_REGISTRY` names), with each entry marked installed or not. Read by the
 * server, because the server is what can reach it. A registry that could not be read answers 200
 * with `error` and no themes — a note above the picker, not a failed page.
 */
export const getThemeRegistry = () =>
  apiFetch<ThemeRegistryResponse>("/api/themes/registry", { server: null });

/**
 * Install one entry the catalogue names, by id: the server fetches that entry's file through the
 * same guards as the address import and writes it through the same reader, so 409 `theme_exists`
 * (and the same `overwrite` retry) is answered here too. Unknown id: 404
 * `registry_theme_not_found`. Admin-only.
 */
export const importThemeFromRegistry = (body: ThemeRegistryImportRequest) =>
  apiFetch<ThemeImportResponse>("/api/themes/registry/import", {
    method: "POST",
    body,
    server: null,
  });