A local-first multi-agent app development platform, built on PenguinHarness
/**
* 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,
});