Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
import React, { createContext, useContext, useEffect, useMemo, useRef } from 'react';
import { useTranslation } from 'react-i18next';
import { useToast } from './ToastContext';
import type { PickerAgentCatalog } from '../components/settings/models/types';
import type { AgentBackendId, NativeCliBackend, WebOAuthBackend } from '../lib/agentBackends';
import { apiFetch, recoverRemoteAuthFromSessionProbe, withApiDeadline } from '../lib/apiFetch';
import { isAuthorizationSensitiveReadPath } from '../lib/authorizationCache';
import { parseBot, type AgentBotSummary, type Bot, type BotEmojiAvatarInput } from '../lib/bots';
import { parseNotificationPreferences, type InboxCategory, type NotificationPreferences } from '../lib/notificationPreferences';
import type { TurnActivityGroupWire } from '../lib/agentActivity';
import type { AgentGraphParams, AgentGraphResult, AgentGraphVisibility } from '../lib/agentGraph';
import { onPageReactivated, type PageReactivationListener } from '../lib/pageActivity';
import type { ScopeKind, ScopeSettingsChange } from '../lib/scopeSettingsPatch';
import type { ShowPagePayload } from '../lib/showPageLinks';
import { visibilityActivityEvents } from '../lib/sessionVisibilityEvents';
import { normalizeSessionInfo, type InstanceCapabilities, type SessionInfo } from '../lib/sessionInfo';
import type { VaultSessionPolicy } from '../lib/vaultSandboxPolicy';
import {
classifyShowPageAccessProbe,
type ShowPageAccess,
type ShowPageAccessProbe,
type ShowAccessApplyRequest,
type ShowAccessApplyResult,
type ShowAccessSettingsResult,
} from '../lib/showPageAccess';
import {
WorkbenchEventReconnectLoop,
WORKBENCH_EVENT_HEARTBEAT_FALLBACK_MS,
declaredWorkbenchHeartbeatInterval,
isWorkbenchHeartbeatFresh,
parseWorkbenchHeartbeatInterval,
streamCoveredGap,
workbenchEventStaleAfterMs,
type WorkbenchControllerLegState,
type WorkbenchEventConnectionState,
} from '../lib/workbenchEventConnection';
import type { DockDoc } from './dockDoc';
import { archivedConflictSessionId, selectApiErrorFields } from './apiErrorParse';
import {
SessionDraftPersistence,
type SessionDraftSaveResult,
type SessionDraftServerState,
type SessionDraftWrite,
} from '../lib/sessionDraftPersistence';
import { getExistingWebPushSubscription, getWebPushDeviceId } from '../lib/webPush';
import { reportRemoteAuthorizationState, type RemoteAuthorizationState } from '../lib/remoteAuth';
import {
configMutationsToPayload,
type ConfigMutation,
} from '../lib/configMutations';
export type { InstanceCapabilities, SessionInfo };
export type { ShowPageAccess };
export type { ConfigMutation };
// The workbench Dock API response shape ({ ok, dock }); the Dock document type
// itself lives with the DockProvider that owns reconciliation.
export type DockResponse = { ok: boolean; dock: DockDoc };
export type ScopeSettingsPatchRequest = ScopeSettingsChange & {
platform: string;
scope: ScopeKind;
id: string;
thread_id?: string;
};
export type ScopeSettingsPatchResult = {
ok: boolean;
platform: string;
scope: ScopeKind;
id: string;
thread_id?: string;
/** The scope's stored row, in the shape the settings reads return it. */
settings: unknown;
/** After a routing change: whether the scope's current session keeps another
* Agent until a new session starts there; null when that is unknown. */
needs_new_session?: boolean | null;
};
// Global workbench toggles persisted server-side in state_meta. Currently just
// the background-work banner switch (spec req 2); read by ChatPage (to gate the
// banner) and the Harness page (the toggle card).
export type WorkbenchPrefs = {
ok?: boolean;
background_work_banner_enabled: boolean;
/** Whether a new Web Session starts with fast mode on: the last choice made in a model picker. */
fast_mode_default?: boolean;
};
/** A Session's processing tier: ``fast`` asks its turns for the vendor's fast tier; null is standard. */
export type SessionSpeed = 'fast' | null;
// One backend's *global* instructions file, surfaced by the Global Prompts
// editor. ``backend`` is an agent backend id (claude / opencode / codex).
export type GlobalPromptFile = {
backend: string;
path: string;
filename: string;
content: string;
exists: boolean;
/** True when the file exists but couldn't be decoded as UTF-8; the editor
* then warns and refuses to overwrite it with an empty draft. */
read_error: boolean;
};
/** Receive addresses derived from a keypair secret's secp256k1 public key. */
export type SigningAddresses = {
eth?: string;
btc_legacy?: string;
btc_segwit?: string;
btc_taproot?: string;
};
export type VaultSecret = {
name: string;
/** Absent on legacy servers; the default record is always the bare secret name. */
default_field?: string;
fields?: string[];
/** Present only when the stored extra-field section could not be read safely. */
fields_state?: 'corrupt';
/** Flat tag list; skill association is a reserved `skill:<name>` tag (see lib/vaultTags). */
tags: string[];
kind: string;
protection: string;
signer_kind: string | null;
/** Receive addresses derived from a keypair secret's public key. Agents and the UI
* identify a signing key by address; the raw public key is never surfaced here. */
signing_addresses?: SigningAddresses | null;
source: string;
description?: string | null;
policy: Record<string, unknown>;
last_used_at: string | null;
use_count: number;
created_at: string;
updated_at: string;
};
export type VaultAuditEvent = {
id: string;
ts: string;
event: string;
secret_name: string | null;
request_id: string | null;
grant_id: string | null;
};
export type VaultRequest = {
id: string;
request_type: string;
secret_name: string | null;
requester: unknown;
delivery: unknown;
status: string;
message_id: string | null;
created_at: string;
decided_at: string | null;
expires_at: string | null;
card?: Record<string, unknown> | null;
session?: VaultRequestSession | null;
};
export type VaultRequestSession = {
id: string;
title: string | null;
label: string | null;
platform: string | null;
scope_kind: string | null;
is_workbench: boolean;
};
export type VaultRequestSpec = {
kind?: 'static';
default_field?: string;
fields?: string[];
protection?: 'standard' | 'protected';
description?: string;
/** May already include `skill:<name>` tags; `links.skills` is a bare-name convenience mirror. */
tags?: string[];
policy?: {
allowed_hosts?: string[];
auth?: { type?: 'bearer' | 'header' | 'query'; name?: string };
};
links?: { skills?: string[] };
};
/**
* How a grant's protected set was selected. Env selectors are explicit secret/env
* names (`OPENAI_API_KEY`, `DB_URL=PROD_DB_URL`); tag selectors group by tag, with
* skill selectors carried as `skill:<name>` tags.
*/
export type VaultSourceSelector = { env?: string[]; tags?: string[] };
/**
* A grant is a first-class, time-limited authorization for avault to use a fixed set
* of protected secrets (design: docs/plans/vaults-grant-delivery-refactor.md §6). It
* is keyed by `id` (the grant_id); `member_snapshot` is the frozen protected set and
* `source_selector` records how it was chosen. Tag edits never mutate an active grant.
*/
export type VaultGrant = {
id: string;
source_selector: VaultSourceSelector;
session_id: string | null;
purpose: string;
status: string;
request_id: string | null;
created_at: string;
expires_at: string;
revoked_at: string | null;
member_snapshot: string[];
member_count: number;
runtime_member_count: number;
delivery_ready?: boolean;
delivery_status?: string;
one_shot?: boolean;
};
type VaultBlindBox = {
scheme: string;
enc: string;
ct: string;
};
/**
* Browser-relayed protected access fulfillment. The browser releases each protected
* DEK as an opaque HPKE blind box addressed to the resident avault agent and submits
* ONLY `{name, dek_blindbox, approval}` per secret — never a raw DEK or plaintext.
*/
export type VaultAccessFulfillmentPayload = {
grant_id?: string;
session_id?: string | null;
/** Approver-chosen agent access duration (protocol v2 §7.1); supersedes the old fixed ttl. */
grant_duration?: VaultGrantDuration;
this_session_only?: boolean;
agent_pubkey?: { public_key?: string; fingerprint?: string };
deks?: Array<{ name: string; dek_blindbox: VaultBlindBox; approval: Record<string, unknown> }>;
};
export type VaultSandboxRootMetadataResult = {
ok: boolean;
root_metadata: {
daemon: {
verificationKeys: Array<{ alg: 'ed25519'; keyId: string; publicKey: string }>;
};
};
code?: string;
message?: string;
};
/** Approver-chosen agent access duration (protocol v2 §7.1). `'one-time'` = a single delivery. */
export type VaultGrantDuration = 'one-time' | number;
/**
* The ed25519-signed operation context the daemon issues and the sandbox renders verbatim
* (protocol v2 §6.2). Everything a human authorizes — the covered secrets, session, command,
* egress, source, and agent access duration — travels inside the signed `display` block so a
* compromised parent can't rewrite the consent story.
*/
export type VaultSignedOperationContext = {
v: 2;
purpose: 'agent-deliver' | 'sign' | 'reveal';
requestId: string;
grantId?: string;
display: {
secrets: Array<{ name: string; kind: 'static' | 'keypair' }>;
sessionLabel?: string;
command?: string;
egress?: string;
source?: { env?: string[]; tags?: string[]; skills?: string[] };
grantTtlSeconds?: number;
};
agent?: { publicKey: { public_key: string; fingerprint?: string }; fingerprint: string };
expiresAt: string;
signature: { alg: 'ed25519'; keyId: string; value: string };
};
/**
* One `POST /api/vault/agent-bindings:batch` call returns per-secret signed contexts sharing one
* display block (protocol v2 §7.1) — the parent brokers all members to the sandbox in a single
* `approveRelease`, then submits the resulting blind boxes with the matching `approval` handles.
*/
export type VaultAgentBindingsBatchResult = {
ok: boolean;
request_id?: string;
grant_id?: string;
grant_duration?: VaultGrantDuration;
ttl_seconds?: number;
agent?: { publicKey: { public_key: string; fingerprint?: string }; fingerprint: string };
agent_pubkey: { public_key: string; fingerprint: string };
items: Array<{
name: string;
context: VaultSignedOperationContext;
approval: { nonce: string; expires_at_unix: number };
}>;
code?: string;
message?: string;
};
/** Persisted vault session settings (daemon side). Mirrors `GET/PATCH /api/vault/settings`. */
export type VaultSettings = {
unlock_window_seconds: number;
strict_approvals: boolean;
last_grant_ttl: VaultGrantDuration;
};
export type VaultSettingsResult = {
ok: boolean;
settings: VaultSettings;
policy: VaultSessionPolicy;
code?: string;
message?: string;
};
/**
* `POST /api/vault/secrets/<name>/reveal-context`. The daemon signs a `reveal` context naming the
* secret; the sandbox renders it and displays the plaintext in-frame. The protected record
* `envelope` is relayed alongside so the sandbox can open it (the parent only holds ciphertext).
*/
export type VaultRevealContextResult = {
ok: boolean;
context?: VaultSignedOperationContext;
envelope?: VaultSealedEnvelope;
code?: string;
message?: string;
};
type VaultSealedEnvelope = {
ciphertext: string;
nonce: string;
wrap_meta: string | Record<string, unknown>;
};
export type VaultVmkResult = {
ok: boolean;
exists: boolean;
wrap_meta: string | null;
};
export type VaultWebAuthnCredentialDescriptor = {
type: 'public-key';
id: string;
factor_id?: string;
transports?: AuthenticatorTransport[];
};
export type VaultWebAuthnAssertionOptions = {
challenge: string;
rpId: string;
userVerification: UserVerificationRequirement;
allowCredentials: VaultWebAuthnCredentialDescriptor[];
};
export type VaultWebAuthnRegistrationOptions = {
ok: boolean;
challenge_id: string;
expires_at: string;
rp_id: string;
origin: string;
requires_existing_factor?: boolean;
webauthn: {
rp: { name: string; id: string };
user: { id: string; name: string; displayName: string };
challenge: string;
pubKeyCredParams: PublicKeyCredentialParameters[];
authenticatorSelection: AuthenticatorSelectionCriteria;
extensions?: AuthenticationExtensionsClientInputs;
};
authorization?: {
challenge_id: string;
expires_at: string;
webauthn: VaultWebAuthnAssertionOptions;
};
code?: string;
message?: string;
};
export type VaultWebAuthnSerializedCredential = {
id: string;
rawId: string;
type: string;
response: Record<string, unknown>;
};
export type VaultWebAuthnAuthz = {
kind: 'webauthn';
challenge_id: string;
factor_id: string;
assertion: VaultWebAuthnSerializedCredential;
};
export type VaultWebAuthnRegistrationPayload = {
challenge_id: string;
credential: VaultWebAuthnSerializedCredential;
label?: string;
authz?: VaultWebAuthnAuthz;
};
export type VaultCreatePayload = {
name: string;
default_field?: string;
fields?: VaultCreateFieldPayload[];
protection?: 'standard' | 'protected';
blind_box?: VaultBlindBox;
sealed?: VaultSealedEnvelope;
envelope?: VaultSealedEnvelope;
description?: string;
/** Flat tag list; skill association is folded in as `skill:<name>` tags (see lib/vaultTags). */
tags?: string[];
kind?: string;
signer_kind?: string | null;
policy?: Record<string, unknown>;
public_meta?: Record<string, unknown>;
/** Bare skill names. Sent alongside the folded `skill:<name>` tags so skill scopes work on
* the pre-refactor backend (which populates vault_links from links.skills); `links.skills`
* is also part of the final request spec (design §5). */
links?: { skills?: string[] };
provision_request_id?: string;
/** Set on the first protected secret so the daemon atomically guards single VMK init. */
establishing_vmk?: boolean;
/** First protected-vault setup registers the delete-authz public key in the same transaction. */
authz_factor_registration?: VaultWebAuthnRegistrationPayload;
};
/**
* Value-free metadata edit (`PATCH /api/vault/secrets/<name>`). At least one field must be
* present. `description: null`/blank clears it; `tags: []` clears all tags; `policy` replaces
* the visible fetch policy (allowed_hosts + auth) while the backend preserves internal keys
* such as `always_ask`. Name / kind / protection / value are never editable through this path.
*/
export type VaultMetadataUpdatePayload = {
default_field?: string;
description?: string | null;
tags?: string[];
policy?: Record<string, unknown>;
};
export type VaultFieldValuePayload = {
/** Canonical record name bound into the envelope (NAME for the default field). */
record: string;
blind_box?: VaultBlindBox;
sealed?: VaultSealedEnvelope;
expected_updated_at?: string;
};
export type VaultCreateFieldPayload = {
name: string;
/** Canonical record name bound into this extra field's envelope. */
record: string;
blind_box?: VaultBlindBox;
sealed?: VaultSealedEnvelope;
};
export type TunnelQualitySnapshot = {
schema_version: 1 | 2;
state: 'healthy' | 'degraded' | 'recovering' | 'unknown';
grade: 'good' | 'fair' | 'poor' | 'critical' | 'unknown';
sampled_at: string;
protocol: 'quic' | 'http2' | 'unknown';
transport?: {
configured: 'auto' | 'quic' | 'http2';
effective: 'quic' | 'http2' | 'unknown';
};
connector_count: number;
ha_connections: number;
rtt_ms: { min: number; median: number; max: number } | null;
baseline_median_rtt_ms: number | null;
edge_locations: string[];
window_seconds: number;
request_errors_per_minute: number;
packet_loss_per_minute: number;
request_path?: {
source: 'synthetic_local';
status: 'healthy' | 'degraded' | 'unavailable' | 'insufficient';
confidence: 'low' | 'medium' | 'high';
window_seconds: number;
sample_count: number;
success_count: number;
latency_ms: { p50: number; p95: number; p99: number; max: number } | null;
failure_rate: number;
slow_request_rate: {
over_500_ms: number;
over_1000_ms: number;
over_2000_ms: number;
};
baseline_p95_ms: number | null;
} | null;
recovery: {
state: 'idle' | 'evaluating' | 'draining' | 'cooldown';
last_attempt_at: string | null;
last_trigger: 'availability' | 'latency' | 'tail_latency' | 'errors' | 'manual' | null;
last_result: 'improved' | 'no_improvement' | 'failed' | null;
previous_median_rtt_ms: number | null;
result_median_rtt_ms: number | null;
previous_protocol?: 'quic' | 'http2' | null;
result_protocol?: 'quic' | 'http2' | null;
previous_p95_ms?: number | null;
result_p95_ms?: number | null;
previous_p99_ms?: number | null;
result_p99_ms?: number | null;
next_attempt_at: string | null;
attempt_count_window: number;
};
};
export type CloudflareEdgeLocation = {
colo: string;
location?: string;
country?: string;
};
export type TunnelNetworkPath = {
schema_version: 1;
provider: 'Cloudflare';
asn: 13335;
sampled_at: string;
locations_pending: boolean;
client_access: 'local' | 'remote';
client_ingress: CloudflareEdgeLocation | null;
connector: {
locations: Array<CloudflareEdgeLocation & { id: string }>;
edge_ips: string[];
};
route: {
assessment: 'same_metro' | 'same_country' | 'cross_country' | 'unknown';
};
};
export type RemoteAccessStatus = {
ok: boolean;
enabled: boolean;
paired: boolean;
running: boolean;
public_url?: string;
pid_state?: string;
transport_protocol?: 'auto' | 'quic' | 'http2';
settings?: RemoteAccessSettings;
tunnel_quality?: TunnelQualitySnapshot;
network_path?: TunnelNetworkPath;
error?: string;
optimization_started?: boolean;
pending_pairing?: {
phase: 'prepared' | 'redeemed' | 'applied' | 'revoked' | 'retirement_pending' | 'invalid';
can_resume: boolean;
} | null;
};
export type RemoteAccessSettings = {
transport_protocol: 'auto' | 'quic' | 'http2';
auto_recovery: boolean;
optimization_profile: 'stable' | 'balanced' | 'low_latency';
edge_ip_version: 'auto' | '4' | '6';
edge_bind_address: string;
};
export type TunnelNetworkInterface = {
id: string;
name: string;
address: string;
ip_version: '4' | '6';
};
export type TunnelConnectivityDiagnostics = {
ok: boolean;
sampled_at: string;
effective_protocol: 'quic' | 'http2' | 'unknown';
dns: { status: 'available' | 'unavailable' | 'unknown' };
quic: { status: 'available' | 'unavailable' | 'unknown'; source: string };
http2: { status: 'available' | 'unavailable' | 'unknown'; source: string };
cloudflared_version?: string | null;
error?: string;
};
// MCP Hub (/api/mcp*): static packages generated from MCP servers.
export interface McpServerSummary {
name: string;
description?: string;
transport?: string;
source?: 'avibe' | 'claude' | 'codex' | 'opencode';
sourcePath?: string;
command?: string;
url?: string;
revision?: string | null;
generatedAt?: string;
serverVersion?: string;
auth?: 'none' | 'needs_login' | 'ok';
toolCount?: number;
tools?: { name: string; description?: string }[];
diagnostics?: string[];
}
export interface McpError { type: string; message: string; field?: string; hint?: string }
/** Masked definition from GET /api/mcp/{name}: env/header values are always blank. */
export interface McpDefinition {
name: string;
description?: string;
transport: {
type: 'stdio' | 'streamable_http';
command?: string;
args?: string[];
cwd?: string;
url?: string;
env?: Record<string, string>;
headers?: Record<string, string>;
has_env?: Record<string, boolean>;
has_headers?: Record<string, boolean>;
};
}
export interface McpResult { ok: boolean; error?: McpError }
export type McpOAuthMutationResult = McpResult & { name?: string };
export interface McpTool { name: string; description?: string; inputSchema?: unknown; flags: { flag: string; kind: string; required: boolean }[] }
export type ApiContextType = {
/** `cache: false` reads past the 30-second config cache, for a surface (the
* desktop pet) that must see a setup another window just finished. */
getConfig: (options?: { cache?: boolean }) => Promise<any>;
getPlatformCatalog: () => Promise<any>;
mutateConfig: (mutations: readonly ConfigMutation[]) => Promise<any>;
waitForAgentActivityConfigMutations: () => Promise<void>;
onConfigChanged: (handler: (config: unknown) => void) => () => void;
getSettings: (platform?: string) => Promise<any>;
saveSettings: (payload: any, platform?: string) => Promise<any>;
saveThreadSettings: (platform: string, channelId: string, threadId: string, settings: any) => Promise<any>;
patchScopeSettings: (request: ScopeSettingsPatchRequest) => Promise<ScopeSettingsPatchResult>;
deleteThreadSettings: (platform: string, channelId: string, threadId: string) => Promise<any>;
getUsers: (platform?: string) => Promise<any>;
saveUsers: (payload: any, platform?: string) => Promise<any>;
toggleAdmin: (userId: string, isAdmin: boolean, platform?: string) => Promise<any>;
removeUser: (userId: string, platform?: string) => Promise<any>;
getShowPages: () => Promise<any>;
getShowPageAccess: (sessionId: string) => Promise<ShowPageAccess>;
probeShowPageAccess: (sessionId: string) => Promise<ShowPageAccessProbe>;
getShowAccessSettings: (sessionId: string) => Promise<ShowAccessSettingsResult>;
applyShowAccess: (
sessionId: string,
payload: ShowAccessApplyRequest,
) => Promise<ShowAccessApplyResult>;
/** The caller's notification switches (docs/plans/workbench-refinements.md §1). */
getNotificationPreferences: () => Promise<NotificationPreferences>;
/** Writes only the switches named; the server merges them into the stored record. */
updateNotificationPreferences: (changes: Partial<NotificationPreferences>) => Promise<NotificationPreferences>;
getWebPushStatus: (payload?: WebPushStatusPayload) => Promise<WebPushStatus>;
getWebPushVapidPublicKey: () => Promise<{ ok: boolean; public_key: string }>;
subscribeWebPush: (
subscription: PushSubscriptionJSON,
deviceLabel?: string,
deviceId?: string,
previousEndpoints?: string[],
backgroundRotation?: boolean,
) => Promise<WebPushSubscriptionResult>;
unsubscribeWebPush: (endpoint: string, deviceId?: string) => Promise<{ ok: boolean; disabled: boolean }>;
sendWebPushTest: (payload?: { title?: string; body?: string; url?: string; endpoint?: string }) => Promise<WebPushTestResult>;
setShowPageAvailability: (sessionId: string, offline: boolean) => Promise<any>;
/** Read the session's Show Page without creating it; rejects with
* `show_page_not_found` — silently, as an expected answer — when there is none.
* Everything that only DISPLAYS the page uses this — `ensureShowPage` is reserved
* for the one caller that owns the first-creation prompt. */
getShowPage: (sessionId: string) => Promise<ShowPagePayload>;
/** Create the session's Show Page if absent; resolves to `{ existed, ... }`. Callers
* MUST honor `existed === false` by sending the visualize prompt: that edge is
* reported once, so a caller that ignores it silently consumes it. To only read the
* page, use `getShowPage`. */
ensureShowPage: (sessionId: string) => Promise<any>;
/** Upload an image as the page's workspace-root favicon (multipart); resolves to the
* refreshed page payload carrying the fresh `icon_version` (§7.1j). */
uploadShowPageIcon: (sessionId: string, file: File) => Promise<any>;
/** The workbench Dock document (resident-tile order + pinned Show Pages). */
getDock: () => Promise<DockResponse>;
/** Pin a session's Show Page to the Dock as an app (idempotent). */
pinDockShowPage: (sessionId: string) => Promise<DockResponse>;
/** Unpin a session's Show Page from the Dock (idempotent; leaves the page). */
unpinDockShowPage: (sessionId: string) => Promise<DockResponse>;
/** Persist a new resident-tile (docked-subset) order. ``known`` is the client's
* baseline id set (built-ins ∪ pins) for optimistic concurrency: a stale
* reorder is rejected server-side and re-synced without a toast. Returns the
* payload; check ``ok``. */
setDockOrder: (order: string[], known?: string[]) => Promise<DockResponse>;
/** Global workbench toggles (state_meta-backed): banner on/off. */
getWorkbenchPrefs: () => Promise<WorkbenchPrefs>;
/** Persist the background-work banner global toggle; resolves to updated prefs. */
setBackgroundWorkBannerEnabled: (enabled: boolean) => Promise<WorkbenchPrefs>;
/** Persist whether new Web Sessions start with fast mode on; resolves to updated prefs. */
setFastModeDefault: (enabled: boolean) => Promise<WorkbenchPrefs>;
getBindCodes: () => Promise<any>;
createBindCode: (type: string, expiresAt?: string) => Promise<any>;
deleteBindCode: (code: string) => Promise<any>;
getFirstBindCode: () => Promise<any>;
detectCli: (binary: string, backend?: string) => Promise<CliDetectionResult>;
installAgent: (name: string) => Promise<InstallResult>;
listDependencies: (options?: DependencyReadOptions) => Promise<DependenciesResult>;
getMacOSLoginSessionStatus: () => Promise<MacOSLoginSessionStatus>;
installDependency: (dep: string) => Promise<InstallResult>;
getBackendConnection: (name: AgentBackendId) => Promise<BackendConnectionState>;
getBackendRuntime: (name: string, cliPath?: string) => Promise<BackendRuntimeInfo>;
restartBackend: (name: string) => Promise<BackendRestartResult>;
getCodexAuth: () => Promise<CodexAuthState>;
saveCodexAuth: (payload: CodexAuthPayload) => Promise<CodexAuthSaveResult>;
getClaudeAuth: () => Promise<ClaudeAuthState>;
saveClaudeAuth: (payload: ClaudeAuthPayload) => Promise<ClaudeAuthSaveResult>;
startOAuthWeb: (backend: 'claude' | 'codex', forceReset?: boolean) => Promise<OAuthWebStartResult>;
startOAuthWebForOpencodeProvider: (
providerId: string,
forceReset?: boolean,
) => Promise<OAuthWebStartResult>;
getOAuthWebStatus: (
backend: WebOAuthBackend,
flowId: string,
) => Promise<OAuthWebStatus>;
submitOAuthWebCode: (
backend: WebOAuthBackend,
flowId: string,
code: string,
) => Promise<OAuthWebMutationResult>;
cancelOAuthWeb: (
backend: WebOAuthBackend,
flowId: string,
) => Promise<OAuthWebMutationResult>;
removeBackendAuth: (backend: 'claude' | 'codex') => Promise<OAuthWebMutationResult>;
removeClaudeOAuthCredentials: () => Promise<OAuthWebMutationResult>;
// Selectively clear just the stored API key — leave OAuth credentials
// intact. Symmetric to OpenCode's per-provider DELETE: lets the user
// drop a stale key without re-signing in. The backend runtime is
// refreshed so cached sessions observe the change on the next request.
removeBackendApiKey: (backend: 'claude' | 'codex') => Promise<OAuthWebMutationResult>;
testBackendAuth: (
backend: 'claude' | 'codex',
options?: { model?: string },
) => Promise<BackendAuthTestResult>;
testOpencodeProvider: (
providerId: string,
options?: { model?: string },
) => Promise<BackendAuthTestResult>;
getOpencodeProviders: () => Promise<OpencodeProviderListResult>;
readOpencodeOptionsForModelPicker: () => Promise<OpencodeOptionsResult>;
saveOpencodeCustomProvider: (
payload: OpencodeCustomProviderPayload,
) => Promise<OpencodeMutationResult>;
deleteOpencodeCustomProvider: (providerId: string) => Promise<OpencodeMutationResult>;
setOpencodeProviderAuth: (
providerId: string,
apiKey?: string,
baseUrl?: string | null,
) => Promise<OpencodeMutationResult>;
deleteOpencodeProviderAuth: (providerId: string) => Promise<OpencodeMutationResult>;
setOpencodeDefaultProvider: (providerId: string) => Promise<OpencodeMutationResult>;
saveOpencodeProviderModel: (
providerId: string,
payload: { model_id: string; reasoning_efforts?: string[] },
) => Promise<OpencodeMutationResult>;
deleteOpencodeProviderModel: (
providerId: string,
modelId: string,
) => Promise<OpencodeMutationResult>;
slackAuthTest: (botToken?: string, proxyUrl?: string) => Promise<any>;
slackChannels: (botToken?: string, browseAll?: boolean, force?: boolean, includeNotReturned?: boolean) => Promise<any>;
slackManifest: () => Promise<{ ok: boolean; manifest?: string; manifest_compact?: string; error?: string }>;
discordAuthTest: (botToken?: string, proxyUrl?: string) => Promise<any>;
discordGuilds: (botToken?: string) => Promise<any>;
discordChannels: (botToken: string | undefined, guildId: string, force?: boolean, includeNotReturned?: boolean) => Promise<any>;
telegramAuthTest: (botToken?: string, proxyUrl?: string) => Promise<any>;
telegramChats: (includePrivate?: boolean, includeNotReturned?: boolean) => Promise<any>;
larkAuthTest: (appId: string, appSecret?: string, domain?: string, proxyUrl?: string) => Promise<any>;
larkChats: (appId: string, appSecret?: string, domain?: string, force?: boolean, includeNotReturned?: boolean) => Promise<any>;
deleteChannel: (platform: string, id: string, scopeType?: string) => Promise<any>;
larkTempWsStart: (appId: string, appSecret?: string, domain?: string) => Promise<any>;
larkTempWsStop: () => Promise<any>;
wechatStartLogin: () => Promise<any>;
wechatPollLogin: (sessionKey: string, verifyCode?: string) => Promise<any>;
doctor: (options?: { deep?: boolean }) => Promise<any>;
opencodeOptions: (cwd: string) => Promise<any>;
opencodeSetupPermission: () => Promise<{ ok: boolean; message: string; config_path: string }>;
opencodePermissionStatus: () => Promise<{ ok: boolean; permission_allowed: boolean; config_path: string }>;
claudeAgents: (cwd?: string) => Promise<{ ok: boolean; agents?: { id: string; name: string; path: string; source?: string }[]; error?: string }>;
claudeModels: () => Promise<{ ok: boolean; models?: string[]; reasoning_options?: Record<string, { value: string; label: string }[]>; model_labels?: Record<string, string>; catalog_refresh_pending?: boolean; error?: string }>;
codexAgents: (cwd?: string) => Promise<{ ok: boolean; agents?: { id: string; name: string; path: string; source?: string; description?: string }[]; error?: string }>;
codexModels: () => Promise<{ ok: boolean; models?: string[]; reasoning_options?: Record<string, { value: string; label: string }[]>; model_labels?: Record<string, string>; catalog_refresh_pending?: boolean; error?: string }>;
/** Picker-safe persisted catalog. Null tells pickers to use the native fallback. */
readModelHubAgentCatalogForModelPicker: (
backend: string,
) => Promise<PickerAgentCatalog | null>;
getLogs: (lines?: number, source?: string) => Promise<{ logs: LogEntry[]; total: number; source: string; sources: LogSource[] }>;
getVersion: (options?: { cache?: boolean; background?: boolean; signal?: AbortSignal }) => Promise<VersionInfo>;
requestDesktopUpdate: (
targetVersion: string,
options?: { confirmInterrupt?: boolean },
) => Promise<DesktopRemoteUpdateResult>;
doUpgrade: (options?: { confirmInterrupt: boolean }) => Promise<UpgradeResult>;
browseDirectory: (path: string, showHidden?: boolean) => Promise<{ ok: boolean; path?: string; parent?: string | null; dirs?: { name: string; path: string }[]; error?: string }>;
browseFavorites: () => Promise<{ ok: boolean; system?: string; favorites?: { key: string; path: string }[]; error?: string }>;
browseMkdir: (path: string) => Promise<{ path: string }>;
listProjects: (includeArchived?: boolean, options?: { cache?: boolean }) => Promise<{ projects: WorkbenchProject[] }>;
reorderProjects: (order: string[], expectedOrder: string[]) => Promise<{ projects: WorkbenchProject[] }>;
getWorkbenchProjectsBootstrap: (params?: {
includeArchived?: boolean;
projectIds?: string[];
status?: 'active' | 'archived' | 'all';
limit?: number;
cache?: boolean;
}) => Promise<WorkbenchProjectsBootstrap>;
createProject: (payload: { folder_path: string; display_name?: string }) => Promise<WorkbenchProject>;
// Default-Agent fields accept null to CLEAR the project default (back to the
// global default); omit a field to leave it untouched.
updateProject: (
projectId: string,
payload: {
display_name?: string;
folder_path?: string;
agent_backend?: string | null;
agent_id?: string | null;
expected_agent_id?: string | null;
agent_name?: string | null;
agent_variant?: string | null;
model?: string | null;
reasoning_effort?: string | null;
},
) => Promise<WorkbenchProject>;
archiveProject: (projectId: string) => Promise<WorkbenchProject>;
getProjectAgentsMd: (projectId: string) => Promise<{
content: string;
source: 'agents' | 'claude' | 'none';
symlinked: boolean;
claude_is_regular_file: boolean;
}>;
saveProjectAgentsMd: (
projectId: string,
payload: { content: string; symlink: boolean },
) => Promise<{ ok: boolean; symlinked: boolean; claude_is_regular_file: boolean; migrated: boolean; symlink_error: string | null }>;
getGlobalPrompts: () => Promise<{ backends: GlobalPromptFile[] }>;
saveGlobalPrompts: (
payload: { content: string; backends: string[] },
) => Promise<{ ok: boolean; backends: GlobalPromptFile[] }>;
listSessions: (params?: { projectId?: string; status?: 'active' | 'archived' | 'all'; limit?: number; beforeId?: string; q?: string; cache?: boolean }) => Promise<{ sessions: WorkbenchSession[]; next_before_id: string | null }>;
createSession: (payload: WorkbenchSessionCreate) => Promise<WorkbenchSession>;
forkSession: (sessionId: string) => Promise<WorkbenchSession>;
getSession: (sessionId: string, params?: { cache?: boolean; handleError?: boolean }) => Promise<WorkbenchSession>;
/** Resolve the stable main session for the current authorization context. */
getMainSession: () => Promise<WorkbenchSessionReadResult>;
/** The caller's desktop mini conversation with Vibey, created on first use
* in their most recently active chat Project. */
ensureDesktopMiniSession: () => Promise<WorkbenchSession>;
getSessionResult: (sessionId: string) => Promise<WorkbenchSessionReadResult>;
getSessionBootstrap: (sessionId: string) => Promise<WorkbenchSessionBootstrap>;
updateSession: (sessionId: string, payload: Partial<WorkbenchSessionUpdate>) => Promise<WorkbenchSession>;
archiveSession: (sessionId: string) => Promise<WorkbenchSession>;
/** Apply the terminal archived state for raw request paths that intentionally
* bypass the shared JSON error handler. */
convergeSessionArchived: (sessionId: string) => void;
/** Subscribe to "the server just refused a write because that session is
* archived". Fires for EVERY request whose error body carries
* ``session_archived``, whatever the verb — the messages POST, the sessions
* PATCH, fork, and every Show Page mutation — so a surface holding a stale
* pre-archive row converges once, here, instead of each call site
* re-implementing it (and the next verb re-introducing the same defect).
* Returns an unsubscribe. */
onSessionArchived: (handler: (sessionId: string) => void) => () => void;
/** Counts of resources permanently reclaimed when archiving this session
* (bound tasks/watches + active runs) — drives the irreversible-confirm dialog. */
getArchivePreview: (sessionId: string) => Promise<{ tasks: number; watches: number; runs: number; queued: number }>;
listSessionMessages: (sessionId: string, params?: { afterId?: string; beforeId?: string; aroundId?: string; aroundNativeId?: string; aroundNativePlatform?: string; aroundTurnId?: string; aroundRunId?: string; limit?: number; tail?: boolean; cache?: boolean }) => Promise<{ messages: WorkbenchMessage[]; next_after_id: string | null; next_before_id?: string | null; anchor_id?: string | null }>;
// Chat Activity panel (GET /api/sessions/<id>/activity): summary of turn groups
// for chips, and one group's rows for lazy expand. Only used when the
// ``ui.show_agent_activity`` toggle is on (see lib/agentActivity).
getSessionActivity: (sessionId: string) => Promise<{ groups: TurnActivityGroupWire[] }>;
getSessionActivityGroup: (sessionId: string, groupId: string) => Promise<TurnActivityGroupWire>;
// Full-text search over message content across all sessions. Backed by the
// non-cached GET /api/search/messages (the query string varies per keystroke,
// so caching would only bloat the read cache). Results group matches by
// session, sessions ordered most-recent-match first. ``includeArchived`` opts
// archived sessions in (they stay excluded by default); archived groups are
// flagged and open read-only.
searchMessages: (
q: string,
opts?: { limit?: number; includeArchived?: boolean },
) => Promise<MessageSearchResult>;
sendSessionMessage: (sessionId: string, payload: { text?: string; content?: Record<string, unknown>; metadata?: Record<string, unknown>; author_id?: string; author_name?: string; retry_for?: string }) => Promise<WorkbenchMessage>;
markSessionRead: (sessionId: string, untilMessageId?: string, opts?: { handleError?: boolean }) => Promise<{ updated: number; unread_counts: Record<string, number>; unread_by_session?: Record<string, number> }>;
cancelSession: (
sessionId: string,
) => Promise<{
ok: boolean;
status?: string;
code?: string;
detail?: string;
recovered_agent_status?: boolean;
}>;
// Send-while-busy queue (messages sent while a turn runs) + per-session draft.
listSessionQueue: (sessionId: string, options?: { cache?: boolean }) => Promise<{ queued: WorkbenchMessage[] }>;
removeQueuedMessage: (sessionId: string, messageId: string) => Promise<{ removed: boolean }>;
sendQueuedNow: (sessionId: string, messageId: string) => Promise<{ ok: boolean; status?: string; reason?: string; code?: string; detail?: string }>;
getTurnState: (sessionId: string, options?: { handleError?: boolean }) => Promise<SessionRuntimeState>;
getCachedSessionDraft: (sessionId: string) => string | null;
cacheSessionDraft: (sessionId: string, text: string) => void;
getSessionDraft: (sessionId: string) => Promise<{ text: string }>;
setSessionDraft: (sessionId: string, text: string) => Promise<{ ok: boolean }>;
reconcileSessionDraftAfterSend: (
sessionId: string,
draft: { text: string; updated_at: string | null },
) => Promise<void>;
recoverSessionDraftAfterRejectedSend: (sessionId: string) => Promise<void>;
listInbox: (params?: { platform?: string; unreadOnly?: boolean; limit?: number; before?: string; onlySession?: string; cache?: boolean; handleError?: boolean; backgroundPush?: boolean }) => Promise<InboxFeedResult>;
connectWorkbenchEvents: (handlers: WorkbenchEventHandlers) => () => void;
// Bots (docs/plans/bots.md "Web API"): every route is the instance Owner's. The
// writes reject with an ``ApiError`` carrying the server's localized message and
// code, and raise no toast: the Bot dialogs show the refusal where it was made.
listBots: (params?: { cache?: boolean }) => Promise<Bot[]>;
createBot: (payload: {
display_name: string;
handle?: string | null;
role?: string | null;
avatar?: BotEmojiAvatarInput | null;
model?: string | null;
reasoning_effort?: string | null;
}) => Promise<Bot>;
setBot: (payload: { agent_name: string; display_name: string; avatar?: BotEmojiAvatarInput | null }) => Promise<Bot>;
updateBot: (
handle: string,
payload: { display_name?: string; avatar?: BotEmojiAvatarInput | null; position?: number },
) => Promise<Bot>;
removeBot: (handle: string) => Promise<void>;
uploadBotAvatar: (handle: string, image: Blob) => Promise<Bot>;
suggestBotHandle: (
payload: { display_name: string; role?: string },
options?: { signal?: AbortSignal },
) => Promise<{ handle: string; source: string }>;
listVibeAgents: (params?: {
backend?: string;
includeDisabled?: boolean;
includeArchived?: boolean;
cache?: boolean;
}) => Promise<{ ok: boolean; agents: VibeAgentBrief[]; default_agent_name: string | null }>;
getVibeAgentOnboarding: () => Promise<VibeAgentOnboardingResult>;
onboardVibeAgents: () => Promise<VibeAgentOnboardingResult>;
getVibeAgent: (
name: string,
params?: { cache?: boolean; handleError?: boolean; expectedCodes?: readonly string[] },
) => Promise<{ ok: boolean; agent: VibeAgentFull; default_agent_name: string | null }>;
createVibeAgent: (payload: VibeAgentCreatePayload) => Promise<{ ok: boolean; agent: VibeAgentFull }>;
updateVibeAgent: (name: string, payload: VibeAgentUpdatePayload) => Promise<{ ok: boolean; agent: VibeAgentFull }>;
setDefaultVibeAgent: (name: string) => Promise<{ ok: boolean; default_agent_name: string; agent: VibeAgentBrief }>;
removeVibeAgent: (name: string) => Promise<{ ok: boolean; code?: string; message?: string; references?: Record<string, number>; removed_agent?: string; archived_agent?: VibeAgentBrief; default_agent_name?: string | null }>;
listVaultSecrets: (opts?: { cache?: boolean }) => Promise<{ ok: boolean; secrets: VaultSecret[] }>;
getVaultVmk: () => Promise<VaultVmkResult>;
getVaultPubkey: () => Promise<{ ok: boolean; public_key: string; fingerprint: string }>;
getVaultAgentPubkey: () => Promise<{ ok: boolean; public_key: string; fingerprint: string }>;
getAvaultAuthorization: () => Promise<AvaultAuthorizationStatus>;
/** Starts the one-time macOS Keychain authorization, or joins the one already running. */
authorizeAvault: () => Promise<AvaultAuthorizationStatus>;
getVaultSandboxRootMetadata: () => Promise<VaultSandboxRootMetadataResult>;
/** One batch of signed agent-delivery contexts for every protected member of a request (§7.1). */
createVaultAgentBindingsBatch: (payload: {
request_id: string;
grant_duration?: VaultGrantDuration;
}) => Promise<VaultAgentBindingsBatchResult>;
getVaultSettings: () => Promise<VaultSettingsResult>;
saveVaultSettings: (payload: Partial<VaultSettings>) => Promise<VaultSettingsResult>;
createVaultRevealContext: (
name: string,
payload?: { session_label?: string; field?: string },
) => Promise<VaultRevealContextResult>;
deriveSigningAddresses: (publicKey: string) => Promise<{ ok: boolean; addresses?: SigningAddresses; code?: string; message?: string }>;
createVaultAuthzWebAuthnOptions: () => Promise<VaultWebAuthnRegistrationOptions>;
registerVaultAuthzWebAuthnFactor: (
payload: VaultWebAuthnRegistrationPayload,
) => Promise<{ ok: boolean; factor?: Record<string, unknown>; code?: string; message?: string }>;
createVaultSecret: (payload: VaultCreatePayload, opts?: { handleError?: boolean }) => Promise<{ ok: boolean; secret?: VaultSecret; code?: string; message?: string }>;
updateVaultSecret: (name: string, payload: VaultMetadataUpdatePayload, opts?: { handleError?: boolean }) => Promise<{ ok: boolean; secret?: VaultSecret; code?: string; message?: string }>;
updateVaultSecretField: (name: string, field: string, payload: VaultFieldValuePayload, opts?: { handleError?: boolean }) => Promise<{ ok: boolean; secret?: VaultSecret; code?: string; message?: string }>;
deleteVaultSecretField: (name: string, field: string, payload: { expected_updated_at: string }) => Promise<{ ok: boolean; secret?: VaultSecret; code?: string; message?: string }>;
deleteVaultSecret: (name: string) => Promise<{ ok: boolean; removed?: boolean; code?: string; message?: string }>;
getVaultProvisionRequest: (
name: string,
opts?: { handleError?: boolean },
) => Promise<{ ok: boolean; request: VaultRequest | null; ambiguous?: boolean }>;
getVaultProvisionRequestById: (requestId: string, opts?: { handleError?: boolean }) => Promise<{ ok: boolean; request: VaultRequest | null }>;
getVaultRequests: (params?: { status?: string; type?: string; limit?: number; session?: string }, opts?: { handleError?: boolean }) => Promise<{ ok: boolean; requests: VaultRequest[] }>;
denyVaultRequest: (requestId: string) => Promise<{ ok: boolean; request?: VaultRequest; code?: string; message?: string }>;
approveVaultDeleteRequest: (requestId: string) => Promise<{ ok: boolean; request?: VaultRequest; removed?: boolean; name?: string; code?: string; message?: string }>;
fulfillVaultAccessRequest: (requestId: string, payload: VaultAccessFulfillmentPayload) => Promise<{ ok: boolean; request_id?: string; grant?: VaultGrant; result?: { type: string; grant?: VaultGrant }; code?: string; message?: string }>;
getVaultGrants: (params?: { status?: string; sessionId?: string }, opts?: { handleError?: boolean }) => Promise<{ ok: boolean; grants: VaultGrant[] }>;
createVaultGrant: (payload: Record<string, unknown>) => Promise<{ ok: boolean; grant: VaultGrant; code?: string; message?: string }>;
revokeVaultGrant: (grantId: string) => Promise<{ ok: boolean; grant?: VaultGrant; code?: string; message?: string }>;
signVaultDigest: (payload: Record<string, unknown>) => Promise<{ ok: boolean; signature?: Record<string, unknown>; request?: VaultRequest; code?: string; message?: string }>;
pinVaultPubkey: (payload: Record<string, unknown>) => Promise<{ ok: boolean; secret?: VaultSecret; code?: string; message?: string }>;
getVaultAudit: (params?: { secret?: string; limit?: number }) => Promise<{ ok: boolean; events: VaultAuditEvent[] }>;
importVibeAgents: (payload: { from?: NativeCliBackend; name?: string; all?: boolean; file?: string; backend?: string }) => Promise<{ ok: boolean; imported?: any[]; skipped?: any[]; error?: string; code?: string; message?: string }>;
// Agent Skills — thin shells over the askill CLI (see /api/skills*).
listSkills: (params?: { scope?: SkillScope | 'all'; projectId?: string; backends?: string[] }) => Promise<SkillsListResult>;
listMcpServers: () => Promise<McpResult & { servers?: McpServerSummary[]; oauthMode?: 'direct' | 'paste' }>;
addMcp: (text: string) => Promise<McpResult & {
saved?: string[];
name?: string;
toolCount?: number;
added?: { name: string; toolCount?: number; auth?: McpServerSummary['auth'] }[];
unchanged?: { name: string; auth?: McpServerSummary['auth'] }[];
failed?: { name: string; error?: string; type?: string }[];
}>;
discoverMcp: () => Promise<McpResult & { results?: { name: string; status: string; error?: string; toolCount?: number }[] }>;
refreshMcp: (name: string) => Promise<McpResult & { name?: string; toolCount?: number }>;
removeMcp: (name: string) => Promise<McpResult>;
completeMcpLogin: (name: string, callbackUrl: string) => Promise<McpOAuthMutationResult>;
getMcpServer: (name: string) => Promise<McpResult & { server?: McpServerSummary; tools?: McpTool[] }>;
previewSkillSource: (source: string, params?: { projectId?: string }) => Promise<SkillsPreviewResult>;
addSkill: (payload: { source: string; scope: SkillScope; projectId?: string; backends?: string[]; all?: boolean; skill?: string; copy?: boolean }) => Promise<SkillsMutationResult>;
removeSkill: (name: string, params?: { scope?: SkillScope; projectId?: string; backends?: string[] }) => Promise<SkillsMutationResult>;
findSkills: (query: string) => Promise<SkillsFindResult>;
uploadSkillZip: (file: File, params?: { projectId?: string }) => Promise<SkillsUploadResult>;
checkSkills: (params?: { scope?: SkillScope; projectId?: string }) => Promise<SkillsCheckResult>;
updateSkill: (name: string, params?: { scope?: SkillScope; projectId?: string }) => Promise<SkillsMutationResult>;
getHarnessCounts: () => Promise<HarnessCountsResult>;
getHarnessBootstrap: (params?: HarnessBootstrapParams) => Promise<HarnessBootstrapResult>;
// ``opts.handleError: false`` suppresses the global error toast (and bypasses
// the read cache) for best-effort background polls — e.g. the open trigger
// detail panel's 4s refresh, which must not toast on every tick when an
// endpoint is down. Matches the getSession/vault handleError idiom.
listHarnessTasks: (params?: HarnessDefinitionsParams, opts?: { handleError?: boolean }) => Promise<HarnessTasksResult>;
setHarnessTaskEnabled: (taskId: string, enabled: boolean) => Promise<{ ok: boolean; task?: HarnessTask }>;
deleteHarnessTask: (taskId: string) => Promise<{ ok: boolean; id?: string }>;
listHarnessWatches: (params?: HarnessDefinitionsParams, opts?: { handleError?: boolean }) => Promise<HarnessWatchesResult>;
setHarnessWatchEnabled: (watchId: string, enabled: boolean) => Promise<{ ok: boolean; watch?: HarnessWatch }>;
deleteHarnessWatch: (watchId: string) => Promise<{ ok: boolean; id?: string }>;
listHarnessRuns: (params?: HarnessRunsParams, opts?: { handleError?: boolean }) => Promise<HarnessRunsResult>;
getHarnessRun: (runId: string) => Promise<{ ok: boolean; run: HarnessRun }>;
getRunningAgents: () => Promise<RunningAgentsResult>;
// Agents · 运行图 graph payload (contract §3). Realtime — refetched off SSE,
// so it bypasses the read cache. ``live_unreachable`` is set when the
// controller is down and the graph fell back to DB-only (history).
getAgentsGraph: (params?: AgentGraphParams) => Promise<AgentGraphResult & { live_unreachable?: boolean }>;
// Foreground/background toggle from the graph detail panel (contract §2,
// M1-owned PATCH). Returns the updated session payload.
setSessionVisibility: (sessionId: string, visibility: AgentGraphVisibility) => Promise<WorkbenchSession>;
endRunningAgent: (payload: {
backend?: string | null;
state?: string | null;
session_id?: string | null;
composite_key?: string | null;
base_session_id?: string | null;
pid?: number | null;
}) => Promise<{ ok: boolean; unreachable?: boolean; error?: string; action?: string }>;
remoteAccessStatus: () => Promise<RemoteAccessStatus>;
pairVibeCloudRemoteAccess: (payload: { backend_url: string; pairing_key: string; device_name?: string }) => Promise<any>;
startRemoteAccess: () => Promise<RemoteAccessStatus>;
stopRemoteAccess: () => Promise<RemoteAccessStatus>;
optimizeRemoteAccessRoute: () => Promise<RemoteAccessStatus>;
getRemoteAccessNetworkInterfaces: () => Promise<{ ok: boolean; interfaces: TunnelNetworkInterface[] }>;
saveRemoteAccessSettings: (settings: RemoteAccessSettings) => Promise<RemoteAccessStatus>;
diagnoseRemoteAccess: () => Promise<TunnelConnectivityDiagnostics>;
getAuthSession: () => Promise<SessionInfo>;
signOut: () => Promise<{ ok: boolean }>;
};
// Workbench project — a scope row with platform='avibe' / scope_type='project'.
// ``folder_path`` mirrors ``scope_settings.workdir`` and is what Agent runs
// pick up as their cwd.
// A project's default Agent route (backend + agent + model + effort), stored on
// the project and inherited by new sessions created under it. ``null`` (or an
// absent field) means "no project default" → fall back to the global default.
export type ProjectDefaultAgent = {
agent_backend: string | null;
agent_id: string | null;
agent_name: string | null;
agent_variant: string | null;
model: string | null;
reasoning_effort: string | null;
};
export type WorkbenchProject = {
id: string;
scope_id: string;
display_name: string;
folder_path: string;
created_at: string;
last_active_at: string | null;
archived: boolean;
default_agent?: ProjectDefaultAgent | null;
metadata?: Record<string, unknown>;
capabilities: {
can_chat: boolean;
has_folder: boolean;
};
};
export type ProjectSessionsPage = {
sessions: WorkbenchSession[];
next_before_id: string | null;
};
export type WorkbenchProjectsBootstrap = {
projects: WorkbenchProject[];
sessions: Record<string, ProjectSessionsPage | undefined>;
};
// Workbench session — a row in ``agent_sessions`` created via /api/sessions.
// ``project_id`` is the short ``proj_<hex>`` suffix of ``scope_id``.
export type WorkbenchSession = {
id: string;
scope_id: string | null;
project_id: string | null;
title: string | null;
agent_id: string | null;
agent_name: string | null;
agent_backend: string | null;
agent_variant: string | null;
model: string | null;
reasoning_effort: string | null;
/** Optional because payloads cached by an older client predate the field. */
speed?: SessionSpeed;
status: string;
/** Storage projection, not a user preference: ``foreground`` = an ordinary chat,
* ``background`` = hidden and undelivered, ``system`` = a row the RUNTIME owns
* (kept out of session lists, still an Inbox destination — today the
* workspace-notifications session, which accepts no turn, see
* ``sessionReadOnlyReason``). Optional because payloads cached by an older client
* predate the field; the server always sends it. */
visibility?: 'foreground' | 'background' | 'system';
pinned: boolean;
/** Live agent-runtime status driving the sidebar dot: idle (gray) /
* running (green) / failed (red). Distinct from the lifecycle ``status``. */
agent_status: 'idle' | 'running' | 'failed';
workdir: string | null;
native_session_id: string | null;
created_at: string;
updated_at: string;
last_active_at: string | null;
metadata: Record<string, unknown>;
};
export type WorkbenchSessionReadResult = {
status: number;
session: WorkbenchSession | null;
/** Project-level chat grant; omitted when the payload has no usable flag. */
capabilities?: { can_chat: boolean };
};
/** GET /api/sessions/:id carries capabilities as a sibling of the row fields. */
function sessionCanChatFromPayload(payload: { capabilities?: { can_chat?: unknown } } | null): { can_chat: boolean } | undefined {
return payload?.capabilities && typeof payload.capabilities.can_chat === 'boolean'
? { can_chat: payload.capabilities.can_chat }
: undefined;
}
function sessionRowFromPayload(payload: WorkbenchSession & { capabilities?: unknown }): WorkbenchSession {
if (!payload || typeof payload !== 'object') return payload;
const { capabilities: _capabilities, ...row } = payload;
return row;
}
export type WorkbenchSessionCreate = {
project_id: string;
// Optional: when omitted the server resolves the current default Agent.
agent_backend?: string;
agent_id?: string;
agent_name?: string;
agent_variant?: string;
model?: string;
reasoning_effort?: string;
speed?: 'fast';
title?: string;
metadata?: Record<string, unknown>;
};
export type WorkbenchSessionUpdate = {
title: string | null;
agent_id: string | null;
agent_name: string | null;
// Session execution snapshot, not a scope/default route selector.
agent_backend: string;
agent_variant: string;
model: string | null;
reasoning_effort: string | null;
speed: SessionSpeed;
pinned: boolean;
};
// One Vibe Agent row from ``/agents`` (brief view used in list rendering).
// ``source`` distinguishes system-builtin agents from user-created ones —
// system agents lock the ``backend`` field and refuse delete, but their
// model / effort / system_prompt / enabled state are still editable.
export type VibeAgentBrief = {
id: string;
name: string;
display_name: string;
description: string | null;
backend: string;
model: string | null;
reasoning_effort: string | null;
enabled: boolean;
archived: boolean;
archived_at: string | null;
source: string;
updated_at: string;
/** The Bot this Agent is, if any (docs/plans/bots.md D1). Absent on older servers. */
bot?: AgentBotSummary | null;
};
export type VibeAgentFull = VibeAgentBrief & {
system_prompt: string | null;
metadata: Record<string, unknown>;
created_at: string;
};
export type VibeAgentOnboardingItem = {
id: string;
name: string;
backend: string;
source: string;
enabled: boolean;
status: 'not_onboarded' | 'private' | 'published' | 'managed_elsewhere';
access_level: 'private' | 'scope' | 'public' | null;
group_ids: string[];
policy_revision: number | null;
applied_acl_revision: number | null;
};
export type VibeAgentOnboardingResult = {
ok: boolean;
available: boolean;
organization_id: string | null;
console_url?: string;
agents: VibeAgentOnboardingItem[];
counts: {
total: number;
system: number;
custom: number;
not_onboarded: number;
private: number;
published: number;
conflicts: number;
};
created?: number;
unchanged?: number;
conflicts?: number;
sync?: { ok?: boolean; error?: string };
};
export type VibeAgentCreatePayload = {
name: string;
backend: string;
description?: string | null;
model?: string | null;
reasoning_effort?: string | null;
system_prompt?: string | null;
metadata?: Record<string, unknown>;
enabled?: boolean;
};
// Agent Skills (askill CLI). The backend returns the askill --json envelope,
// optionally enriched; logical failures come back as { ok: false, error }
// with HTTP 200 (callers branch on `ok`, like the agents endpoints).
export type SkillScope = 'global' | 'project';
export type AskillAgentRef = { id: string; name: string };
export type SkillsErrorBody = { code: string; message: string; details?: unknown };
export type SkillBrief = {
name: string;
scope: SkillScope;
path: string;
agents: AskillAgentRef[];
description?: string | null;
version?: string | null;
// Enriched natively by `list --json` (askill v0.1.13+).
tags?: string[];
sourceType?: string | null;
sourceUrl?: string | null;
installSource?: string | null;
installedAt?: string | null;
updatedAt?: string | null;
};
export type SkillsListResult = {
ok: boolean;
error?: SkillsErrorBody;
filters?: { scope: string; agents: AskillAgentRef[] };
summary?: { global: number; project: number };
skills?: SkillBrief[];
/** Set when the selected project has no folder configured: the backend
* returned global skills only (project-scoped skills aren't possible). */
project_no_folder?: boolean;
};
export type SkillAiBreakdown = { key: string; label: string; score: number };
export type SkillSearchItem = {
id: string | number;
name: string;
description: string;
owner: string;
repo: string | null;
tags: string[];
stars: number | null;
aiScore: number | null;
aiBreakdown: SkillAiBreakdown[];
updatedAt: string | null;
installSource: string;
url: string | null;
};
export type SkillsFindResult = {
ok: boolean;
error?: SkillsErrorBody;
query?: string;
count?: number;
skills?: SkillSearchItem[];
};
export type SkillDiscovered = { name: string; description: string; path?: string | null };
export type SkillsPreviewResult = {
ok: boolean;
error?: SkillsErrorBody;
action?: string;
source?: Record<string, unknown>;
skills?: SkillDiscovered[];
};
export type SkillsMutationResult = { ok: boolean; error?: SkillsErrorBody; [key: string]: unknown };
// Result of uploading a .zip: the server unpacks it and previews the skills
// inside; `dir` is the server-side path to install from via addSkill.
export type SkillsUploadResult = {
ok: boolean;
error?: SkillsErrorBody;
dir?: string;
skills?: SkillDiscovered[];
};
export type SkillCheckStatus = 'update_available' | 'up_to_date' | 'uncheckable';
export type SkillCheckItem = {
name: string;
scope: SkillScope;
status: SkillCheckStatus;
localVersion?: string | null;
remoteVersion?: string | null;
reason?: string | null;
};
export type SkillsCheckResult = {
ok: boolean;
error?: SkillsErrorBody;
summary?: { total: number; updateAvailable: number; upToDate: number; uncheckable: number };
skills?: SkillCheckItem[];
};
export type VibeAgentUpdatePayload = {
name?: string;
description?: string | null;
model?: string | null;
reasoning_effort?: string | null;
system_prompt?: string | null;
metadata?: Record<string, unknown>;
enabled?: boolean;
};
// Events streamed by ``GET /api/events`` — the broker JSON-encodes each
// payload as ``{type, data}`` (older servers may include ``ts``).
// ``connectWorkbenchEvents`` parses and dispatches to type-specific handlers;
// subscribers can also catch any event via ``onAny`` for logging/analytics.
export type WorkbenchEventEnvelope<T = unknown> = {
type: string;
data: T;
ts?: number;
};
export type WorkbenchEventHandlers = {
/**
* A stream is live and reaching this consumer, and any gap before now is
* over. Every gap ends here, on either of the two legs a stream is carried
* over: the browser socket breaking (an error, a page that came back to a
* stream that could not prove it survived, a heartbeat that stopped arriving)
* is recovered by reconnecting, and this fires once the new subscription
* exists; the UI server's controller bridge dropping and coming back is
* recovered in place, and this fires when it does. Nothing replays either
* gap, so this is also the one place to re-read whatever this consumer keeps
* live off the stream — including the window between its own first read and
* this subscription.
*
* Consumers must not re-derive when a gap happened. Neither the reactivation
* edge nor `onEventBridgeStatus` is that signal: a returning page whose stream
* never broke has missed nothing, and a bridge report is a level rather than
* an edge. Both verdicts are made in one place, and a consumer recomputing
* them will drift from it.
*
* It carries no payload, deliberately. Which leg came back, and whether any
* handshake stands behind this edge at all -- a page returning onto a stream
* that could not prove it survived says to catch up now, rather than wait for
* a replacement several backoff windows away -- are distinctions a catch-up
* cannot branch on without silently skipping the gaps it does not recognise.
* So there is nothing here to branch on. `onEventBridgeStatus` stays the level
* a bridge indicator renders from, and is not a second catch-up trigger: every
* bridge recovery arrives here too, so refetching from both would charge each
* one twice.
*/
onConnected?: () => void;
onProjectsChanged?: () => void;
/** The Owner's Bots changed (created, set, edited, reordered, removed): refetch
* ``GET /api/bots``. ``handle`` is a hint, not a filter. */
onBotsChanged?: (data: { handle?: string }) => void;
/** This account's notification switches changed, on this device or another.
* The server sends it only to the account's own streams; it is taken as a
* nudge to re-read, so the read path stays the one place a record is adopted. */
onNotificationPreferencesChanged?: () => void;
onConnectionState?: (state: WorkbenchEventConnectionState) => void;
onEventBridgeStatus?: (data: { connected: boolean }) => void;
onAuthorizationChanged?: (data: {
project_ids?: string[];
resource_kinds?: string[];
instance_authorization_revision?: number;
}) => void;
onMessageNew?: (data: WorkbenchMessage) => void;
onMessageUpdated?: (data: WorkbenchMessage) => void;
// ``visibility`` (contract A6): the backend carries the session's current
// foreground/background on visibility/scope changes so the Inbox can drop /
// restore the card live. Absent on pre-M1 backends ⇒ consumers no-op.
onSessionActivity?: (data: {
session_id: string;
scope_id: string | null;
event: string;
title?: string | null;
visibility?: 'foreground' | 'background';
pinned?: boolean;
// Client-synthesized marker (never on a real backend event): a foreground
// restore, so the projects tree grows its window to bring the row back.
restored?: boolean;
}) => void;
onInboxUnreadChanged?: (data: {
session_id?: string;
scope_id?: string | null;
delta?: number;
unread_counts: Record<string, number>;
unread_by_session?: Record<string, number>;
}) => void;
// A session's inbox card changed — new agent reply, or the user replied.
// Carries the recomputed per-session row so consumers upsert + re-sort in
// place without a refetch (the realtime "bump to top" signal).
onInboxSessionUpdated?: (data: InboxSession) => void;
// Session-level turn lifecycle (the controller is the authority): a turn for
// this session started / settled. Drives the Chat working indicator + Stop
// button without the browser having to infer turn end from message rows.
onTurnStart?: (data: { session_id: string }) => void;
onTurnEnd?: (data: { session_id: string }) => void;
// A session's live agent-runtime status changed (idle/running/failed) — the
// sidebar dot recolors from this without a refetch. Same controller→browser
// bus as turn.start/turn.end; published only when the value actually moves.
onSessionStatus?: (data: { session_id: string; agent_status: 'idle' | 'running' | 'failed' }) => void;
// The send-while-busy queue for a session changed (enqueue / flush / remove).
onQueueUpdated?: (data: { session_id: string }) => void;
// A Task / Watch definition was created, edited, enabled, paused or removed.
// Instance-scoped like the two below, and `definition_type` is a hint, not a
// filter: below runtime management the server reduces the frame to `{}`, so a
// consumer that reads the field must still refetch when it is absent.
onDefinitionsUpdated?: (data: { definition_type?: string }) => void;
onRunsUpdated?: (data: {
run_id: string;
status: HarnessRunStatus;
run_type?: string;
session_id?: string;
definition_id?: string;
updated_at?: string;
cancel_requested?: boolean;
}) => void;
onVaultsUpdated?: (data: {
scope: string;
request_id?: string;
request_status?: string;
grant_id?: string;
grant_status?: string;
secret_name?: string;
}) => void;
onRemoteAccessQuality?: (data: TunnelQualitySnapshot) => void;
onAny?: (event: WorkbenchEventEnvelope) => void;
onError?: (err: Event) => void;
};
// One row from the platform-agnostic ``messages`` table.
export type WorkbenchMessage = {
id: string;
scope_id: string | null;
session_id: string | null;
platform: string;
author: 'user' | 'agent' | 'system' | string;
// First-class message type: 'user' | 'harness' | 'assistant' | 'tool_call' |
// 'notify' | 'result'. Distinct from the coarse author — the chat renders
// 'notify' as a terminal status marker, and the inbox previews 'result' only.
type: 'user' | 'harness' | 'assistant' | 'tool_call' | 'notify' | 'result' | string;
// Origin of the message, distinct from the coarse ``author`` role: a
// harness-triggered prompt uses author/type='harness'. Drives the transcript's
// "Scheduled task" / "Watch" provenance tag.
source: 'user' | 'agent' | 'harness' | string | null;
author_id: string | null;
author_name: string | null;
// Read-side display name for a human sender on an Organization instance,
// resolved from author_id. Absent on a personal instance and whenever the
// sender cannot be resolved; never carries the underlying email address.
sender_label?: string | null;
// Read-side provenance for an agent-callback ("自动触发") harness message (A9a):
// the session that triggered the run, resolved from the run's source_actor.
// Present only on agent_run harness messages; enables the source-session chip
// + /chat/<source_session_id> deep-link.
source_session_id?: string | null;
source_session_title?: string | null;
source_session_agent_name?: string | null;
native_message_id: string | null;
parent_native_message_id: string | null;
// Server-owned read projection. Durable Message rows never carry this field.
projection?: 'claimed_delivery' | null;
// Queue/bootstrap include unaccepted steers as well as editable queued rows.
// Durable transcript Messages do not carry Delivery state.
state?: string;
// Server-owned queued Delivery recovery projection, not Message metadata.
requires_explicit_retry?: boolean;
retry_reason?: string | null;
text: string;
content: Record<string, unknown>;
metadata: Record<string, unknown>;
created_at: string;
updated_at: string;
delivered_at: string | null;
read_at: string | null;
};
// One highlighted message-content hit from GET /api/search/messages, split by
// the server so the UI never has to locate the match: ``prefix`` + ``match`` +
// ``suffix`` reconstruct a window of the message text, with ``match`` the part
// to highlight (empty when the snippet is just leading context).
export type MessageSnippet = {
prefix: string;
match: string;
suffix: string;
};
// A single matching message within a session group. The row chip derives its
// role from author/type/source so harness prompts remain distinct from both
// human input and agent output.
export type MessageSearchMatch = {
id: string;
author: string;
source: string | null;
type: 'user' | 'harness' | 'result' | string;
created_at: string;
snippet: MessageSnippet;
};
// Matches grouped by their session, with enough session/project context to
// render a group header and (in P3/P4) navigate into the chat at the match.
export type MessageSearchSession = {
session_id: string;
title: string | null;
project_id: string | null;
project_name: string | null;
// True when the session is archived (only possible with includeArchived) —
// the group is marked in the results and the chat opens read-only.
archived: boolean;
matches: MessageSearchMatch[];
};
export type MessageSearchResult = {
sessions: MessageSearchSession[];
total: number;
session_count: number;
};
// Union item for the background-work banner. Backend activities (from the
// process-local SessionActivityRegistry) and live-derived harness items
// (watches / scheduled tasks / delegated agent runs) share this shape. The
// legacy fields stay for backward compatibility; `item_kind` / `label` /
// `since` / `schedule_type` are the unified fields the banner renders and
// routes on. `item_kind` is optional so a pre-union payload degrades to a
// backend activity.
export type SessionActivityItemKind = 'backend_activity' | 'watch' | 'task' | 'agent_run';
export type SessionActivityState = {
id: string;
backend: string;
runtime_key: string;
session_id: string | null;
kind: string;
status: string;
description: string | null;
started_at: string;
updated_at: string;
item_kind?: SessionActivityItemKind;
label?: string | null;
since?: string;
schedule_type?: 'at' | 'cron' | null;
};
export type ModelRecoveryState = {
request_id: string;
phase: 'waiting' | 'attempting';
attempt_count: number;
started_at: string;
window_end: string;
source_id: string | null;
reason: string | null;
next_eligible_at: string | null;
};
export type SessionRuntimeState = {
in_flight: boolean | null;
foreground: 'idle' | 'running' | 'unknown';
native_turn_started: boolean;
pending_input_count: number;
background_activities: SessionActivityState[];
pending_activity_output_count: number;
connection: 'connected' | 'reconnecting' | 'disconnected' | 'unknown';
backend?: string;
recovered_agent_status?: boolean;
model_recovery?: ModelRecoveryState[];
};
export type WorkbenchSessionBootstrap = {
session: WorkbenchSession;
capabilities: { can_chat: boolean };
agents: VibeAgentBrief[];
default_agent_name: string | null;
config: any | null;
messages: WorkbenchMessage[];
next_after_id: string | null;
next_before_id?: string | null;
queued: WorkbenchMessage[];
draft: { text: string; updated_at: string | null };
turn_state: SessionRuntimeState;
};
function sessionDraftServerState(payload: unknown): SessionDraftServerState {
const draft = payload && typeof payload === 'object'
? payload as { text?: unknown; updated_at?: unknown }
: {};
return {
text: typeof draft.text === 'string' ? draft.text : '',
updatedAt: typeof draft.updated_at === 'string' ? draft.updated_at : null,
};
}
const SESSION_DRAFT_WRITE_TIMEOUT_MS = 12_000;
const SESSION_DRAFT_RECONCILE_TIMEOUT_MS = 5_000;
// One row of the per-session ("Slack-like") inbox feed from ``GET /api/inbox``.
// Aggregated per session at query time: ``preview_text`` is the session's latest
// agent ``result`` (aligned with the avibe chat, which only shows results),
// ``last_activity_at`` is the most recent message of *any* author (the sort
// key), and ``replied`` is true when the session is awaiting the agent — the
// user's latest message is newer than the agent's latest reply, so it stays set
// for the whole agent turn (even mid-stream) and clears only once the agent
// replies.
export type InboxSession = {
session_id: string;
scope_id: string | null;
project_id: string | null;
project_name: string | null;
title: string | null;
last_activity_at: string;
last_message_author: string | null;
replied: boolean;
preview_text: string;
preview_at: string | null;
unread_count: number;
unread: boolean;
/** Bot conversation or ordinary Session, by the server's Bot registry. */
category?: InboxCategory;
};
export type InboxFeedResult = {
sessions: InboxSession[];
next_cursor: string | null;
unread_by_session: Record<string, number>;
unread_total: number;
unread_sessions: number;
/** ``unread_total`` split by category. The page splits its own live map the
* same way (``lib/notificationPreferences``); these serve readers without one,
* such as the push worker. */
unread_by_category?: Record<InboxCategory, number>;
/** Unread in the caller's loud categories: the worker's and the desktop app's badge. */
badge_total?: number;
};
// =============================================================================
// Harness (scheduled tasks / watches / runs)
// =============================================================================
// Server-resolved view of a task/watch's bound session, for the cards. A
// workbench session carries a title; an IM session resolves to its platform +
// channel display name.
//
// ``session_is_workbench`` chooses the icon and which label to show.
// ``session_openable`` — and only it — decides whether the label is a link:
// ``/chat/<id>`` opens IM-bound sessions too, so linking on "is workbench" hid
// working destinations behind a bare id. One predicate answers it for every
// surface (``storage/agent_session_rows.py::session_openable_in_chat``).
export type HarnessSessionSummary = {
session_title: string | null;
session_platform: string | null;
session_scope_kind: string | null;
session_label: string | null;
session_is_workbench: boolean;
session_openable: boolean;
};
// What a task/watch is *doing*, derived server-side from columns that already
// exist. ``enabled`` is a switch and was being read as a state, which made a
// one-shot that finished on its own indistinguishable from one the user paused.
// ``lifecycle_detail`` is set only on ``finished`` rows and says how they ended.
export type HarnessLifecycleState = 'running' | 'waiting' | 'paused' | 'finished';
export type HarnessLifecycleDetail = 'normal' | 'timeout' | 'error' | 'missed' | 'canceled';
export type HarnessDefinitionHealth = 'failing' | 'degraded' | 'healthy' | 'unknown';
// The fields every task/watch row reads to describe its state.
export type HarnessDefinitionState = {
lifecycle_state: HarnessLifecycleState | null;
lifecycle_detail: HarnessLifecycleDetail | null;
// When the scheduler will fire this next; null when nothing is promised.
next_run_at: string | null;
// When the current wait began — set only while ``waiting``, so a paused row's
// last start reads as history rather than a wait anyone is still in.
waiting_since: string | null;
// When the run that makes this row ``running`` actually started. Null while
// that run is still queued, and null in every other state — a duration for
// "how long has this been running" must come from the run that is running,
// not from whenever the row last did anything.
running_since: string | null;
retired_at?: string | null;
lifecycle_finished_at?: string | null;
// Derived from this definition's own settled run outcomes, never from
// ``last_run_at``/``last_error``: those are overwritten on every fire, so one
// success used to erase days of failure and a daily-failing cron rendered
// identically to a daily-succeeding one.
//
// ``failing`` = the newest verdict failed. ``degraded`` = the newest succeeded
// but a failure is still inside the window — a success downgrades, it does not
// clear. ``unknown`` = health could not be computed, which must not read as a
// clean bill of health.
health: HarnessDefinitionHealth | null;
// How many verdicts back the failure run reaches, and how many failures are in
// the window at all. Both age out on their own; neither is acknowledgment state.
consecutive_failures: number;
recent_failures: number;
// Watches separate waiter health above from the Agent Runs created by events.
// Tasks omit these because their execution is already the definition health.
processing_health?: HarnessDefinitionHealth | null;
processing_consecutive_failures?: number;
processing_recent_failures?: number;
};
export type HarnessTask = HarnessSessionSummary & HarnessDefinitionState & {
id: string;
name: string | null;
agent_name: string | null;
session_policy: string | null;
session_id: string | null;
session_key: string;
prompt: string;
message: string;
message_payload: Record<string, unknown> | null;
schedule_type: string;
cron: string | null;
run_at: string | null;
timezone: string;
post_to: string | null;
deliver_key: string | null;
enabled: boolean;
created_at: string | null;
updated_at: string | null;
last_run_at: string | null;
last_run_id: string | null;
last_error: string | null;
resume_blocked?: {
code: string;
owner_session_id: string;
} | null;
// Command tasks: a scheduled definition that runs a subprocess instead of
// prompting an Agent. Non-null ``shell_command`` OR a non-empty ``command``
// argv is what makes a row one (see ``taskIsCommand``); its ``prompt`` is
// empty and — when ``metadata.on_failure`` is ``"none"`` — it has no session
// at all, so nothing here may be assumed present.
//
// ``/api/harness/tasks`` serves the raw store row, so these are exactly the
// keys ``_scheduled_task_from_row`` writes: ``metadata`` already decoded, not
// ``metadata_json``.
shell_command?: string | null;
command?: unknown[] | null;
timeout_seconds?: number | null;
last_exit_code?: number | null;
metadata?: Record<string, unknown> | null;
// Where a command task's subprocess runs. Null is not "nowhere": a definition
// bound to a Session follows that Session's workdir, read live at fire time
// (``_bound_session_workdir``), so the pane names the source rather than
// printing a blank.
cwd?: string | null;
};
export type HarnessWatchRuntime = {
running: boolean;
pid?: number | null;
started_at?: string | null;
updated_at?: string | null;
};
export type HarnessWatch = HarnessSessionSummary & HarnessDefinitionState & {
id: string;
name: string | null;
agent_name: string | null;
session_policy: string | null;
session_id: string | null;
session_key: string;
command: unknown[];
shell_command: string | null;
prefix: string | null;
message: string | null;
message_payload: Record<string, unknown> | null;
cwd: string | null;
mode: string;
timeout_seconds: number;
lifetime_timeout_seconds: number;
retry_exit_codes: number[];
retry_delay_seconds: number;
post_to: string | null;
deliver_key: string | null;
enabled: boolean;
created_at: string | null;
updated_at: string | null;
last_started_at: string | null;
last_finished_at: string | null;
retired_at: string | null;
last_event_at: string | null;
last_error: string | null;
last_exit_code: number | null;
// Decoded server-side metadata includes durable Watch admission facts such as
// the circuit-breaker incident; it is troubleshooting evidence, not a new UI
// lifecycle state.
metadata: Record<string, unknown> | null;
runtime: HarnessWatchRuntime;
// Whether the waiter process is alive. ``null`` means we have never seen a
// heartbeat for it, which is not the same as having seen it exit — the row
// must not report a dead waiter on the strength of never having looked.
process_alive: boolean | null;
};
export type HarnessRunStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'canceled' | (string & {});
// Everything the list endpoint accepts. The UI offers four of these as chips
// (see ``harnessLifecycle.ts``); the per-state values stay valid so a deep link
// can name one exactly.
export type HarnessDefinitionStatus =
| 'all'
| 'active'
| 'running'
| 'waiting'
| 'paused'
| 'finished';
// Counts are per *state*, one bucket per lifecycle value plus the total, so a
// chip spanning two states sums them client-side rather than asking the server
// for a bucket named after a chip.
export type HarnessDefinitionCounts = {
total: number;
running: number;
waiting: number;
paused: number;
finished: number;
[key: string]: number;
};
export type HarnessRunCounts = {
all: number;
queued: number;
running: number;
succeeded: number;
failed: number;
canceled: number;
[key: string]: number;
};
// A run carries the same resolved session summary as a task/watch, so the same
// DetailSession component renders all three. ``callback_session`` is nested
// rather than prefix-flattened for exactly that reason.
export type HarnessRun = HarnessSessionSummary & {
id: string;
request_type: string | null;
run_type: string | null;
status: HarnessRunStatus;
definition_id: string | null;
// The task/watch this run came from, named. Present even when soft-deleted —
// a run outlives its definition — with ``definition_deleted`` telling the UI
// to show the name without a link.
definition_name: string | null;
definition_kind: 'task' | 'watch' | null;
definition_deleted: boolean;
callback_session: HarnessSessionSummary | null;
task_id: string | null;
source_kind: string | null;
// Polymorphic: a session id when ``source_kind === 'agent'``, otherwise a
// parent run id, a vault request handle, or a human's name. Render it raw
// only when ``source_session`` is null — that is the resolved form, and it is
// non-null exactly when the actor names a session.
source_actor: string | null;
// ``source_actor`` narrowed to the session case, so the UI never has to
// re-derive "is this string an id?" from ``source_kind``.
source_session_id: string | null;
source_session: HarnessSessionSummary | null;
parent_run_id: string | null;
// Callback (report-back) lineage — serialized by the backend run row but
// previously unrendered; the run detail surfaces these (Part B).
callback_session_id: string | null;
callback_run_id: string | null;
callback_status: string | null;
callback_error: string | null;
agent_name: string | null;
agent_id: string | null;
agent_backend: string | null;
model: string | null;
reasoning_effort: string | null;
session_policy: string | null;
session_key: string | null;
session_id: string | null;
post_to: string | null;
deliver_key: string | null;
prompt: string | null;
message: string | null;
message_payload: Record<string, unknown> | null;
result_text: string | null;
result_payload: Record<string, unknown> | null;
message_ids: string[];
cancel_requested: boolean;
cancel_requested_at: string | null;
pid: number | null;
exit_code: number | null;
error: string | null;
stdout: string | null;
stderr: string | null;
created_at: string | null;
started_at: string | null;
completed_at: string | null;
updated_at: string | null;
metadata: Record<string, unknown>;
ok: boolean | null;
};
export type HarnessRunsParams = {
status?: HarnessRunStatus;
runType?: string;
// Comma-serialized server-side exclusion. ``run_type`` is an equality match,
// so "everything except watcher heartbeats" needs its own param — and an
// exclusion keeps a future run type visible by default instead of dropping it.
excludeRunType?: string[];
agentName?: string;
definitionId?: string;
query?: string;
page?: number;
limit?: number;
};
export type HarnessDefinitionsParams = {
status?: HarnessDefinitionStatus;
query?: string;
page?: number;
limit?: number;
};
export type HarnessPageResultBase<TCounts> = {
counts: TCounts;
total: number;
page: number;
limit: number;
has_more: boolean;
};
export type HarnessTasksResult = HarnessPageResultBase<HarnessDefinitionCounts> & {
tasks: HarnessTask[];
};
export type HarnessWatchesResult = HarnessPageResultBase<HarnessDefinitionCounts> & {
watches: HarnessWatch[];
};
export type HarnessRunsResult = HarnessPageResultBase<HarnessRunCounts> & {
runs: HarnessRun[];
// Every run_type present in the ledger, so the selector can offer a type the
// UI has no built-in name for. Optional: an older server omits it.
run_types?: string[];
};
export type HarnessCountsResult = {
tasks: HarnessDefinitionCounts;
watches: HarnessDefinitionCounts;
runs: HarnessRunCounts;
};
export type HarnessBootstrapParams = {
tab?: 'tasks' | 'watches' | 'runs';
status?: HarnessDefinitionStatus | HarnessRunStatus;
/** Runs tab only — mirrors the dedicated /api/harness/runs filters so the
* first paint already reflects the active filter instead of flashing an
* unfiltered page. */
run_type?: string;
exclude_run_type?: string[];
query?: string;
/** Scope tasks/watches to a bound session (background-work banner deep-link). */
session_id?: string;
page?: number;
limit?: number;
};
export type HarnessBootstrapResult = {
counts: HarnessCountsResult;
tab: 'tasks' | 'watches' | 'runs';
page: HarnessTasksResult | HarnessWatchesResult | HarnessRunsResult;
};
// =============================================================================
// Running agents (live process view)
// =============================================================================
export type RunningAgentState = 'active' | 'idle' | 'orphan';
export type RunningAgent = {
backend: string;
state: RunningAgentState;
base_session_id: string | null;
composite_key: string | null;
workdir: string | null;
pid: number | null;
pid_shared: boolean;
native_session_id: string | null;
model: string | null;
elapsed_seconds: number | null;
session_id: string | null;
title: string | null;
platform: string | null;
scope_type: string | null;
scope_display_name: string | null;
/** The session's visibility; null for a process with no session row. */
visibility: 'foreground' | 'background' | 'system' | null;
trigger_source: 'human' | 'agent' | 'scheduled' | 'watch' | 'webhook' | 'callback' | null;
agent_name: string | null;
openable_in_chat: boolean;
};
export type RunningAgentCounts = {
total: number;
active: number;
idle: number;
orphan: number;
by_backend: Record<string, number>;
};
export type RunningAgentsResult =
| { ok: true; agents: RunningAgent[]; counts: RunningAgentCounts; unreachable?: false }
| { ok: false; unreachable: true; agents: RunningAgent[]; counts: Partial<RunningAgentCounts> };
export type LogEntry = {
timestamp: string;
level: string;
logger: string;
message: string;
source: string;
};
export type LogSource = {
key: string;
filename: string;
path: string;
exists: boolean;
total: number;
logs?: LogEntry[];
};
export type VersionInfo = {
current: string;
latest: string | null;
has_update: boolean;
error: string | null;
managed_by?: 'desktop';
remote_install_allowed?: boolean;
remote_request?: DesktopRemoteUpdateRequest | null;
build?: {
kind: 'package' | 'source';
revision?: string;
dirty?: boolean;
};
};
export type DesktopRemoteUpdatePhase =
| 'requested'
| 'acknowledged'
| 'checking'
| 'awaiting_host'
| 'downloading'
| 'installing'
| 'restarting'
| 'completed'
| 'failed'
| 'declined'
| 'expired';
export type DesktopRemoteUpdateRequest = {
request_id: string;
target: string;
phase: DesktopRemoteUpdatePhase;
progress: number | null;
error_code: string | null;
updated_at: string;
};
export type DesktopRemoteUpdateErrorCode =
| 'not_desktop_managed'
| 'no_update_available'
| 'update_in_progress'
| 'desktop_shell_unavailable'
| 'confirmation_required';
export type DesktopRemoteUpdateResult =
| { ok: true; request_id: string; delivery: 'prompt' | 'install' }
| UpdateConfirmationRequired
| {
ok: false;
error: Exclude<DesktopRemoteUpdateErrorCode, 'confirmation_required'>;
message?: string;
};
export type UpdateInterruptionCounts = {
agents: number;
watches: number;
tasks: number;
total: number;
unknown: boolean;
};
export type UpdateConfirmationRequired = {
ok: false;
error: 'confirmation_required';
counts: UpdateInterruptionCounts;
};
export type UpgradeResult = UpdateConfirmationRequired | {
ok: boolean;
message: string;
output: string | null;
activation_notice?: string | null;
restarting: boolean;
code?: string;
error?: never;
};
export type InstallResult = {
ok: boolean;
message: string;
output: string | null;
path?: string | null;
job_id?: string;
status?: 'running' | 'succeeded' | 'failed' | 'rejected';
poll_timeout_seconds?: number;
reason?: string | null;
action_class?: 'operator_only';
download_error?: DependencyDownloadError | null;
/** Agent CLI failures: a stable recognition code (``install_failed`` when
* nothing matched), its localized hint, and the installer's exit status. */
code?: string;
hint?: string | null;
hint_params?: Record<string, unknown>;
exit_code?: number;
};
export type DependencyDownloadError = {
kind: 'http' | 'dns' | 'tls' | 'timeout' | 'network' | 'permission' | 'disk' | 'io' | 'unknown';
message: string;
url?: string | null;
host?: string | null;
http_status?: number;
retryable: boolean;
attempts: number;
};
export type DependencyItem = {
id: string;
kind: 'tool' | 'runtime' | 'node';
required: boolean | null;
installed: boolean | null;
version: string | null;
latest_version?: string | null;
has_update?: boolean;
status: 'ready' | 'not_required' | 'missing' | 'upgrade_required' | 'unsupported' | 'error' | 'unknown';
readiness?: 'ready' | 'not_required' | 'not_ready';
action_class?: 'none' | 'repairable' | 'operator_only';
reason?: string | null;
release_state?: 'published' | 'unavailable' | null;
download_error?: DependencyDownloadError | null;
inspection_error?: { kind: string; message: string } | null;
/** avault only: the binary cannot read the Vault key until the user authorizes it once. */
authorization_required?: boolean;
};
/** avault's one-time macOS Keychain authorization (see vibe/avault_authorization.py). */
export type AvaultAuthorizationAttempt = {
id: string;
state: 'running' | 'succeeded' | 'failed';
reason?: string | null;
detail?: string;
started_at: string;
finished_at?: string;
};
export type AvaultAuthorizationStatus = {
ok: boolean;
required: boolean;
detected_at: string | null;
attempt: AvaultAuthorizationAttempt | null;
login_session_state?: MacOSLoginSessionStatus['state'];
};
export type MacOSLoginSessionStatus = {
ok: boolean;
state: 'healthy' | 'stale_login_session' | 'no_gui_session' | 'unknown' | 'not_applicable';
};
export type DependenciesResult = {
ok: boolean;
deps: DependencyItem[];
login_session_state?: MacOSLoginSessionStatus['state'];
reconciling?: boolean;
reconciling_dependencies?: string[];
};
export type DependencyReadOptions = { ids?: readonly string[]; signal?: AbortSignal };
export type BackendConnectionState = {
ok: boolean;
backend: AgentBackendId;
installed: boolean;
/** Independent executable evidence; built-in backends do not have a CLI. */
cli_status?: CliStatus | null;
enabled: boolean;
// external: launch capability only; the native backend owns authentication.
auth: 'subscription' | 'api_key' | 'external' | 'none' | 'unknown';
application: 'applied' | 'draining' | 'failed' | 'stopped' | 'unknown';
ready: boolean;
entry_eligible: boolean;
/** Which credential owner supplies this backend; omitted responses remain direct-compatible. */
supply_mode?: 'direct' | 'hub';
permission_required?: boolean;
message?: string;
};
export type CliStatus = 'unknown' | 'ok' | 'missing' | 'broken';
export type CliDetectionResult = {
found: boolean;
path: string | null;
status: CliStatus;
version?: string | null;
reason?: string | null;
/** The lifecycle projection shares this exact health observation. */
runtime?: BackendRuntimeInfo;
};
export type BackendRuntimeInfo = {
ok: boolean;
name?: string;
enabled?: boolean;
auto_update?: boolean;
cli_path?: string;
resolved_path?: string | null;
installed?: boolean;
status?: CliStatus;
reason?: string | null;
current_version?: string | null;
latest_version?: string | null;
has_update?: boolean;
managed_by?: 'desktop';
supports_restart?: boolean;
process_status?: 'running' | 'stopped' | 'unknown';
error?: string;
};
export type BackendRestartResult = {
ok: boolean;
message: string;
};
export type CodexAuthMode = 'oauth' | 'api_key';
// Mirrors Codex CLI's ``cli_auth_credentials_store`` setting. ``auto`` is
// Codex's documented default and is treated as keyring-preferred — when
// the live store is not ``file`` the on-disk ``auth.json`` may not be
// the source of truth, so the UI must not interpret ``has_api_key=false``
// as "no key configured" in that case.
export type CodexCredentialsStore = 'file' | 'keyring' | 'auto' | (string & {});
export type ActiveAuthMode = 'oauth' | 'api_key' | 'none';
// Identity decoded from the ChatGPT JWT inside ``~/.codex/auth.json``.
// All fields are best-effort — the OAuth bundle may carry partial
// claims, in which case the panel renders only what's present.
export type CodexChatGptAccount = {
email: string | null;
name: string | null;
plan_type: string | null;
organizations: Array<{
id: string | null;
title: string | null;
role: string | null;
is_default: boolean;
}> | null;
};
export type CodexAuthState = {
ok: boolean;
auth_mode: CodexAuthMode;
// What the running Codex CLI is actually using at launch — separate
// from ``auth_mode`` which is the user's saved intent. Lets the UI
// surface "Currently active: …" so the two-radio choice is no longer
// ambiguous about which mode is live.
active_auth_mode: ActiveAuthMode;
has_api_key: boolean;
api_key_length: number;
// Server-masked preview (e.g. ``sk-proj-•••••••••H8mN``). Used to
// pre-fill the API Key input so the page reflects the saved state
// instead of looking empty. Plaintext keys never leave the server.
api_key_masked: string | null;
base_url: string | null;
has_chatgpt_tokens: boolean;
chatgpt_account?: CodexChatGptAccount | null;
credentials_store: CodexCredentialsStore;
file_store_active: boolean;
// True when Codex is in keyring-preferred mode and disk shows no
// key/tokens — the live auth may live in the OS keychain (we cannot
// portably read it). UI must not claim "no key configured" in that
// case; it should prompt the user to choose a mode (saving will pin
// file storage so subsequent reads work).
auth_mode_uncertain?: boolean;
message?: string;
};
export type CodexAuthPayload = {
auth_mode: CodexAuthMode;
api_key?: string | null;
base_url?: string | null;
};
// Non-fatal warning the server attached to a config-mutation response.
// Used today for "we cleared a custom relay pointer because OAuth tokens
// won't validate against your custom base_url"; new codes can be added
// without touching the type.
export type BackendNotice = {
code: string;
provider_id?: string;
base_url?: string;
detail?: string;
};
export type CodexAuthSaveResult = CodexAuthState & {
restart?: BackendRestartResult;
notices?: BackendNotice[];
error?: string;
reauth_channel?: 'hub';
};
export type ClaudeAuthMode = 'oauth' | 'api_key';
export type ClaudeCredentialType = 'api_key' | 'auth_token';
// Claude Code reads ``~/.claude/settings.json`` at launch and its ``env``
// block wins over inherited process env. avibe therefore writes
// API-key auth into that file directly; ``v2config`` only appears for
// legacy installs that have not yet been migrated by the next save.
export type ClaudeApiKeySource = 'v2config' | 'settings_json' | null;
export type ClaudeAuthState = {
ok: boolean;
auth_mode: ClaudeAuthMode;
// Legacy field; native authentication is not inferred by this inventory.
active_auth_mode: ActiveAuthMode;
auth_managed_by?: 'claude';
auth_mode_uncertain?: boolean;
oauth_store_state?: 'present' | 'absent' | 'unknown';
can_remove_oauth_credentials?: boolean;
has_api_key: boolean;
api_key_length: number;
api_key_masked: string | null;
api_key_source?: ClaudeApiKeySource;
// Inspectable native material only, not a signed-in or effective-auth claim.
has_oauth_credentials: boolean;
base_url: string | null;
settings_path: string | null;
settings_exists: boolean;
settings_env_has_key: boolean;
settings_env_key_length: number;
settings_env_key_var: 'ANTHROPIC_API_KEY' | 'ANTHROPIC_AUTH_TOKEN' | null;
credential_type: ClaudeCredentialType | null;
settings_env_base_url: string | null;
settings_conflict: boolean;
message?: string;
};
export type ClaudeAuthPayload = {
auth_mode: ClaudeAuthMode;
api_key?: string | null;
credential_type?: ClaudeCredentialType;
base_url?: string | null;
};
export type ClaudeAuthSaveResult = ClaudeAuthState & {
restart?: BackendRestartResult;
partial?: boolean;
warning?: string;
detail?: string;
error?: string;
reauth_channel?: 'hub';
};
// One entry in the OpenCode provider grid. The full catalog is built
// dynamically on the server by merging ``/provider`` + ``/provider/auth``
// + ``/config/providers`` — there is **no** hard-coded list in the UI.
// ``local`` is inferred from the absence of network auth methods (Ollama,
// LM Studio); the page renders its own "Local" badge for those rows.
export type OAuthWebState =
| 'starting'
| 'awaiting_code'
| 'verifying'
| 'success'
| 'failed'
| 'cancelled';
export type OAuthWebStartResult = {
ok: boolean;
// This operation committed authorization, independently of runtime apply.
authorization_completed?: boolean;
flow_id?: string;
backend?: WebOAuthBackend;
state?: OAuthWebState;
url?: string | null;
device_code?: string | null;
awaiting_code?: boolean;
callback_kind?: 'code' | 'device' | 'redirect' | null;
error?: string;
detail?: string;
reauth_channel?: 'hub';
};
export type OAuthWebStatus = {
ok: boolean;
authorization_completed?: boolean;
flow_id?: string;
backend?: WebOAuthBackend;
state?: OAuthWebState;
url?: string | null;
device_code?: string | null;
awaiting_code?: boolean;
callback_kind?: 'code' | 'device' | 'redirect' | null;
error?: string | null;
reauth_channel?: 'hub';
};
export type OAuthWebMutationResult = {
ok: boolean;
error?: string;
detail?: string;
reauth_channel?: 'hub';
notices?: BackendNotice[];
restart?: BackendRestartResult;
// ``partial: true`` rides on ``ok: true`` when the V2Config side of
// the operation succeeded but the CLI subprocess (``codex logout`` /
// ``claude auth logout``) reported a non-zero exit. The caller should
// show a warning rather than a green success — credentials may still
// be on disk. Pairs with ``warning`` (machine-readable code) and
// ``detail`` (human-readable excerpt).
partial?: boolean;
warning?: string;
};
export type BackendAuthTestResult = {
ok: boolean;
duration_ms?: number;
excerpt?: string;
exit_code?: number;
error?: string;
detail?: string;
reauth_channel?: 'hub';
};
export type OpencodeProvider = {
id: string;
name: string;
description: string;
configured: boolean;
// ``configured`` means usable (including keyless local custom providers).
// ``has_auth`` means there is an auth.json or legacy opencode.json key entry
// that the UI can safely offer to remove.
has_auth?: boolean;
oauth_available: boolean;
local: boolean;
custom?: boolean;
adapter?: 'openai-compatible' | 'anthropic-compatible' | string | null;
models: string[];
model_entries?: {
id: string;
user_managed: boolean;
reasoning_efforts?: string[];
}[];
// Optional ``baseURL`` override persisted in opencode.json. Surfaced so
// the Settings page can pre-populate the Base URL input with the last
// saved value instead of starting empty on every reload.
base_url?: string | null;
// Server-masked preview of the api-type credential stored in
// ``~/.local/share/opencode/auth.json`` (e.g. ``sk-proj-•••H8mN``).
// ``null``/missing when the provider uses OAuth or hasn't been
// configured yet. Mirrors Claude / Codex's ``api_key_masked`` so the
// user can see at a glance which providers have a stored key without
// having to expand each card.
api_key_masked?: string | null;
// ``api`` / ``oauth`` / null — the auth type currently stored for the
// provider. OpenCode's ``auth.json`` only carries ONE entry per
// provider at a time, so this is also the type that will be used at
// launch. Lets the UI badge dual-mode providers (e.g. openai) with
// which source is live, instead of leaving the user guessing.
active_auth_type?: 'api' | 'oauth' | string | null;
};
export type OpencodeCustomProviderPayload = {
provider_id: string;
name: string;
adapter: 'openai-compatible' | 'anthropic-compatible';
base_url: string;
api_key?: string;
};
export type OpencodeProviderListResult = {
ok: boolean;
message?: string;
providers?: OpencodeProvider[];
default_provider?: string;
// True when ``opencode.json`` has ``permission: "allow"`` — the
// setting that lets OpenCode skip the interactive tool-call approval
// prompt avibe can't reply to. The Settings page hides the
// "Allow tool calls" affordance when this is already true.
permission_allowed?: boolean;
};
export type OpencodeOptionsResult = {
ok: boolean;
data?: {
models?: { providers?: unknown[] };
reasoning_options?: Record<string, { value: string; label: string }[]>;
[key: string]: unknown;
};
};
export type OpencodeMutationResult = {
ok: boolean;
restart?: BackendRestartResult;
message?: string;
error?: string;
detail?: string;
reauth_channel?: 'hub';
default_provider?: string;
provider_id?: string;
model_id?: string;
catalog_refresh?: {
ok: boolean;
message?: string;
catalog?: OpencodeProviderListResult | null;
};
};
export type WebPushNormalDeliveryOwner = {
policy?: string;
disposition?: string | null;
reason?: string;
};
export type WebPushNormalDeliveryRecent = {
at?: string;
message_id?: string | null;
session_id?: string | null;
owners?: Record<string, WebPushNormalDeliveryOwner>;
disposition?: string | null;
};
/** Normal-path authorization evaluation shared by the test/status surface. */
export type WebPushNormalDelivery = {
user_key?: string;
policy?: string;
authorized?: boolean | null;
disposition?: string | null;
reason?: string;
revision_state?: string;
recent_deliveries?: WebPushNormalDeliveryRecent[];
};
export type WebPushStatus = {
ok: boolean;
configured: boolean;
public_key: string;
subscription_count: number;
current_subscription_enabled?: boolean;
current_subscription_repairable?: boolean;
normal_delivery?: WebPushNormalDelivery;
};
export type WebPushStatusPayload = {
endpoint?: string;
subscription?: PushSubscriptionJSON;
device_id?: string;
device_label?: string;
previous_endpoints?: string[];
};
export type WebPushSubscriptionResult = {
ok: boolean;
accepted: boolean;
subscription: {
id: string;
user_key: string;
endpoint: string;
enabled: boolean;
device_id?: string | null;
user_agent?: string | null;
device_label?: string | null;
} | null;
};
export type WebPushTestResult = {
ok: boolean;
sent?: number;
failed?: number;
error?: string;
normal_delivery?: WebPushNormalDelivery;
};
// Error thrown by the JSON helpers below when a request fails. Carries the
// HTTP status and the server's machine-readable ``error`` code (when the body
// includes one) so callers can branch on *why* a request failed instead of
// only seeing a human string. The AuthGuard relies on this to tell a policy
// block (e.g. ``remote_access_host_mismatch``) apart from an unconfigured
// instance.
export class ApiError extends Error {
readonly status: number;
readonly code: string | null;
constructor(message: string, status: number, code: string | null) {
super(message);
this.name = 'ApiError';
this.status = status;
this.code = code;
}
}
const ApiContext = createContext<ApiContextType | undefined>(undefined);
const CONFIG_CACHE_TTL_MS = 30_000;
export const useApi = () => {
const context = useContext(ApiContext);
if (!context) {
throw new Error('useApi must be used within ApiProvider');
}
return context;
};
export const ApiProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
const { showToast } = useToast();
const { t } = useTranslation();
const readCacheRef = useRef(new Map<string, { expiresAt: number; promise: Promise<any> }>());
const configChangedHandlersRef = useRef(new Set<(config: unknown) => void>());
// Agent Activity is global across chat routes. Keep its writes ordered for the
// provider lifetime without making unrelated runtime-backed config saves block chat.
const agentActivityConfigMutationTailRef = useRef<Promise<unknown>>(Promise.resolve());
const eventSourceRef = useRef<EventSource | null>(null);
const eventHandlersRef = useRef(new Set<WorkbenchEventHandlers>());
const eventConnectionRef = useRef<{ sub_id: number; source?: 'browser' | 'controller' } | null>(null);
// The controller leg of this stream, which is the second thing that can break:
// the browser socket stays open and heartbeating while the UI server loses
// `/internal/events`, and `vibe/inbox_bridge.py` resumes the live feed without
// replaying what the controller published in between. `unknown` is not a third
// kind of outage -- it is a stream that has not heard from the leg yet, which
// is what keeps its first "connected" report from reading as a recovery.
const eventControllerLegRef = useRef<WorkbenchControllerLegState>('unknown');
// When the active stream last proved it was alive, and the cadence the server
// said it would prove it at. Null whenever there is no stream to speak for --
// including a stream that has connected but not yet been heard from, because a
// heartbeat is the only thing that proves continuity and nothing else may
// stand in for one. A server too old to send them therefore never reads as
// proven, which is the pre-heartbeat behavior this optimization replaces.
const eventHeartbeatAtRef = useRef<number | null>(null);
const eventHeartbeatIntervalRef = useRef(WORKBENCH_EVENT_HEARTBEAT_FALLBACK_MS);
// When the deadline the current stream is being held to started running, or
// null when this server never promised a cadence and so cannot be held to one.
// Deliberately separate from the stamp above: a promise is what makes a
// deadline enforceable, and only a heartbeat is proof the stream is carrying
// events. Collapsing them either lets a handshake vouch for a stream or leaves
// a stream that dies before its first heartbeat with no deadline at all.
const eventHeartbeatClockAtRef = useRef<number | null>(null);
// Fires when the next heartbeat is overdue. A heartbeat is a continuous clock,
// so whoever trusts it has to keep watching it: sampling only at the moment a
// page returns would leave a stream that dies one second later unquestioned
// until the next return, which may never come while the tab stays open.
const eventHeartbeatWatchdogRef = useRef<ReturnType<typeof setTimeout> | null>(null);
const eventConnectionStateRef = useRef<WorkbenchEventConnectionState>('reconnecting');
const eventReconnectLoopRef = useRef<WorkbenchEventReconnectLoop | null>(null);
const resumeWorkbenchEventsRef = useRef<PageReactivationListener>(() => {});
const syncSessionDraftsRef = useRef<() => void>(() => {});
const stopWorkbenchEventsRef = useRef<() => void>(() => {});
const sessionArchivedHandlersRef = useRef(new Set<(sessionId: string) => void>());
const sessionDraftPersistence = useMemo(() => new SessionDraftPersistence(), []);
const convergeSessionArchived = (sessionId: string) => {
sessionDraftPersistence.clearSession(sessionId);
for (const handler of Array.from(sessionArchivedHandlersRef.current)) {
try {
handler(sessionId);
} catch (err) {
console.error('[API] session-archived subscriber failed', err);
}
}
};
const handleApiError = async (
res: Response,
path: string,
{ expectedCodes }: { expectedCodes?: readonly string[] } = {},
) => {
let errorMessage = `Request failed: ${path} (${res.status})`;
let errorCode: string | null = null;
try {
const data = await res.json();
const parsed = selectApiErrorFields(data, errorMessage);
if (parsed) {
// Localize by code, falling back to the server-provided message so we never render a
// key like ``errors.[object Object]``.
errorCode = parsed.code;
errorMessage = parsed.code
? t(`errors.${parsed.code}`, { defaultValue: parsed.fallback })
: parsed.fallback;
}
} catch {
// Response is not JSON, use status text
errorMessage = `${path}: ${res.statusText || 'Unknown error'} (${res.status})`;
}
// A code the caller declared EXPECTED is an answer, not a failure: it still
// rejects, so no caller can mistake an error body for data, but it is neither
// announced to the user nor logged as an error. Declared per call site, applied
// here, so "expected" cannot mean two different things in two helpers.
if (!(errorCode !== null && expectedCodes?.includes(errorCode))) {
// Log error details to console
console.error(`[API Error] ${path}`, {
status: res.status,
statusText: res.statusText,
error: errorMessage,
});
// Show toast to user
showToast(errorMessage, 'error');
}
// Archive is TERMINAL, so this particular refusal is not a failure to retry
// but a state change the client missed (a backgrounded/offline tab can drop
// the archive SSE). Announce it once, from the one place every JSON helper
// funnels its errors through, so any subscriber converges no matter WHICH
// session-scoped write tripped it. Best-effort and non-throwing: a subscriber
// must never change whether/what this handler throws.
const archivedSessionId = archivedConflictSessionId(errorCode, path);
if (archivedSessionId) {
convergeSessionArchived(archivedSessionId);
}
throw new ApiError(errorMessage, res.status, errorCode);
};
const onSessionArchived = (handler: (sessionId: string) => void) => {
sessionArchivedHandlersRef.current.add(handler);
return () => {
sessionArchivedHandlersRef.current.delete(handler);
};
};
const onConfigChanged = (handler: (config: unknown) => void) => {
configChangedHandlersRef.current.add(handler);
return () => {
configChangedHandlersRef.current.delete(handler);
};
};
const convergeConfig = (config: unknown) => {
for (const handler of Array.from(configChangedHandlersRef.current)) {
try {
handler(config);
} catch (err) {
console.error('[API] config-changed subscriber failed', err);
}
}
};
const getJson = async (
path: string,
{ handleError = true, expectedCodes, signal }: {
handleError?: boolean;
expectedCodes?: readonly string[];
signal?: AbortSignal;
} = {},
) => {
const res = await (signal ? apiFetch(path, { signal }) : apiFetch(path));
if (!res.ok && handleError) {
await handleApiError(res, path, { expectedCodes });
}
return res.json();
};
// Absence is data for a GET of ONE session's Show Page, never an incident: the share
// panel opens on sessions that have no page yet and renders that as an empty link.
// The property is owned here instead of declared per call site because the panel fires
// several of these reads at once — one of them forgetting is a toast the user sees for
// the normal case, and the reader cannot tell which of the parallel reads produced it.
// Mutations stay off this path deliberately: pinning or re-skinning a page that does
// not exist IS a fault worth announcing. So is the POST-shaped access-settings read,
// which only mounts once an access read has already proven the page exists, so an
// absent page there means it vanished mid-session rather than never existed.
const readShowPageJson = (path: string) => getJson(path, { expectedCodes: ['show_page_not_found'] });
const getCachedJson = (path: string, ttlMs = 1500, opts?: { cache?: boolean; handleError?: boolean }) => {
// Best-effort callers (handleError: false) bypass the shared read cache so a
// silently-failing request can't hand its suppressed-error promise to a
// toast-enabled caller hitting the same path.
if (opts?.cache === false || opts?.handleError === false) {
return getJson(path, { handleError: opts?.handleError });
}
const now = Date.now();
const cached = readCacheRef.current.get(path);
if (cached && cached.expiresAt > now) {
return cached.promise;
}
const promise = getJson(path).catch((err) => {
readCacheRef.current.delete(path);
throw err;
});
readCacheRef.current.set(path, { expiresAt: now + ttlMs, promise });
return promise;
};
const clearReadCache = () => {
readCacheRef.current.clear();
};
const clearReadCacheMatching = (predicate: (path: string) => boolean) => {
for (const path of readCacheRef.current.keys()) {
if (predicate(path)) {
readCacheRef.current.delete(path);
}
}
};
const clearSessionReadCache = (sessionId: string) => {
const encoded = encodeURIComponent(sessionId);
const sessionPrefix = `/api/sessions/${encoded}`;
clearReadCacheMatching((path) =>
path === sessionPrefix ||
path.startsWith(`${sessionPrefix}/`) ||
path.startsWith('/api/sessions?') ||
path === '/api/sessions' ||
path.startsWith('/api/workbench/projects-bootstrap') ||
path.startsWith('/api/inbox?') ||
path === '/api/inbox',
);
};
const dispatchToWorkbenchHandlers = (dispatch: (handlers: WorkbenchEventHandlers) => void) => {
for (const handlers of Array.from(eventHandlersRef.current)) {
dispatch(handlers);
}
};
// Feed a locally-synthesized session.activity event through the SAME handler
// set + read-cache invalidation the SSE 'session.activity' listener uses, so a
// client-originated change (e.g. a visibility PATCH) reconciles every workbench
// cache via its own reducer even when the SSE stream is down. Idempotent with a
// later real SSE event carrying the same change.
const emitLocalSessionActivity = (data: Parameters<NonNullable<WorkbenchEventHandlers['onSessionActivity']>>[0]) => {
if (data.session_id) clearSessionReadCache(data.session_id);
dispatchToWorkbenchHandlers((handlers) => handlers.onSessionActivity?.(data));
};
const setWorkbenchEventConnectionState = (state: WorkbenchEventConnectionState) => {
if (eventConnectionStateRef.current === state) return;
eventConnectionStateRef.current = state;
dispatchToWorkbenchHandlers((handlers) => handlers.onConnectionState?.(state));
};
const parseWorkbenchEnvelope = <T,>(raw: string): WorkbenchEventEnvelope<T> | null => {
try {
return JSON.parse(raw) as WorkbenchEventEnvelope<T>;
} catch (err) {
console.error('[workbench-events] parse failed', err, raw);
return null;
}
};
const clearWorkbenchHeartbeatWatchdog = () => {
if (eventHeartbeatWatchdogRef.current === null) return;
clearTimeout(eventHeartbeatWatchdogRef.current);
eventHeartbeatWatchdogRef.current = null;
};
const closeActiveWorkbenchEventSource = () => {
const source = eventSourceRef.current;
eventSourceRef.current = null;
source?.close();
eventConnectionRef.current = null;
eventControllerLegRef.current = 'unknown';
// The stamp and the cadence both speak for one socket only; a later stream
// must earn its own, including the right to be watched on a timer.
eventHeartbeatAtRef.current = null;
eventHeartbeatClockAtRef.current = null;
clearWorkbenchHeartbeatWatchdog();
};
/**
* The stream's own handshake, or null while events cannot reach handlers. A
* controller-sourced stream is itself the controller leg, so it is down when
* that leg reports down.
*/
const workbenchEventHandshake = () => {
const connection = eventConnectionRef.current;
if (!connection) return null;
if (connection.source === 'controller' && eventControllerLegRef.current !== 'connected') return null;
return connection;
};
/**
* Reconnecting this socket would close no gap, because it is carrying
* everything it can carry right now.
*
* Scoped to this socket on purpose: a stream reaches the browser over two legs
* that fail independently, and each one is judged by whoever can see it. This
* is the browser leg. Reopening it cannot repair the controller leg behind the
* UI server -- the replacement would inherit the same severed bridge -- so the
* controller leg is not a term here; it announces its own recovery instead, in
* the `workbench.events.bridge.status` listener below.
*
* That makes this the answer to one question only: whether recycling this
* socket would close anything. It is not a verdict on the stream, and asking
* it as one is how a controller-leg outage came to read as a gap-free resume.
* `streamCoveredGap` is where every leg is accounted for.
*
* All three terms are needed for this leg. `readyState` is the browser's own
* transport verdict, which it revises on network changes and HTTP/2 ping
* timeouts. The handshake says a stream that is open can also reach handlers.
* Neither survives suspension: a backgrounded tab can have its socket dropped
* and be resumed with the connection still reported `OPEN` and no `error` ever
* delivered, so only a recent heartbeat distinguishes a quiet stream from that
* zombie.
*/
const isWorkbenchBrowserLegLive = () =>
eventSourceRef.current?.readyState === EventSource.OPEN &&
workbenchEventHandshake() !== null &&
isWorkbenchHeartbeatFresh(
eventHeartbeatAtRef.current,
eventHeartbeatIntervalRef.current,
Date.now(),
);
/**
* This stream is over: drop it, say so, and let the loop schedule the next
* attempt. One owner for the transition, because a stream that dies silently
* has to end up in exactly the same state as one that reports `error` --
* consumers recover through the reconnect's `connected`, so a path that
* skipped any of these steps would strand them.
*/
const failWorkbenchEventStream = () => {
closeActiveWorkbenchEventSource();
setWorkbenchEventConnectionState('reconnecting');
dispatchToWorkbenchHandlers((handlers) => handlers.onEventBridgeStatus?.({ connected: false }));
getWorkbenchEventReconnectLoop().failed();
};
/**
* Watch for the heartbeat the current stream owes us. A stream that stops
* proving itself is dead whether or not the browser ever says so, and the
* only way a consumer learns that is if someone is still looking.
*/
const armWorkbenchHeartbeatWatchdog = () => {
clearWorkbenchHeartbeatWatchdog();
// Only a stream whose server promised a cadence owes a heartbeat. A deadline
// is a claim about a cadence, so a server that never declared one cannot be
// held to it: against an older server -- a rollback under a tab that stayed
// open -- this would otherwise close a healthy stream every stale window
// forever, charging every consumer a catch-up each round. A modern server
// makes that promise in its handshake, which is what puts a stream that dies
// before its first heartbeat on a deadline too.
const clockAt = eventHeartbeatClockAtRef.current;
if (clockAt === null) return;
const staleAt = clockAt + workbenchEventStaleAfterMs(eventHeartbeatIntervalRef.current);
eventHeartbeatWatchdogRef.current = setTimeout(() => {
eventHeartbeatWatchdogRef.current = null;
// A hidden page cannot hold a stream open anyway, and its timers are
// throttled or frozen: the reactivation edge is the honest check there.
if (document.visibilityState !== 'visible') return;
// A heartbeat may have landed since this timer was set, in which case the
// stream is proving itself and only the deadline moved.
if (isWorkbenchBrowserLegLive()) {
armWorkbenchHeartbeatWatchdog();
return;
}
failWorkbenchEventStream();
}, Math.max(0, staleAt - Date.now()));
};
/**
* Start this stream's clock from its server's promise. Called from the
* handshake, so a stream that opens and never sends a heartbeat still has a
* deadline to miss -- the case a stamp-only clock cannot express, because
* there is nothing to stamp.
*
* Sticky per stream: only a frame that carries a cadence is allowed to speak
* for one, so a controller-relayed handshake (no cadence of its own) never
* clears a clock the UI server's own handshake started.
*/
const declareWorkbenchHeartbeatCadence = (intervalMs: number) => {
eventHeartbeatIntervalRef.current = intervalMs;
eventHeartbeatClockAtRef.current = Date.now();
armWorkbenchHeartbeatWatchdog();
};
/**
* Record proof of life and keep watching for the next one. Stamping and
* watching are one action on purpose: a stamp nobody watches expires
* unnoticed, and a watchdog armed off a stale stamp fires against the wrong
* deadline.
*
* A heartbeat also restarts the clock, and does so even from a server that
* never declared a cadence: whatever the deadline was measured from, the
* newest proof is now the honest starting point.
*/
const stampWorkbenchHeartbeat = (intervalMs?: number) => {
const now = Date.now();
eventHeartbeatAtRef.current = now;
eventHeartbeatClockAtRef.current = now;
if (intervalMs !== undefined) eventHeartbeatIntervalRef.current = intervalMs;
armWorkbenchHeartbeatWatchdog();
};
function reconnectWorkbenchEventSource(): void {
if (eventHandlersRef.current.size === 0) return;
closeActiveWorkbenchEventSource();
openWorkbenchEventSource();
}
function getWorkbenchEventReconnectLoop(): WorkbenchEventReconnectLoop {
if (!eventReconnectLoopRef.current) {
eventReconnectLoopRef.current = new WorkbenchEventReconnectLoop({
reconnect: reconnectWorkbenchEventSource,
isVisible: () => document.visibilityState === 'visible',
isBrowserLegLive: isWorkbenchBrowserLegLive,
});
}
return eventReconnectLoopRef.current;
}
function openWorkbenchEventSource(): void {
if (
eventSourceRef.current ||
eventHandlersRef.current.size === 0 ||
document.visibilityState !== 'visible'
) return;
let source: EventSource;
try {
source = new EventSource('/api/events');
} catch (err) {
setWorkbenchEventConnectionState('reconnecting');
getWorkbenchEventReconnectLoop().failed();
const event = err instanceof Event ? err : new Event('error');
dispatchToWorkbenchHandlers((handlers) => handlers.onError?.(event));
return;
}
eventSourceRef.current = source;
setWorkbenchEventConnectionState('reconnecting');
getWorkbenchEventReconnectLoop().attemptStarted();
source.addEventListener('connected', (e: MessageEvent) => {
if (eventSourceRef.current !== source) return;
// Deliberately no stamp here. This frame proves the stream is alive now,
// which is not the question: the question is whether it will still be
// proving that in a minute, and only a heartbeat answers it. Seeding from
// the handshake would hand a stream up to one stale window of unearned
// trust -- enough for a suspended tab to return, be believed, and skip the
// catch-up for a gap it did have.
//
// What it may do is start the clock: the frame's `interval_ms` is the
// server declaring the cadence it owes, which is a promise, not proof.
// That is what puts a stream that opens and then goes silent on a
// deadline, while a server too old to declare one is still never
// watchdogged and still never believed without a heartbeat.
try {
const parsed = JSON.parse(e.data) as {
sub_id?: number;
interval_ms?: unknown;
type?: string;
data?: unknown;
};
const sourceKind = typeof parsed.sub_id === 'number' ? 'browser' : 'controller';
eventConnectionRef.current = {
sub_id: typeof parsed.sub_id === 'number' ? parsed.sub_id : -1,
source: sourceKind,
};
const declaredIntervalMs = declaredWorkbenchHeartbeatInterval(parsed.interval_ms);
if (declaredIntervalMs !== undefined) declareWorkbenchHeartbeatCadence(declaredIntervalMs);
if (sourceKind === 'controller') {
eventControllerLegRef.current = 'connected';
setWorkbenchEventConnectionState('connected');
dispatchToWorkbenchHandlers((handlers) => handlers.onEventBridgeStatus?.({ connected: true }));
}
} catch (err) {
console.error('[workbench-events] connected parse failed', err, e.data);
eventConnectionRef.current = null;
}
if (eventConnectionRef.current) {
getWorkbenchEventReconnectLoop().streamOpened();
dispatchToWorkbenchHandlers((handlers) => handlers.onConnected?.());
}
});
// The server's proof of life. It carries no news, so nothing is dispatched
// to handlers -- the arrival itself is the whole payload, and the declared
// cadence lets the staleness window be sized by the side that sets it.
source.addEventListener('heartbeat', (e: MessageEvent) => {
if (eventSourceRef.current !== source) return;
let intervalMs: number | undefined;
try {
const payload = JSON.parse(e.data) as { interval_ms?: unknown };
intervalMs = parseWorkbenchHeartbeatInterval(payload.interval_ms);
} catch {
// The frame arrived, which is what matters; keep the current cadence.
}
// The only place a stream is ever stamped, which is what lets a null stamp
// mean "nothing has proved this stream yet" even on a stream already
// running against a declared deadline.
stampWorkbenchHeartbeat(intervalMs);
});
source.addEventListener('authorization.changed', (e: MessageEvent) => {
const envelope = parseWorkbenchEnvelope<{
project_ids?: string[];
resource_kinds?: string[];
instance_authorization_revision?: number;
}>(e.data);
if (!envelope) return;
clearReadCacheMatching(isAuthorizationSensitiveReadPath);
dispatchToWorkbenchHandlers((handlers) => {
handlers.onAny?.(envelope);
handlers.onAuthorizationChanged?.(envelope.data);
});
});
source.addEventListener('projects.changed', (e: MessageEvent) => {
const envelope = parseWorkbenchEnvelope<Record<string, never>>(e.data);
if (!envelope) return;
clearReadCacheMatching((path) => path.startsWith('/api/projects') || path.startsWith('/api/workbench/projects-bootstrap'));
dispatchToWorkbenchHandlers((handlers) => {
handlers.onAny?.(envelope);
handlers.onProjectsChanged?.();
});
});
source.addEventListener('bots.changed', (e: MessageEvent) => {
const envelope = parseWorkbenchEnvelope<{ handle?: string }>(e.data);
if (!envelope) return;
// A Bot is Agent metadata (D1), so the Agents reads carry it too.
clearReadCacheMatching((path) => path.startsWith('/api/bots') || path.startsWith('/api/agents'));
dispatchToWorkbenchHandlers((handlers) => {
handlers.onAny?.(envelope);
handlers.onBotsChanged?.(envelope.data ?? {});
});
});
source.addEventListener('notifications.preferences.updated', (e: MessageEvent) => {
const envelope = parseWorkbenchEnvelope<unknown>(e.data);
if (!envelope) return;
clearReadCacheMatching((path) => path.startsWith('/api/notifications') || path.startsWith('/api/inbox'));
dispatchToWorkbenchHandlers((handlers) => {
handlers.onAny?.(envelope);
handlers.onNotificationPreferencesChanged?.();
});
});
source.addEventListener('remote.authorization', (e: MessageEvent) => {
try {
const payload = JSON.parse(e.data) as { state?: RemoteAuthorizationState };
if (payload.state) reportRemoteAuthorizationState(payload.state);
} catch (err) {
console.error('[workbench-events] remote authorization parse failed', err, e.data);
}
});
source.addEventListener('message.new', (e: MessageEvent) => {
const envelope = parseWorkbenchEnvelope<WorkbenchMessage>(e.data);
if (!envelope) return;
if (envelope.data.session_id) {
clearSessionReadCache(envelope.data.session_id);
} else {
clearReadCacheMatching((path) => path.startsWith('/api/inbox') || path.startsWith('/api/sessions'));
}
dispatchToWorkbenchHandlers((handlers) => {
handlers.onAny?.(envelope);
handlers.onMessageNew?.(envelope.data);
});
});
source.addEventListener('message.updated', (e: MessageEvent) => {
const envelope = parseWorkbenchEnvelope<WorkbenchMessage>(e.data);
if (!envelope?.data.session_id) return;
clearSessionReadCache(envelope.data.session_id);
dispatchToWorkbenchHandlers((handlers) => {
handlers.onAny?.(envelope);
handlers.onMessageUpdated?.(envelope.data);
});
});
source.addEventListener('session.activity', (e: MessageEvent) => {
const envelope = parseWorkbenchEnvelope<any>(e.data);
if (!envelope) return;
if (envelope.data.session_id) {
clearSessionReadCache(envelope.data.session_id);
if (envelope.data.event === 'archived') {
sessionDraftPersistence.clearSession(envelope.data.session_id);
}
} else {
clearReadCacheMatching((path) => path.startsWith('/api/inbox') || path.startsWith('/api/sessions'));
}
dispatchToWorkbenchHandlers((handlers) => {
handlers.onAny?.(envelope);
handlers.onSessionActivity?.(envelope.data);
});
});
source.addEventListener('inbox.unread.changed', (e: MessageEvent) => {
const envelope = parseWorkbenchEnvelope<any>(e.data);
if (!envelope) return;
clearReadCacheMatching((path) => path.startsWith('/api/inbox') || path.startsWith('/api/sessions'));
dispatchToWorkbenchHandlers((handlers) => {
handlers.onAny?.(envelope);
handlers.onInboxUnreadChanged?.(envelope.data);
});
});
source.addEventListener('inbox.session.updated', (e: MessageEvent) => {
const envelope = parseWorkbenchEnvelope<InboxSession>(e.data);
if (!envelope) return;
clearSessionReadCache(envelope.data.session_id);
dispatchToWorkbenchHandlers((handlers) => {
handlers.onAny?.(envelope);
handlers.onInboxSessionUpdated?.(envelope.data);
});
});
source.addEventListener('turn.start', (e: MessageEvent) => {
const envelope = parseWorkbenchEnvelope<{ session_id: string }>(e.data);
if (!envelope) return;
clearSessionReadCache(envelope.data.session_id);
dispatchToWorkbenchHandlers((handlers) => {
handlers.onAny?.(envelope);
handlers.onTurnStart?.(envelope.data);
});
});
source.addEventListener('turn.end', (e: MessageEvent) => {
const envelope = parseWorkbenchEnvelope<{ session_id: string }>(e.data);
if (!envelope) return;
clearSessionReadCache(envelope.data.session_id);
dispatchToWorkbenchHandlers((handlers) => {
handlers.onAny?.(envelope);
handlers.onTurnEnd?.(envelope.data);
});
});
source.addEventListener('session.status', (e: MessageEvent) => {
const envelope = parseWorkbenchEnvelope<{
session_id: string;
agent_status: 'idle' | 'running' | 'failed';
}>(e.data);
if (!envelope) return;
clearSessionReadCache(envelope.data.session_id);
dispatchToWorkbenchHandlers((handlers) => {
handlers.onAny?.(envelope);
handlers.onSessionStatus?.(envelope.data);
});
});
source.addEventListener('queue.updated', (e: MessageEvent) => {
const envelope = parseWorkbenchEnvelope<{ session_id: string }>(e.data);
if (!envelope) return;
clearSessionReadCache(envelope.data.session_id);
dispatchToWorkbenchHandlers((handlers) => {
handlers.onAny?.(envelope);
handlers.onQueueUpdated?.(envelope.data);
});
});
source.addEventListener('definitions.updated', (e: MessageEvent) => {
const envelope = parseWorkbenchEnvelope<{ definition_type?: string }>(e.data);
if (!envelope) return;
clearReadCacheMatching((path) => path.startsWith('/api/harness'));
dispatchToWorkbenchHandlers((handlers) => {
handlers.onAny?.(envelope);
handlers.onDefinitionsUpdated?.(envelope.data);
});
});
source.addEventListener('runs.updated', (e: MessageEvent) => {
const envelope = parseWorkbenchEnvelope<{
run_id: string;
status: HarnessRunStatus;
run_type?: string;
session_id?: string;
definition_id?: string;
updated_at?: string;
cancel_requested?: boolean;
}>(e.data);
if (!envelope) return;
clearReadCacheMatching((path) => path.startsWith('/api/harness'));
dispatchToWorkbenchHandlers((handlers) => {
handlers.onAny?.(envelope);
handlers.onRunsUpdated?.(envelope.data);
});
});
source.addEventListener('vaults.updated', (e: MessageEvent) => {
const envelope = parseWorkbenchEnvelope<{
scope: string;
request_id?: string;
request_status?: string;
grant_id?: string;
grant_status?: string;
secret_name?: string;
}>(e.data);
if (!envelope) return;
clearReadCacheMatching((path) => path.startsWith('/api/vault/'));
dispatchToWorkbenchHandlers((handlers) => {
handlers.onAny?.(envelope);
handlers.onVaultsUpdated?.(envelope.data);
});
});
source.addEventListener('remote_access.quality.changed', (e: MessageEvent) => {
const envelope = parseWorkbenchEnvelope<TunnelQualitySnapshot>(e.data);
if (!envelope) return;
dispatchToWorkbenchHandlers((handlers) => {
handlers.onAny?.(envelope);
handlers.onRemoteAccessQuality?.(envelope.data);
});
});
source.addEventListener('workbench.events.bridge.status', (e: MessageEvent) => {
if (eventSourceRef.current !== source) return;
const envelope = parseWorkbenchEnvelope<{ connected: boolean }>(e.data);
if (!envelope) return;
getWorkbenchEventReconnectLoop().streamOpened();
const previousLeg = eventControllerLegRef.current;
eventControllerLegRef.current = envelope.data.connected ? 'connected' : 'disconnected';
setWorkbenchEventConnectionState(envelope.data.connected ? 'connected' : 'reconnecting');
dispatchToWorkbenchHandlers((handlers) => {
handlers.onAny?.(envelope);
handlers.onEventBridgeStatus?.(envelope.data);
});
// A leg that was down and is now up is a gap that just ended. The browser
// socket stayed open across it, so no reconnect will announce this one --
// but the meaning is identical, so it arrives through the same signal, and
// consumers need no second concept to handle it. Only from `disconnected`:
// a new stream's opening report is the leg's state, not a recovery, and
// treating it as one would charge every connect a duplicate catch-up.
if (previousLeg === 'disconnected' && envelope.data.connected) {
dispatchToWorkbenchHandlers((handlers) => handlers.onConnected?.());
}
});
source.onerror = (err) => {
if (eventSourceRef.current !== source) return;
failWorkbenchEventStream();
// EventSource does not expose a failed response's status or JSON body.
// Probe through apiFetch, then inspect the successful /api/session form;
// both 401s and the 200 refresh payload enter the shared login recovery.
void apiFetch('/api/session', { cache: 'no-store' })
.then(recoverRemoteAuthFromSessionProbe)
.catch(() => undefined);
dispatchToWorkbenchHandlers((handlers) => handlers.onError?.(err));
};
}
const ensureWorkbenchEventSource = () => {
getWorkbenchEventReconnectLoop();
openWorkbenchEventSource();
};
const stopWorkbenchEventSource = () => {
closeActiveWorkbenchEventSource();
eventReconnectLoopRef.current?.stop();
eventReconnectLoopRef.current = null;
setWorkbenchEventConnectionState('reconnecting');
};
stopWorkbenchEventsRef.current = stopWorkbenchEventSource;
/**
* The page or the network came back. Catch the transport up; the stream then
* tells consumers whether anything was missed, by reconnecting or not.
*
* One owner, deliberately. Every consumer used to subscribe to the raw
* reactivation edge and refetch unconditionally, which is why returning to a
* tab cost a burst of reads that a healthy stream had already delivered. Now
* only a stream that cannot prove it survived the gap costs a catch-up, and
* consumers hear about it through the same `connected` signal an ordinary
* mid-session reconnect already used.
*
* `awaySince` is when the gap being recovered from opened, or null for one
* nothing can date -- a network return, or a page back from an away period
* the sampler never saw begin.
*/
const wakeWorkbenchEvents: PageReactivationListener = (awaySince) => {
if (eventHandlersRef.current.size === 0 || document.visibilityState !== 'visible') return;
// Read before waking, because waking is what changes the answer.
//
// Two questions, asked separately because they have different subjects. The
// transport one -- is this socket worth keeping -- is about the browser leg,
// and is the reconnect loop's. This one is about the whole path across an
// interval, so it is asked of every leg, by the one function that knows what
// the legs are; the browser leg's own verdict goes in as a term rather than
// standing in for the answer.
const survivedTheGap = streamCoveredGap({
browserLegLive: isWorkbenchBrowserLegLive(),
lastHeartbeatAt: eventHeartbeatAtRef.current,
controllerLeg: eventControllerLegRef.current,
awaySince,
intervalMs: eventHeartbeatIntervalRef.current,
now: Date.now(),
});
// The indicator belongs to whoever opens a stream: openWorkbenchEventSource
// marks it reconnecting on every attempt. Announcing it here instead made a
// wake that keeps a live stream flash "reconnecting" over a healthy one.
getWorkbenchEventReconnectLoop().wake();
// Timers are not trustworthy across a hidden period -- throttled, frozen,
// or fired while hidden and declined -- so re-establish the watch on a
// stream that was kept rather than reasoning about which of those happened.
// Idempotent: it re-arms off the surviving clock, and declines for a stream
// that was recycled or never declared a cadence.
armWorkbenchHeartbeatWatchdog();
// This edge owns its own catch-up. Deferring it to the replacement stream's
// handshake would make recovery depend on the thing being recovered: a
// server that is down, an offline network, or a backoff wait leaves the
// reconnect pending for as long as it takes, and until then a returning page
// shows whatever it had before it was hidden with nothing on the way. Paying
// it here is what the unconditional refetch did before this change, so a
// reactivation onto a broken stream costs no more than it used to; the
// replacement's later `connected` is a second catch-up in exactly the case
// that already paid for two.
if (!survivedTheGap) {
dispatchToWorkbenchHandlers((handlers) => handlers.onConnected?.());
}
};
resumeWorkbenchEventsRef.current = wakeWorkbenchEvents;
useEffect(() => {
const wakeIfVisible: PageReactivationListener = (awaySince) => {
if (document.visibilityState !== 'visible') return;
resumeWorkbenchEventsRef.current(awaySince);
syncSessionDraftsRef.current();
};
// Regaining the network is its own gap, independent of the page coming back,
// and an undated one: nothing here watched the connection drop, so no
// heartbeat can be placed inside it.
const wakeFromNetwork = () => wakeIfVisible(null);
const stopReactivation = onPageReactivated(wakeIfVisible);
window.addEventListener('online', wakeFromNetwork);
if (document.visibilityState === 'visible') syncSessionDraftsRef.current();
return () => {
stopReactivation();
window.removeEventListener('online', wakeFromNetwork);
stopWorkbenchEventsRef.current();
};
}, []);
const requestJson = async (
path: string,
init: RequestInit,
errorPath = path,
{
clearCache = true,
handleError = true,
expectedCodes,
}: {
clearCache?: boolean;
handleError?: boolean;
expectedCodes?: readonly string[];
} = {},
) => {
const res = await apiFetch(path, init);
if (!res.ok && handleError) {
await handleApiError(res, errorPath, { expectedCodes });
}
const payloadJson = await res.json().catch(() => ({}));
if (res.ok && clearCache) {
clearReadCache();
}
return { res, payloadJson };
};
const readSessionDraftServer = async (
sessionId: string,
timeoutMs = SESSION_DRAFT_RECONCILE_TIMEOUT_MS,
): Promise<SessionDraftServerState | null> => {
const controller = new AbortController();
const timeout = window.setTimeout(() => controller.abort(), timeoutMs);
try {
const res = await apiFetch(
`/api/sessions/${encodeURIComponent(sessionId)}/draft`,
{ signal: controller.signal },
);
if (!res.ok) return null;
return sessionDraftServerState(await res.json().catch(() => null));
} catch {
return null;
} finally {
window.clearTimeout(timeout);
}
};
const writeSessionDraft = async (
sessionId: string,
draft: SessionDraftWrite,
): Promise<SessionDraftSaveResult> => {
const controller = new AbortController();
let timedOut = false;
const timeout = window.setTimeout(() => {
timedOut = true;
controller.abort();
}, SESSION_DRAFT_WRITE_TIMEOUT_MS);
try {
const { res, payloadJson } = await requestJson(
`/api/sessions/${encodeURIComponent(sessionId)}/draft`,
{
method: 'PUT',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
text: draft.text,
expected_updated_at: draft.expectedUpdatedAt,
}),
signal: controller.signal,
},
`/api/sessions/${sessionId}/draft`,
{ handleError: false },
);
const hasServerDraft = payloadJson?.draft && typeof payloadJson.draft === 'object';
const server = sessionDraftServerState(payloadJson?.draft);
if (res.status === 409 && payloadJson?.code === 'draft_conflict') {
return { ok: false, conflict: true, server };
}
return res.ok
? { ok: true, ...(hasServerDraft ? { server } : {}) }
: { ok: false };
} catch (error) {
if (!timedOut) throw error;
// The request may have committed before its response stalled. Reconcile
// once before releasing queued successors so they inherit the actual
// cloud revision instead of manufacturing a conflict from uncertainty.
const server = await readSessionDraftServer(sessionId);
if (!server) return { ok: false };
if (server.text === draft.text) return { ok: true, server };
return server.updatedAt !== draft.expectedUpdatedAt
? { ok: false, conflict: true, server }
: {
ok: false,
server,
// The abort only stops waiting for the response; the synchronous
// server transaction may still commit. If the queued successor
// conflicts specifically with this text, rebase and retry once.
retryConflictIfServerText: draft.text,
};
} finally {
window.clearTimeout(timeout);
}
};
const rebaseAndRetrySessionDraft = async (
sessionId: string,
server: SessionDraftServerState,
): Promise<void> => {
sessionDraftPersistence.rebase(sessionId, server);
await sessionDraftPersistence.retry(
sessionId,
(draft) => writeSessionDraft(sessionId, draft),
);
};
syncSessionDraftsRef.current = () => {
void sessionDraftPersistence.retryAll(writeSessionDraft);
};
const postJson = async (
path: string,
payload: any,
opts?: { handleError?: boolean; expectedCodes?: readonly string[] },
) => {
const { payloadJson } = await requestJson(
path,
{
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(payload),
},
path,
opts,
);
return payloadJson;
};
// DELETE wrapper that routes 4xx/5xx through ``handleApiError`` so the
// global toast and console-error surface stay consistent with
// ``getJson``/``postJson``. New mutating helpers should route through
// requestJson/postJson/patchJson/deleteJson so successful mutations always
// invalidate reusable GET promises.
const deleteJson = async (
path: string,
payload?: any,
opts?: { handleError?: boolean; expectedCodes?: readonly string[] },
) => {
const { payloadJson } = await requestJson(path, {
method: 'DELETE',
...(payload === undefined
? {}
: {
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(payload),
}),
}, path, opts);
return payloadJson;
};
const patchJson = async (path: string, payload: any, opts?: { handleError?: boolean }) => {
const { payloadJson } = await requestJson(
path,
{
method: 'PATCH',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(payload),
},
path,
opts,
);
return payloadJson;
};
// The Bot routes answer a refusal with a coded, already-localized body
// (``_bot_error_response``). Read it here and reject with it, without the global
// toast: the dialog that asked shows the refusal in place.
const botRequest = async (path: string, init: RequestInit): Promise<Record<string, unknown>> => {
const { res, payloadJson } = await requestJson(path, init, path, { handleError: false });
if (!res.ok || payloadJson?.ok === false) {
const parsed = payloadJson && typeof payloadJson === 'object'
? selectApiErrorFields(payloadJson, `Request failed: ${path} (${res.status})`)
: null;
throw new ApiError(parsed?.fallback ?? `Request failed: ${path} (${res.status})`, res.status, parsed?.code ?? null);
}
return payloadJson as Record<string, unknown>;
};
const botFromResponse = (payload: Record<string, unknown>): Bot => {
const bot = parseBot(payload.bot);
if (!bot) throw new ApiError('The server returned no Bot', 0, null);
return bot;
};
const sleep = (ms: number) => new Promise((resolve) => window.setTimeout(resolve, ms));
const startAndPollDependencyInstall = async (dep: string): Promise<InstallResult> => {
const started = await postJson(`/api/dependencies/${encodeURIComponent(dep)}/install`, {});
const jobId = typeof started?.job_id === 'string' ? started.job_id : null;
if (!jobId) return started;
// Covers the 120s controller readiness bound plus the 300s CPA RPC bound.
const deadline = Date.now() + 430_000;
let last = started;
while (Date.now() < deadline) {
await sleep(1000);
last = await getJson(`/api/dependencies/${encodeURIComponent(dep)}/install/${encodeURIComponent(jobId)}`);
if (last?.status === 'succeeded' || last?.status === 'failed') {
return last;
}
}
return { ...last, ok: false, status: 'failed', message: t('settings.dependencies.installFailed') };
};
const startAndPollAgentInstall = async (name: string): Promise<InstallResult> => {
const started = await postJson(`/api/agent/${encodeURIComponent(name)}/install`, {});
const jobId = typeof started?.job_id === 'string' ? started.job_id : null;
if (!jobId) return started;
const serverBudgetSeconds = started?.poll_timeout_seconds;
const pollBudgetMs =
typeof serverBudgetSeconds === 'number' && Number.isFinite(serverBudgetSeconds)
? Math.max(310_000, serverBudgetSeconds * 1000)
: 390_000;
const deadline = Date.now() + pollBudgetMs;
let last = started;
while (Date.now() < deadline) {
await sleep(1000);
last = await getJson(
`/api/agent/${encodeURIComponent(name)}/install/${encodeURIComponent(jobId)}`,
);
if (last?.status === 'succeeded' || last?.status === 'failed') {
return last;
}
}
// ``last`` is still the running job, whose message announces the start.
return {
...last,
ok: false,
status: 'failed',
message: t('backendLifecycle.upgradeFailed'),
};
};
// ``useMemo`` is load-bearing here, not a perf tweak. Without it,
// ``ApiProvider`` produces a fresh ``value`` object on every render
// — including the renders triggered by ToastProvider's state
// updates above us in the tree. Each new ``value`` flips the
// identity of ``api`` for every ``useApi()`` consumer, so any
// ``useEffect(..., [api])`` re-runs on every toast.
//
// Concrete failure that this fix addresses (reported on iOS Safari
// for PR #282): clicking "Copy" on the Codex device-code block
// calls ``showToast('copied')`` → ToastProvider re-renders →
// ApiProvider re-renders → ``value`` identity changes →
// SettingsCodexProviderPage's mount effect re-runs → calls
// ``getCodexAuth()`` → reads the disk state (still ``apikey``
// because the OAuth flow hasn't completed) → ``setAuthMode("api_
// key")`` → the segmented radio flips back to API Key mid-login.
// Defensive patches at the event boundary (preventDefault,
// disabled buttons, setter guards) didn't help because the click
// wasn't the trigger — the cascading re-render was.
//
// ``[showToast, t]`` are intentional deps: ``showToast`` is stable
// (``useCallback`` in ToastContext) so it never invalidates by
// itself; ``t`` only changes on locale switch — recomputing then
// is correct (cached error messages would otherwise stay in the
// old language).
const value: ApiContextType = useMemo(() => ({
getConfig: (options) => (options?.cache === false
? getJson('/api/config')
: getCachedJson('/api/config', CONFIG_CACHE_TTL_MS)),
getPlatformCatalog: () => getJson('/api/platforms'),
mutateConfig: (mutations) => {
const save = async () => {
const config = await postJson('/api/config', configMutationsToPayload(mutations));
convergeConfig(config);
return config;
};
const touchesAgentActivity = mutations.some((mutation) => (
mutation.kind === 'set'
&& mutation.path.length <= 2
&& mutation.path.every((part, index) => part === ['ui', 'show_agent_activity'][index])
));
if (!touchesAgentActivity) return save();
const mutation = agentActivityConfigMutationTailRef.current
.catch(() => undefined)
.then(save);
agentActivityConfigMutationTailRef.current = mutation;
return mutation;
},
waitForAgentActivityConfigMutations: async () => {
// Include writes appended while the current tail is settling; return only
// when the provider's Agent Activity queue is actually idle.
while (true) {
const pending = agentActivityConfigMutationTailRef.current;
await pending.catch(() => undefined);
if (pending === agentActivityConfigMutationTailRef.current) return;
}
},
onConfigChanged,
getSettings: (platform) => getJson(platform ? `/api/settings?platform=${encodeURIComponent(platform)}` : '/api/settings'),
saveSettings: (payload, platform) => postJson('/api/settings', platform ? { ...payload, platform } : payload),
saveThreadSettings: (platform, channelId, threadId, settings) => postJson('/api/settings/thread', {
platform,
channel_id: channelId,
thread_id: threadId,
settings,
}),
patchScopeSettings: (request) => patchJson('/api/settings/scope', request),
deleteThreadSettings: (platform, channelId, threadId) => deleteJson(
`/api/settings/thread?platform=${encodeURIComponent(platform)}&channel_id=${encodeURIComponent(channelId)}&thread_id=${encodeURIComponent(threadId)}`,
),
getUsers: (platform) => getJson(platform ? `/api/users?platform=${encodeURIComponent(platform)}` : '/api/users'),
saveUsers: (payload, platform) => postJson('/api/users', platform ? { ...payload, platform } : payload),
toggleAdmin: (userId, isAdmin, platform) => postJson(`/api/users/${encodeURIComponent(userId)}/admin`, platform ? { is_admin: isAdmin, platform } : { is_admin: isAdmin }),
removeUser: (userId, platform) =>
deleteJson(platform ? `/api/users/${encodeURIComponent(userId)}?platform=${encodeURIComponent(platform)}` : `/api/users/${encodeURIComponent(userId)}`),
getShowPages: () => getJson('/api/show-pages'),
getShowPageAccess: (sessionId) => readShowPageJson(`/api/show-pages/${encodeURIComponent(sessionId)}/access`),
probeShowPageAccess: async (sessionId) => {
try {
const response = await apiFetch(`/api/show-pages/${encodeURIComponent(sessionId)}/access`);
let payload: unknown;
try {
payload = await response.json();
} catch {
return { status: 'error', access: null };
}
return classifyShowPageAccessProbe(response.status, payload);
} catch {
return { status: 'error', access: null };
}
},
getShowAccessSettings: (sessionId) => postJson(
`/api/show-pages/${encodeURIComponent(sessionId)}/access-settings/read`,
{ page_id: sessionId },
),
applyShowAccess: (sessionId, payload) => postJson(
`/api/show-pages/${encodeURIComponent(sessionId)}/access-settings/apply`,
{ page_id: sessionId, ...payload },
),
getNotificationPreferences: async () => {
const path = '/api/notifications/preferences';
const preferences = parseNotificationPreferences(await getJson(path, { handleError: false }));
if (!preferences) throw new ApiError(`Request failed: ${path}`, 0, null);
return preferences;
},
updateNotificationPreferences: async (changes) => {
const path = '/api/notifications/preferences';
const { res, payloadJson } = await requestJson(path, {
method: 'PUT',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(changes),
});
const saved = res.ok ? parseNotificationPreferences(payloadJson) : null;
if (!saved) throw new ApiError(`Request failed: ${path} (${res.status})`, res.status, null);
return saved;
},
getWebPushStatus: (payload) =>
payload ? postJson('/api/web-push/status', payload) : getJson('/api/web-push/status'),
getWebPushVapidPublicKey: () => getJson('/api/web-push/vapid-public-key'),
subscribeWebPush: (subscription, deviceLabel, deviceId, previousEndpoints, backgroundRotation) =>
postJson('/api/web-push/subscriptions', {
subscription,
device_label: deviceLabel,
device_id: deviceId,
previous_endpoints: previousEndpoints,
background_rotation: backgroundRotation,
}),
unsubscribeWebPush: (endpoint, deviceId) =>
deleteJson('/api/web-push/subscriptions', { endpoint, device_id: deviceId }),
sendWebPushTest: (payload) => postJson('/api/web-push/test', payload ?? {}),
setShowPageAvailability: (sessionId, offline) => postJson(
`/api/show-pages/${encodeURIComponent(sessionId)}/availability`,
{ offline },
),
getShowPage: (sessionId) => readShowPageJson(`/api/show-pages/${encodeURIComponent(sessionId)}`),
ensureShowPage: (sessionId) => postJson(`/api/show-pages/${encodeURIComponent(sessionId)}/ensure`, {}),
uploadShowPageIcon: async (sessionId, file) => {
// Multipart POST: the server names the on-disk file, so we send only the bytes
// and a filename hint. `requestJson` adds CSRF + surfaces errors like everything
// else; letting the browser set the multipart Content-Type/boundary (no JSON).
const form = new FormData();
form.append('file', file, file.name);
const { payloadJson } = await requestJson(
`/api/show-pages/${encodeURIComponent(sessionId)}/icon`,
{ method: 'POST', body: form },
);
return payloadJson;
},
getDock: () => getJson('/api/dock'),
pinDockShowPage: (sessionId) => postJson('/api/dock/pins', { session_id: sessionId }),
unpinDockShowPage: (sessionId) => deleteJson(`/api/dock/pins/${encodeURIComponent(sessionId)}`),
setDockOrder: async (order, known) => {
// Suppress the global error toast: a stale-reorder rejection (the server
// rejects an order whose ``known`` baseline no longer matches its installed
// set) is handled by the optimistic re-sync in DockContext, not a
// user-facing error. ``known`` is the client's current id set (built-ins ∪
// pins), sent so the server can reject a stale tab that would otherwise
// silently undock a pin another tab installed. The caller inspects ``ok``.
const { payloadJson } = await requestJson(
'/api/dock/order',
{
method: 'PUT',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(known ? { order, known } : { order }),
},
'PUT /api/dock/order',
{ handleError: false },
);
return payloadJson;
},
getWorkbenchPrefs: () => getCachedJson('/api/workbench/prefs', 5_000),
setBackgroundWorkBannerEnabled: async (enabled) => {
// Default handleError:true — a non-2xx (auth/CSRF/server) throws so the
// caller reverts its optimistic switch instead of diverging from the
// persisted value.
const { payloadJson } = await requestJson(
'/api/workbench/prefs',
{
method: 'PUT',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ background_work_banner_enabled: enabled }),
},
'PUT /api/workbench/prefs',
);
return payloadJson;
},
setFastModeDefault: async (enabled) => {
// A remembered preference, written behind the pick it follows: a failure
// only leaves the next new Session on the previous default.
const { payloadJson } = await requestJson(
'/api/workbench/prefs',
{
method: 'PUT',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ fast_mode_default: enabled }),
},
'PUT /api/workbench/prefs',
{ handleError: false, clearCache: false },
);
readCacheRef.current.delete('/api/workbench/prefs');
return payloadJson;
},
getBindCodes: () => getJson('/api/bind-codes'),
createBindCode: (type, expiresAt) => postJson('/api/bind-codes', { type, expires_at: expiresAt }),
deleteBindCode: (code) => deleteJson(`/api/bind-codes/${encodeURIComponent(code)}`),
getFirstBindCode: () => getJson('/api/setup/first-bind-code'),
detectCli: async (binary, backend) => {
if (!backend) return getJson(`/api/cli/detect?binary=${encodeURIComponent(binary)}`);
// One owner observation supplies both the host status and its lifecycle
// chip; do not immediately launch a second independent version probe.
const runtime: BackendRuntimeInfo = await getJson(`/api/backend/${encodeURIComponent(backend)}/runtime?cli_path=${encodeURIComponent(binary)}`);
return { found: runtime.installed === true, path: runtime.resolved_path ?? null,
status: runtime.status ?? 'unknown', version: runtime.current_version,
reason: runtime.reason, runtime };
},
installAgent: (name) => startAndPollAgentInstall(name),
listDependencies: ({ ids, signal } = {}) => {
const params = new URLSearchParams();
for (const id of ids ?? []) params.append('id', id);
const query = params.toString();
const path = `/api/dependencies${query ? `?${query}` : ''}`;
return withApiDeadline(15_000, signal, (requestSignal) => getJson(path, { signal: requestSignal }));
},
getMacOSLoginSessionStatus: () => getJson('/api/macos/login-session'),
installDependency: (dep) => startAndPollDependencyInstall(dep),
getBackendConnection: (name) => getJson(`/api/backend/${encodeURIComponent(name)}/connection`),
getBackendRuntime: (name, cliPath) => getJson(`/api/backend/${encodeURIComponent(name)}/runtime${cliPath === undefined ? '' : `?cli_path=${encodeURIComponent(cliPath)}`}`),
restartBackend: (name) => postJson(`/api/backend/${encodeURIComponent(name)}/restart`, {}),
getCodexAuth: () => getJson('/api/backend/codex/auth'),
saveCodexAuth: (payload) => postJson('/api/backend/codex/auth', payload),
getClaudeAuth: () => getJson('/api/backend/claude/auth'),
saveClaudeAuth: (payload) => postJson('/api/backend/claude/auth', payload),
startOAuthWeb: (backend, forceReset = true) =>
postJson(`/api/backend/${encodeURIComponent(backend)}/auth/oauth/start`, {
force_reset: forceReset,
}),
startOAuthWebForOpencodeProvider: (providerId, forceReset = true) =>
postJson(
`/api/backend/opencode/provider/${encodeURIComponent(providerId)}/auth/oauth/start`,
{ force_reset: forceReset },
),
getOAuthWebStatus: (backend, flowId) =>
getJson(
`/api/backend/${encodeURIComponent(backend)}/auth/oauth/status/${encodeURIComponent(flowId)}`,
),
submitOAuthWebCode: (backend, flowId, code) =>
postJson(`/api/backend/${encodeURIComponent(backend)}/auth/oauth/submit-code`, {
flow_id: flowId,
code,
}),
cancelOAuthWeb: (backend, flowId) =>
postJson(`/api/backend/${encodeURIComponent(backend)}/auth/oauth/cancel`, {
flow_id: flowId,
}),
removeBackendAuth: (backend) =>
postJson(`/api/backend/${encodeURIComponent(backend)}/auth/oauth/remove`, {}),
removeClaudeOAuthCredentials: () =>
postJson('/api/backend/claude/auth/oauth/credentials/remove', {}),
removeBackendApiKey: (backend) =>
postJson(`/api/backend/${encodeURIComponent(backend)}/auth/api-key/remove`, {}),
testBackendAuth: (backend, options) =>
postJson(`/api/backend/${encodeURIComponent(backend)}/auth/test`, {
...(options?.model ? { model: options.model } : {}),
}),
testOpencodeProvider: (providerId, options) =>
postJson(`/api/backend/opencode/provider/${encodeURIComponent(providerId)}/test`, {
...(options?.model ? { model: options.model } : {}),
}),
getOpencodeProviders: () => getJson('/api/backend/opencode/providers'),
// Model pickers absorb the expected Owner-only refusal and retain typed-value
// fallback. Keep that policy on this dedicated reader so direct options calls
// still report access failures and no picker can forget the suppression.
readOpencodeOptionsForModelPicker: () =>
postJson('/api/opencode/options', { cwd: '~' }, {
expectedCodes: ['instance_access_forbidden'],
}),
saveOpencodeCustomProvider: (payload) =>
postJson('/api/backend/opencode/custom-provider', payload),
deleteOpencodeCustomProvider: (providerId) =>
deleteJson(`/api/backend/opencode/custom-provider/${encodeURIComponent(providerId)}`),
setOpencodeProviderAuth: (providerId, apiKey, baseUrl) =>
// Forward ``base_url`` only when the caller passed something
// (including an explicit empty string for "clear"); omitting it
// entirely tells the server to leave the stored value untouched,
// which is the right default for callers that don't care about
// the base-URL override.
postJson(`/api/backend/opencode/provider/${encodeURIComponent(providerId)}/auth`, {
api_key: apiKey,
...(baseUrl !== undefined ? { base_url: baseUrl } : {}),
}),
deleteOpencodeProviderAuth: (providerId) =>
deleteJson(`/api/backend/opencode/provider/${encodeURIComponent(providerId)}/auth`),
setOpencodeDefaultProvider: (providerId) =>
postJson('/api/backend/opencode/default-provider', { provider_id: providerId }),
saveOpencodeProviderModel: (providerId, payload) =>
postJson(`/api/backend/opencode/provider/${encodeURIComponent(providerId)}/models`, payload),
deleteOpencodeProviderModel: (providerId, modelId) =>
deleteJson(
`/api/backend/opencode/provider/${encodeURIComponent(providerId)}/models/${encodeURIComponent(modelId)}`,
),
slackAuthTest: (botToken, proxyUrl) => postJson('/api/slack/auth_test', { bot_token: botToken, proxy_url: proxyUrl || undefined }),
slackChannels: (botToken, browseAll, force, includeNotReturned) => postJson('/api/slack/channels', { bot_token: botToken, browse_all: browseAll || false, force: force || false, include_not_returned: includeNotReturned || false }),
slackManifest: () => getJson('/api/slack/manifest'),
discordAuthTest: (botToken, proxyUrl) => postJson('/api/discord/auth_test', { bot_token: botToken, proxy_url: proxyUrl || undefined }),
discordGuilds: (botToken) => postJson('/api/discord/guilds', { bot_token: botToken }),
discordChannels: (botToken, guildId, force, includeNotReturned) => postJson('/api/discord/channels', { bot_token: botToken, guild_id: guildId, force: force || false, include_not_returned: includeNotReturned || false }),
telegramAuthTest: (botToken, proxyUrl) => postJson('/api/telegram/auth_test', { bot_token: botToken, proxy_url: proxyUrl || undefined }),
telegramChats: (includePrivate, includeNotReturned) => postJson('/api/telegram/chats', { include_private: includePrivate || false, include_not_returned: includeNotReturned || false }),
larkAuthTest: (appId, appSecret, domain, proxyUrl) => postJson('/api/lark/auth_test', { app_id: appId, app_secret: appSecret, domain: domain || 'feishu', proxy_url: proxyUrl || undefined }),
larkChats: (appId, appSecret, domain, force, includeNotReturned) => postJson('/api/lark/chats', { app_id: appId, app_secret: appSecret, domain: domain || 'feishu', force: force || false, include_not_returned: includeNotReturned || false }),
deleteChannel: (platform, id, scopeType) => postJson('/api/channels/delete', { platform, id, scope_type: scopeType || 'channel' }),
larkTempWsStart: (appId, appSecret, domain) => postJson('/api/lark/temp_ws/start', { app_id: appId, app_secret: appSecret, domain: domain || 'feishu' }),
larkTempWsStop: () => postJson('/api/lark/temp_ws/stop', {}),
wechatStartLogin: () => postJson('/api/wechat/qr_login/start', {}),
wechatPollLogin: (sessionKey, verifyCode) => postJson('/api/wechat/qr_login/poll', { session_key: sessionKey, verify_code: verifyCode || undefined }),
doctor: (options = {}) => postJson('/api/doctor', options.deep ? { deep: true } : {}),
opencodeOptions: (cwd) => postJson('/api/opencode/options', { cwd }),
opencodeSetupPermission: () => postJson('/api/opencode/setup-permission', {}),
opencodePermissionStatus: () => getJson('/api/opencode/permission-status'),
claudeAgents: (cwd) => cwd ? getJson(`/api/claude/agents?cwd=${encodeURIComponent(cwd)}`) : getJson('/api/claude/agents'),
claudeModels: () => getJson('/api/claude/models'),
codexAgents: (cwd) => cwd ? getJson(`/api/codex/agents?cwd=${encodeURIComponent(cwd)}`) : getJson('/api/codex/agents'),
codexModels: () => getJson('/api/codex/models'),
// Direct mode, rolling upgrades, and a temporarily unreadable Hub catalog
// all keep the existing native picker behavior without surfacing a toast.
readModelHubAgentCatalogForModelPicker: (backend) =>
getJson(`/api/models/agents/${encodeURIComponent(backend)}/models`, { handleError: false })
.then((payload) => {
const agent = payload?.ok === false ? null : payload?.agent;
return agent && typeof agent === 'object'
? (agent as PickerAgentCatalog)
: null;
})
.catch(() => null),
getLogs: (lines = 500, source) => postJson('/api/logs', source ? { lines, source } : { lines }),
getVersion: (options) => options?.background
? withApiDeadline(10_000, options.signal, async (signal) => {
const response = await apiFetch('/api/version', { signal });
// Reconnect failures belong to the update status, not repeated toasts.
if (!response.ok) throw new ApiError('Version read unavailable', response.status, null);
const payload = await response.json();
if (typeof payload?.current !== 'string') throw new Error('Invalid version response');
return payload as VersionInfo;
})
: getCachedJson('/api/version', 10_000, options),
requestDesktopUpdate: async (targetVersion, options) => {
const { res, payloadJson } = await requestJson(
'/api/desktop/update/request',
{
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
target_version: targetVersion,
confirm_interrupt: options?.confirmInterrupt ?? false,
}),
},
'/api/desktop/update/request',
{ handleError: false },
);
if (!res.ok && !['not_desktop_managed', 'no_update_available', 'update_in_progress',
'desktop_shell_unavailable', 'confirmation_required'].includes(payloadJson?.error)) {
throw new ApiError('Desktop update request failed', res.status, payloadJson?.error ?? null);
}
return payloadJson as DesktopRemoteUpdateResult;
},
doUpgrade: async (options) => {
if (!options) return postJson('/api/upgrade', {});
const { res, payloadJson } = await requestJson('/api/upgrade', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ confirm_interrupt: options.confirmInterrupt }),
}, '/api/upgrade', { handleError: false });
if (!res.ok && payloadJson?.error !== 'confirmation_required') {
throw new ApiError('Upgrade request failed', res.status, payloadJson?.error ?? null);
}
return payloadJson as UpgradeResult;
},
browseDirectory: (path, showHidden) => postJson('/api/browse', { path, show_hidden: showHidden || false }),
browseFavorites: () => getJson('/api/browse/favorites'),
browseMkdir: (path) => postJson('/api/browse/mkdir', { path }),
listProjects: (includeArchived, options) => {
const path = `/api/projects${includeArchived ? '?include_archived=1' : ''}`;
return options?.cache === false ? getJson(path) : getCachedJson(path);
},
getWorkbenchProjectsBootstrap: (params) => {
const search = new URLSearchParams();
if (params?.includeArchived) search.set('include_archived', '1');
if (params?.status) search.set('status', params.status);
if (params?.limit) search.set('limit', String(params.limit));
for (const projectId of params?.projectIds ?? []) {
search.append('project_id', projectId);
}
const qs = search.toString();
const path = qs ? `/api/workbench/projects-bootstrap?${qs}` : '/api/workbench/projects-bootstrap';
return params?.cache === false ? getJson(path) : getCachedJson(path);
},
createProject: (payload) => postJson('/api/projects', payload),
reorderProjects: async (order, expectedOrder) => {
try {
const { payloadJson } = await requestJson('/api/projects/order', {
method: 'PUT',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ order, expected_order: expectedOrder }),
});
return payloadJson;
} catch (error) {
if (!(error instanceof ApiError)) showToast(t('errors.invalid_project_order'), 'error');
throw error;
}
},
updateProject: async (projectId, payload) => {
const { payloadJson } = await requestJson(`/api/projects/${encodeURIComponent(projectId)}`, {
method: 'PATCH',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(payload),
}, `PATCH /api/projects/${projectId}`);
return payloadJson;
},
archiveProject: (projectId) => deleteJson(`/api/projects/${encodeURIComponent(projectId)}`),
getProjectAgentsMd: (projectId) =>
getJson(`/api/projects/${encodeURIComponent(projectId)}/agents-md`),
saveProjectAgentsMd: async (projectId, payload) => {
const { payloadJson } = await requestJson(`/api/projects/${encodeURIComponent(projectId)}/agents-md`, {
method: 'PUT',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(payload),
}, `PUT /api/projects/${projectId}/agents-md`);
return payloadJson;
},
getGlobalPrompts: () => getJson('/api/global-prompts'),
saveGlobalPrompts: async (payload) => {
const { payloadJson } = await requestJson('/api/global-prompts', {
method: 'PUT',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(payload),
});
return payloadJson;
},
listSessions: (params) => {
const search = new URLSearchParams();
if (params?.projectId) search.set('project_id', params.projectId);
if (params?.status) search.set('status', params.status);
if (params?.limit) search.set('limit', String(params.limit));
if (params?.beforeId) search.set('before_id', params.beforeId);
if (params?.q) search.set('q', params.q);
const qs = search.toString();
const path = qs ? `/api/sessions?${qs}` : '/api/sessions';
return params?.cache === false ? getJson(path) : getCachedJson(path);
},
createSession: (payload) => postJson('/api/sessions', payload),
forkSession: (sessionId) =>
postJson(`/api/sessions/${encodeURIComponent(sessionId)}/fork`, {}),
getSession: async (sessionId, params) => {
const payload = params?.cache === false
? await getJson(`/api/sessions/${encodeURIComponent(sessionId)}`, { handleError: params?.handleError })
: await getCachedJson(`/api/sessions/${encodeURIComponent(sessionId)}`, undefined, { handleError: params?.handleError });
return sessionRowFromPayload(payload);
},
getMainSession: async () => {
const res = await apiFetch('/api/sessions/main');
const payload = await res.json().catch(() => null);
const sessionPayload = payload && typeof payload === 'object' && 'session' in payload
? (payload as { session?: unknown }).session
: payload;
if (!(res.ok && sessionPayload && typeof sessionPayload === 'object' && typeof (sessionPayload as { id?: unknown }).id === 'string')) {
return { status: res.status, session: null };
}
return {
status: res.status,
session: sessionRowFromPayload(sessionPayload as WorkbenchSession & { capabilities?: unknown }),
capabilities: sessionCanChatFromPayload(payload),
};
},
ensureDesktopMiniSession: async () => {
// No global toast: the pet shows its own copy. Errors still reject, with the code.
const res = await apiFetch('/api/desktop-mini/session', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({}),
});
const payload = await res.json().catch(() => null);
if (!res.ok || !payload || typeof payload.id !== 'string') {
const parsed = selectApiErrorFields(payload, `Request failed: /api/desktop-mini/session (${res.status})`);
throw new ApiError(parsed?.fallback ?? `Request failed (${res.status})`, res.status, parsed?.code ?? null);
}
clearReadCacheMatching((path) => path.startsWith('/api/sessions') || path.startsWith('/api/workbench/projects-bootstrap'));
return sessionRowFromPayload(payload);
},
getSessionResult: async (sessionId) => {
const res = await apiFetch(`/api/sessions/${encodeURIComponent(sessionId)}`);
const payload = await res.json().catch(() => null);
if (!(res.ok && payload && typeof payload.id === 'string')) {
return { status: res.status, session: null };
}
return {
status: res.status,
session: sessionRowFromPayload(payload),
capabilities: sessionCanChatFromPayload(payload),
};
},
getSessionBootstrap: async (sessionId) => {
const read = sessionDraftPersistence.beginRead(sessionId);
try {
const payload = await getJson(`/api/sessions/${encodeURIComponent(sessionId)}/bootstrap`);
if (payload?.session?.status === 'archived') {
sessionDraftPersistence.clearSession(sessionId);
return payload;
}
const server = sessionDraftServerState(payload?.draft);
const text = sessionDraftPersistence.reconcileRead(sessionId, read, server);
void sessionDraftPersistence.retry(
sessionId,
(draft) => writeSessionDraft(sessionId, draft),
);
return text === server.text
? payload
: { ...payload, draft: { ...(payload.draft ?? {}), text } };
} catch (error) {
sessionDraftPersistence.releaseRead(sessionId, read);
throw error;
}
},
updateSession: async (sessionId, payload) => {
const { payloadJson } = await requestJson(`/api/sessions/${encodeURIComponent(sessionId)}`, {
method: 'PATCH',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(payload),
}, `PATCH /api/sessions/${sessionId}`);
return payloadJson;
},
archiveSession: async (sessionId) => {
const payload = await deleteJson(`/api/sessions/${encodeURIComponent(sessionId)}`);
sessionDraftPersistence.clearSession(sessionId);
return payload;
},
convergeSessionArchived,
onSessionArchived,
getArchivePreview: (sessionId) =>
getJson(`/api/sessions/${encodeURIComponent(sessionId)}/archive-preview`),
listSessionMessages: (sessionId, params) => {
const search = new URLSearchParams();
if (params?.afterId) search.set('after_id', params.afterId);
if (params?.beforeId) search.set('before_id', params.beforeId);
if (params?.aroundId) search.set('around_id', params.aroundId);
if (params?.aroundNativeId) search.set('around_native_id', params.aroundNativeId);
if (params?.aroundNativePlatform) search.set('around_native_platform', params.aroundNativePlatform);
if (params?.aroundTurnId) search.set('around_turn_id', params.aroundTurnId);
if (params?.aroundRunId) search.set('around_run_id', params.aroundRunId);
if (params?.limit) search.set('limit', String(params.limit));
if (params?.tail) search.set('tail', '1');
const qs = search.toString();
const base = `/api/sessions/${encodeURIComponent(sessionId)}/messages`;
const path = qs ? `${base}?${qs}` : base;
return params?.cache === false ? getJson(path) : getCachedJson(path);
},
getSessionActivity: (sessionId) =>
// Uncached: this is also the gap-recovery resync path, so it must reflect
// durable state (not a stale read served after a missed message.new).
getJson(`/api/sessions/${encodeURIComponent(sessionId)}/activity`),
getSessionActivityGroup: (sessionId, groupId) =>
getJson(
`/api/sessions/${encodeURIComponent(sessionId)}/activity?group_id=${encodeURIComponent(groupId)}`,
),
searchMessages: (q, opts) => {
const search = new URLSearchParams();
search.set('q', q);
if (opts?.limit) search.set('limit', String(opts.limit));
if (opts?.includeArchived) search.set('include_archived', '1');
return getJson(`/api/search/messages?${search.toString()}`);
},
sendSessionMessage: (sessionId, payload) =>
postJson(`/api/sessions/${encodeURIComponent(sessionId)}/messages`, payload),
markSessionRead: (sessionId, untilMessageId, opts) =>
postJson(
`/api/sessions/${encodeURIComponent(sessionId)}/mark-read`,
untilMessageId ? { until_message_id: untilMessageId } : {},
opts,
),
cancelSession: async (sessionId) => {
const { res, payloadJson } = await requestJson(`/api/sessions/${encodeURIComponent(sessionId)}/cancel`, {
method: 'POST',
}, `/api/sessions/${sessionId}/cancel`, { handleError: false });
// 503 + 404 are surfaced to the caller as plain payloads so the
// UI can render a sensible "nothing to stop" / "socket down"
// state without throwing.
return { ok: res.ok, ...payloadJson };
},
listSessionQueue: (sessionId, options) => {
const path = `/api/sessions/${encodeURIComponent(sessionId)}/queue`;
return options?.cache === false ? getJson(path) : getCachedJson(path);
},
removeQueuedMessage: (sessionId, messageId) =>
deleteJson(`/api/sessions/${encodeURIComponent(sessionId)}/queue/${encodeURIComponent(messageId)}`),
sendQueuedNow: async (sessionId, messageId) => {
const { res, payloadJson } = await requestJson(
`/api/sessions/${encodeURIComponent(sessionId)}/queue/${encodeURIComponent(messageId)}/send-now`,
{ method: 'POST' },
`/api/sessions/${sessionId}/queue/${messageId}/send-now`,
{ handleError: false },
);
return { ok: res.ok, ...payloadJson };
},
getTurnState: async (sessionId, options) => {
const path = `/api/sessions/${encodeURIComponent(sessionId)}/turn-state`;
const res = await apiFetch(path);
if (res.status === 504) {
readCacheRef.current.delete(path);
return {
in_flight: null,
foreground: 'unknown',
native_turn_started: false,
pending_input_count: 0,
background_activities: [],
pending_activity_output_count: 0,
connection: 'unknown',
};
}
if (!res.ok) {
if (options?.handleError === false) {
throw new ApiError(`Request failed: ${path} (${res.status})`, res.status, null);
}
await handleApiError(res, path);
}
return res.json();
},
getCachedSessionDraft: (sessionId) => sessionDraftPersistence.peek(sessionId),
cacheSessionDraft: (sessionId, text) => sessionDraftPersistence.cache(sessionId, text),
getSessionDraft: async (sessionId) => {
const read = sessionDraftPersistence.beginRead(sessionId);
try {
const payload = await getJson(`/api/sessions/${encodeURIComponent(sessionId)}/draft`);
const server = sessionDraftServerState(payload);
const text = sessionDraftPersistence.reconcileRead(sessionId, read, server);
void sessionDraftPersistence.retry(
sessionId,
(draft) => writeSessionDraft(sessionId, draft),
);
return { text };
} catch (error) {
sessionDraftPersistence.releaseRead(sessionId, read);
throw error;
}
},
setSessionDraft: (sessionId, text) => sessionDraftPersistence.save(
sessionId,
text,
(draft) => writeSessionDraft(sessionId, draft),
),
reconcileSessionDraftAfterSend: (sessionId, draft) => (
rebaseAndRetrySessionDraft(sessionId, sessionDraftServerState(draft))
),
recoverSessionDraftAfterRejectedSend: async (sessionId) => {
// The message reservation clears the cloud draft before dispatch. A
// rejected/unknown dispatch therefore needs an authoritative revision
// before the composer's optimistic text restoration is replayed.
sessionDraftPersistence.markRejectedSend(sessionId);
const server = await readSessionDraftServer(sessionId);
if (!server) return;
await rebaseAndRetrySessionDraft(sessionId, server);
},
listInbox: (params) => {
const search = new URLSearchParams();
if (params?.platform) search.set('platform', params.platform);
if (params?.unreadOnly) search.set('unread_only', '1');
if (params?.limit) search.set('limit', String(params.limit));
if (params?.before) search.set('before', params.before);
if (params?.onlySession) search.set('session', params.onlySession);
const qs = search.toString();
const path = qs ? `/api/inbox?${qs}` : '/api/inbox';
if (params?.backgroundPush) {
// A Push-triggered page read is non-interactive just like the worker's
// own read. Bypass the shared cache and never adopt an error as an empty map.
return apiFetch(path, { headers: { 'X-Avibe-Background-Push': '1' } }).then(async (response) => {
if (!response.ok) throw new Error(`Background Inbox refresh failed (${response.status})`);
return response.json();
});
}
const options = { handleError: params?.handleError };
return params?.cache === false ? getJson(path, options) : getCachedJson(path, 1500, options);
},
listBots: async (params) => {
const payload = params?.cache === false
? await getJson('/api/bots', { handleError: false })
: await getCachedJson('/api/bots', 1500, { handleError: false });
if (!payload || payload.ok === false || !Array.isArray(payload.bots)) {
const parsed = payload ? selectApiErrorFields(payload, 'Request failed: /api/bots') : null;
throw new ApiError(parsed?.fallback ?? 'Request failed: /api/bots', 0, parsed?.code ?? null);
}
return (payload.bots as unknown[]).map(parseBot).filter((bot): bot is Bot => bot !== null);
},
createBot: async (payload) => botFromResponse(await botRequest('/api/bots', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(payload),
})),
setBot: async (payload) => botFromResponse(await botRequest('/api/bots/set', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(payload),
})),
updateBot: async (handle, payload) => botFromResponse(await botRequest(`/api/bots/${encodeURIComponent(handle)}`, {
method: 'PATCH',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(payload),
})),
removeBot: async (handle) => {
await botRequest(`/api/bots/${encodeURIComponent(handle)}`, { method: 'DELETE' });
},
uploadBotAvatar: async (handle, image) => botFromResponse(await botRequest(
`/api/bots/${encodeURIComponent(handle)}/avatar`,
{ method: 'PUT', headers: { 'Content-Type': image.type || 'application/octet-stream' }, body: image },
)),
suggestBotHandle: async (payload, options) => {
const body = await botRequest('/api/bots/handle-suggestion', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(payload),
signal: options?.signal,
});
return { handle: String(body.handle ?? ''), source: String(body.source ?? '') };
},
listVibeAgents: (params) => {
const search = new URLSearchParams();
if (params?.backend) search.set('backend', params.backend);
if (params?.includeDisabled) search.set('include_disabled', '1');
if (params?.includeArchived) search.set('include_archived', '1');
const qs = search.toString();
const path = qs ? `/api/agents?${qs}` : '/api/agents';
return params?.cache === false ? getJson(path) : getCachedJson(path, 5_000);
},
getVibeAgentOnboarding: () => getJson('/api/agent-onboarding'),
onboardVibeAgents: () => postJson('/api/agent-onboarding', {}),
getVibeAgent: (name, params) => {
const path = `/api/agents/${encodeURIComponent(name)}`;
return params?.cache === false
? getJson(path, { handleError: params.handleError, expectedCodes: params.expectedCodes })
: getCachedJson(path, 5_000, { handleError: params?.handleError });
},
createVibeAgent: (payload) => postJson('/api/agents', payload),
updateVibeAgent: async (name, payload) => {
const { payloadJson } = await requestJson(`/api/agents/${encodeURIComponent(name)}`, {
method: 'PATCH',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(payload),
}, `PATCH /api/agents/${name}`);
return payloadJson;
},
setDefaultVibeAgent: (name) => postJson('/api/agents/default', { name }),
removeVibeAgent: (name) => deleteJson(`/api/agents/${encodeURIComponent(name)}`),
getVaultVmk: () => getCachedJson('/api/vault/vmk', 1500, { handleError: false }),
listVaultSecrets: (opts) => getCachedJson('/api/vault/secrets', 1500, opts),
getVaultPubkey: () => getCachedJson('/api/vault/pubkey', 1500),
getVaultAgentPubkey: () => getCachedJson('/api/vault/agent/pubkey', 1500),
getAvaultAuthorization: async () => {
// Polled while an attempt runs: a failed read rejects quietly, so the caller keeps
// its last status and keeps polling instead of taking an error body for a status.
const path = '/api/vault/avault-authorization';
const res = await apiFetch(path);
if (!res.ok) throw new ApiError(`Request failed: ${path} (${res.status})`, res.status, null);
return res.json();
},
authorizeAvault: () => postJson('/api/vault/avault-authorization', {}),
getVaultSandboxRootMetadata: () => getCachedJson('/api/vault/sandbox/root-metadata', 1500, { handleError: false }),
createVaultAgentBindingsBatch: (payload) =>
postJson('/api/vault/agent-bindings:batch', payload, { handleError: false }),
getVaultSettings: () => getJson('/api/vault/settings', { handleError: false }),
saveVaultSettings: (payload) => patchJson('/api/vault/settings', payload, { handleError: false }),
createVaultRevealContext: (name, payload) =>
postJson(`/api/vault/secrets/${encodeURIComponent(name)}/reveal-context`, payload ?? {}, { handleError: false }),
deriveSigningAddresses: (publicKey) =>
postJson('/api/vault/signing-addresses', { public_key: publicKey }, { handleError: false }),
createVaultAuthzWebAuthnOptions: () => postJson('/api/vault/authz/factors/webauthn/options', {}),
registerVaultAuthzWebAuthnFactor: (payload) => postJson('/api/vault/authz/factors/webauthn', payload),
createVaultSecret: (payload, opts) => postJson('/api/vault/secrets', payload, opts),
updateVaultSecret: (name, payload, opts) => patchJson(`/api/vault/secrets/${encodeURIComponent(name)}`, payload, opts),
updateVaultSecretField: async (name, field, payload, opts) => {
const path = `/api/vault/secrets/${encodeURIComponent(name)}/fields/${encodeURIComponent(field)}`;
const { payloadJson } = await requestJson(path, {
method: 'PUT',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(payload),
}, path, opts);
return payloadJson;
},
deleteVaultSecretField: (name, field, payload) =>
deleteJson(
`/api/vault/secrets/${encodeURIComponent(name)}/fields/${encodeURIComponent(field)}`,
payload,
{ handleError: false },
),
deleteVaultSecret: (name) => deleteJson(`/api/vault/secrets/${encodeURIComponent(name)}`),
getVaultProvisionRequest: (name, opts) =>
getCachedJson(`/api/vault/provision-requests/${encodeURIComponent(name)}`, 1500, opts),
getVaultProvisionRequestById: (requestId, opts) =>
getCachedJson(`/api/vault/provision-requests/by-id/${encodeURIComponent(requestId)}`, 1500, opts),
getVaultRequests: (params, opts) => {
const search = new URLSearchParams();
if (params?.status) search.set('status', params.status);
if (params?.type) search.set('type', params.type);
if (params?.limit) search.set('limit', String(params.limit));
if (params?.session) search.set('session', params.session);
const qs = search.toString();
return getCachedJson(qs ? `/api/vault/requests?${qs}` : '/api/vault/requests', 1500, opts);
},
denyVaultRequest: (requestId) => postJson(`/api/vault/requests/${encodeURIComponent(requestId)}/deny`, {}),
approveVaultDeleteRequest: (requestId) => postJson(`/api/vault/requests/${encodeURIComponent(requestId)}/approve-delete`, {}),
fulfillVaultAccessRequest: (requestId, payload) =>
postJson(`/api/vault/requests/${encodeURIComponent(requestId)}/fulfill-access`, payload),
getVaultGrants: (params, opts) => {
const search = new URLSearchParams();
if (params?.status) search.set('status', params.status);
if (params?.sessionId) search.set('session_id', params.sessionId);
const qs = search.toString();
return getCachedJson(qs ? `/api/vault/grants?${qs}` : '/api/vault/grants', 1500, opts);
},
createVaultGrant: (payload) => postJson('/api/vault/grants', payload),
revokeVaultGrant: (grantId) => deleteJson(`/api/vault/grants/${encodeURIComponent(grantId)}`),
signVaultDigest: (payload) => postJson('/api/vault/sign', payload),
pinVaultPubkey: (payload) => postJson('/api/vault/pubkey-pin', payload),
getVaultAudit: (params) => {
const search = new URLSearchParams();
if (params?.secret) search.set('secret', params.secret);
if (params?.limit) search.set('limit', String(params.limit));
const qs = search.toString();
return getCachedJson(qs ? `/api/vault/audit?${qs}` : '/api/vault/audit', 1500);
},
importVibeAgents: (payload) => postJson('/api/agents/import', payload),
listSkills: (params) => {
const search = new URLSearchParams();
if (params?.scope) search.set('scope', params.scope);
if (params?.projectId) search.set('project_id', params.projectId);
if (params?.backends?.length) search.set('backends', params.backends.join(','));
const qs = search.toString();
return getCachedJson(qs ? `/api/skills?${qs}` : '/api/skills', 5_000);
},
listMcpServers: () => getJson('/api/mcp', { handleError: false }),
addMcp: (text) => postJson('/api/mcp', { text }, { handleError: false }),
discoverMcp: () => postJson('/api/mcp/discover', {}, { handleError: false }),
refreshMcp: (name) => postJson(`/api/mcp/${encodeURIComponent(name)}/refresh`, {}, { handleError: false }),
removeMcp: (name) => deleteJson(`/api/mcp/${encodeURIComponent(name)}`, undefined, { handleError: false }),
completeMcpLogin: (name, callbackUrl) => postJson(`/api/mcp/${encodeURIComponent(name)}/oauth/complete`, { callbackUrl }, { handleError: false }),
getMcpServer: (name) => getJson(`/api/mcp/${encodeURIComponent(name)}`, { handleError: false }),
previewSkillSource: (source, params) =>
postJson('/api/skills/preview', { source, project_id: params?.projectId }),
addSkill: (payload) =>
postJson('/api/skills', {
source: payload.source,
scope: payload.scope,
project_id: payload.projectId,
backends: payload.backends,
all: payload.all,
skill: payload.skill,
copy: payload.copy,
}),
removeSkill: (name, params) => {
const search = new URLSearchParams();
if (params?.scope) search.set('scope', params.scope);
if (params?.projectId) search.set('project_id', params.projectId);
if (params?.backends?.length) search.set('backends', params.backends.join(','));
const qs = search.toString();
return deleteJson(qs ? `/api/skills/${encodeURIComponent(name)}?${qs}` : `/api/skills/${encodeURIComponent(name)}`);
},
findSkills: (query) => getJson(`/api/skills/find?q=${encodeURIComponent(query)}`),
uploadSkillZip: async (file, params) => {
// Read the file client-side and send it as base64 JSON so the upload
// rides the same /api route + auth as everything else (no multipart).
const dataUrl = await new Promise<string>((resolve, reject) => {
const reader = new FileReader();
reader.onload = () => resolve(String(reader.result));
reader.onerror = () => reject(reader.error);
reader.readAsDataURL(file);
});
const base64 = dataUrl.split(',')[1] ?? '';
return postJson('/api/skills/upload', {
filename: file.name,
content_base64: base64,
project_id: params?.projectId,
});
},
checkSkills: (params) => {
const search = new URLSearchParams();
if (params?.scope) search.set('scope', params.scope);
if (params?.projectId) search.set('project_id', params.projectId);
const qs = search.toString();
return getCachedJson(qs ? `/api/skills/check?${qs}` : '/api/skills/check', 5_000);
},
updateSkill: (name, params) =>
postJson('/api/skills/update', { name, scope: params?.scope, project_id: params?.projectId }),
getHarnessCounts: () => getCachedJson('/api/harness/counts'),
getHarnessBootstrap: (params) => {
const search = new URLSearchParams();
if (params?.tab) search.set('tab', params.tab);
if (params?.status) search.set('status', params.status);
if (params?.run_type) search.set('run_type', params.run_type);
if (params?.exclude_run_type?.length) search.set('exclude_run_type', params.exclude_run_type.join(','));
if (params?.query) search.set('query', params.query);
if (params?.session_id) search.set('session_id', params.session_id);
if (params?.page) search.set('page', String(params.page));
if (params?.limit) search.set('limit', String(params.limit));
const qs = search.toString();
return getCachedJson(qs ? `/api/harness/bootstrap?${qs}` : '/api/harness/bootstrap');
},
listHarnessTasks: (params, opts) => {
const search = new URLSearchParams();
if (params?.status) search.set('status', params.status);
if (params?.query) search.set('query', params.query);
if (params?.page) search.set('page', String(params.page));
if (params?.limit) search.set('limit', String(params.limit));
const qs = search.toString();
return getCachedJson(qs ? `/api/harness/tasks?${qs}` : '/api/harness/tasks', undefined, opts);
},
setHarnessTaskEnabled: (taskId, enabled) =>
patchJson(`/api/harness/tasks/${encodeURIComponent(taskId)}`, { enabled }),
deleteHarnessTask: (taskId) => deleteJson(`/api/harness/tasks/${encodeURIComponent(taskId)}`),
listHarnessWatches: (params, opts) => {
const search = new URLSearchParams();
if (params?.status) search.set('status', params.status);
if (params?.query) search.set('query', params.query);
if (params?.page) search.set('page', String(params.page));
if (params?.limit) search.set('limit', String(params.limit));
const qs = search.toString();
return getCachedJson(qs ? `/api/harness/watches?${qs}` : '/api/harness/watches', undefined, opts);
},
setHarnessWatchEnabled: (watchId, enabled) =>
patchJson(`/api/harness/watches/${encodeURIComponent(watchId)}`, { enabled }),
deleteHarnessWatch: (watchId) => deleteJson(`/api/harness/watches/${encodeURIComponent(watchId)}`),
listHarnessRuns: (params, opts) => {
const search = new URLSearchParams();
if (params?.status) search.set('status', params.status);
if (params?.runType) search.set('run_type', params.runType);
if (params?.excludeRunType?.length) search.set('exclude_run_type', params.excludeRunType.join(','));
if (params?.agentName) search.set('agent_name', params.agentName);
if (params?.definitionId) search.set('definition_id', params.definitionId);
if (params?.query) search.set('query', params.query);
if (params?.page) search.set('page', String(params.page));
if (params?.limit) search.set('limit', String(params.limit));
const qs = search.toString();
return getCachedJson(qs ? `/api/harness/runs?${qs}` : '/api/harness/runs', undefined, opts);
},
getHarnessRun: (runId) => getCachedJson(`/api/harness/runs/${encodeURIComponent(runId)}`),
connectWorkbenchEvents: (handlers) => {
eventHandlersRef.current.add(handlers);
ensureWorkbenchEventSource();
queueMicrotask(() => {
if (eventHandlersRef.current.has(handlers)) {
handlers.onConnectionState?.(eventConnectionStateRef.current);
}
});
if (workbenchEventHandshake()) {
queueMicrotask(() => {
if (eventHandlersRef.current.has(handlers) && workbenchEventHandshake()) {
handlers.onConnected?.();
}
});
}
if (eventControllerLegRef.current === 'connected') {
queueMicrotask(() => {
if (eventHandlersRef.current.has(handlers)) {
handlers.onEventBridgeStatus?.({ connected: true });
}
});
}
return () => {
eventHandlersRef.current.delete(handlers);
if (eventHandlersRef.current.size === 0) {
stopWorkbenchEventSource();
}
};
},
getAgentsGraph: (params) => {
const search = new URLSearchParams();
if (params?.window) search.set('window', params.window);
if (params?.project) search.set('project', params.project);
if (params?.includeEnded === false) search.set('include_ended', '0');
if (params?.includeBackground === false) search.set('include_background', '0');
const qs = search.toString();
return getJson(qs ? `/api/agents-graph?${qs}` : '/api/agents-graph');
},
setSessionVisibility: async (sessionId, visibility) => {
const session = (await patchJson(`/api/sessions/${encodeURIComponent(sessionId)}`, {
visibility,
})) as WorkbenchSession;
// Single chokepoint: replay the committed PATCH as the same session.activity
// event sequence the backend emits, through the existing workbench-event
// pipeline, so the projects tree AND the inbox reconcile via their own
// reducers even when the SSE stream is down (remote/mobile). Any caller
// (sidebar hide, graph toggle) inherits this; a real SSE event arriving
// later is an idempotent no-op.
for (const event of visibilityActivityEvents({
sessionId,
scopeId: session.scope_id,
title: session.title,
visibility,
})) {
emitLocalSessionActivity(event);
}
return session;
},
getRunningAgents: async () => {
const res = await apiFetch('/api/running-agents');
// 503/504 means controller is down; surface as unreachable instead of throwing.
if (res.status === 503 || res.status === 504) {
return { ok: false as const, unreachable: true as const, agents: [], counts: {} };
}
if (!res.ok) {
await handleApiError(res, '/api/running-agents');
}
return res.json();
},
endRunningAgent: async (payload) => {
const res = await apiFetch('/api/running-agents/end', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(payload),
});
if (res.status === 503) {
return { ok: false, unreachable: true };
}
// 409 (couldn't end) returns a body with ok:false + error; surface it.
return res.json().catch(() => ({ ok: res.ok }));
},
remoteAccessStatus: () => getJson('/api/remote-access/status'),
pairVibeCloudRemoteAccess: (payload) => postJson('/api/remote-access/vibe-cloud/pair', payload),
startRemoteAccess: () => postJson('/api/remote-access/start', {}),
stopRemoteAccess: () => postJson('/api/remote-access/stop', {}),
optimizeRemoteAccessRoute: () => postJson('/api/remote-access/optimize-route', {}),
getRemoteAccessNetworkInterfaces: () => getJson('/api/remote-access/network-interfaces'),
saveRemoteAccessSettings: (settings) => postJson('/api/remote-access/settings', settings),
diagnoseRemoteAccess: () => postJson('/api/remote-access/diagnostics', {}),
getAuthSession: () => getJson('/api/session').then(normalizeSessionInfo),
signOut: async () => {
let endpoint: string | undefined;
try {
endpoint = (await getExistingWebPushSubscription())?.endpoint;
} catch {
// Logout remains authoritative when Push APIs are unavailable.
}
return postJson('/auth/logout', {
device_id: await getWebPushDeviceId(),
...(endpoint ? { endpoint } : {}),
});
},
// eslint-disable-next-line react-hooks/exhaustive-deps
}), [sessionDraftPersistence, showToast, t]);
return <ApiContext.Provider value={value}>{children}</ApiContext.Provider>;
};