Server API
Server API
ServerApi
Server environment, configuration and providers.
Configuration reads, snapshots and keybindingsUpdated payloads type
keybindings as resolved rules with command, shortcut and optional
whenAst. Known command names keep their literal types; script and newer
commands remain strings. shortcut.key is trimmed to 1 to 64 characters and
the five modifier flags are required Booleans. whenAst is a recursive union
of identifier, not, and and or nodes without a depth bound; unknown node
types decode as { unknown: true, raw } at any depth and extra metadata is
preserved. A node’s type alone decides whether it is known, so unknown
and raw keys on a known node stay metadata. Malformed rules are omitted and later rules kept; more than 256
remaining rules or a non-array fail decoding, and later valid stream chunks
remain available. Reading keybindings does not add or remove a rule.
Configuration reads, snapshots and keybindingsUpdated payloads type
issues: keybindings.malformed-config with a trimmed nonempty message,
and keybindings.invalid-entry with the same message and a numeric
index without an integer or sign bound. Unknown kinds decode as
{ unknown: true, raw } and extra issue metadata is preserved. Malformed
records are omitted, later valid records and stream chunks remain available,
and a non-array issues fails decoding. Reading issues does not change keybindings.
Configuration reads, snapshots and settings updates expose optional
settings.idleCompaction: onReturn, beforeCacheExpires or off. Growing string
values, omission and unknown settings metadata are preserved. Non-string
values fail decoding; later valid stream chunks remain available. Reading
this metadata does not compact threads or change defaults or timing.
Configuration reads and snapshots expose optional RemoteOpenTarget.username
as a trimmed nonempty string without an extra format or length constraint.
Omission stays absent; unknown target metadata and growing kind strings remain.
Malformed usernames invalidate their target records; the existing compatible
array decoder omits those records and preserves later valid rows and chunks.
Reading this metadata does not look up a username or open an SSH connection.
Configuration reads and snapshots expose optional Boolean
observability.otlpLogsEnabled. False and omission stay intact; malformed
non-Booleans fail decoding, and later valid stream chunks remain available.
This metadata does not enable or configure log export.
Configuration reads and snapshots expose optional Boolean
observability.otlpTracesEnabled. False and omission stay intact; malformed
non-Booleans fail decoding, and later valid stream chunks remain available.
This metadata does not enable or configure trace export.
Configuration reads and snapshots expose optional Boolean
observability.otlpMetricsEnabled. False and omission stay intact; malformed
non-Booleans fail decoding, and later valid stream chunks remain available.
This metadata does not enable or configure metric export.
Configuration reads and snapshots expose optional Boolean
observability.localTracingEnabled. False and omission stay intact; malformed
non-Booleans fail decoding, and later valid stream chunks remain available.
This metadata does not enable or configure local tracing.
Configuration reads and snapshots expose optional observability.logsDirectoryPath:
the server log directory as a trimmed nonempty string without a path-format or
length restriction. Omission stays absent; null, blank and non-string values fail
decoding, and later valid stream chunks remain available. Reading this metadata
does not open, read or create the directory.
Configuration observability exposes optional otlpTracesUrl,
otlpMetricsUrl and otlpLogsUrl: trimmed nonempty strings without a URL-format
or length restriction. Omission stays
absent. Null, blank and non-string values fail configuration decoding;
unknown observability metadata is preserved. Configuration snapshots use
the same schema, and later valid stream chunks remain available after a
decode error. Reading this metadata does not configure telemetry or contact
an endpoint.
Configuration reads and snapshots expose optional directEndpoints: address
hints with kind (lan or tailnet) and nonempty httpBaseUrl. Empty arrays and
omission are distinct. Unknown kind strings and extra metadata are preserved;
malformed entries are dropped, while a non-array field fails decoding.
These are hints only: consumers must verify that an address answers as this
environment before using it. Reading them does not select or connect to one.
Configuration reads and configuration snapshots expose optional
lastEventLoopStall: the latest recent noticeable server event-loop stall.
It contains string detectedAt, nonnegative integer durationMs, positive
integer cpuCount and optional numeric loadAverage (absent on Windows).
Omission means no recent stall was supplied; null and malformed objects fail
decoding. Unknown metadata is preserved. The server controls detection and
expiry; reading this metadata does not cache it or change timing.
Environment capabilities include optional boolean environmentThemes: true
advertises environment-theme publication through configuration streams. False
and omission are preserved; omission does not advertise support. Available
through environment reads, configuration reads and configuration snapshots.
Supplied non-boolean values fail decoding.
Provider auth records also expose optional action metadata with required
elicitationId (trimmed nonempty string, max 256), url (string, max 2048)
and message (string, max 1024). Optional createdAt and expiresAt are
strings of at most 128 characters. Only the elicitation id is trimmed;
other strings permit empty and arbitrary text. Omission and unknown nested
metadata are preserved. Malformed actions make provider records malformed;
existing arrays omit them while later valid records remain available.
Reading this metadata does not open a URL or change authentication state.
Provider auth records expose optional boolean canLogout metadata. True,
false and omission are preserved; omission does not advertise support.
Unknown auth and provider metadata is preserved. Non-boolean values make
the provider record malformed; existing forward-compatible arrays omit it
in reads and streams while later valid records remain available. Reading
this metadata does not log out or change authentication.
Provider records expose optional nativeSessions metadata. When present,
canList, canLoad and canResume are required booleans; canDelete is
optional. False and omission are preserved; omission does not advertise
support. Unknown nested and provider metadata is preserved. Malformed native
session metadata makes the provider record malformed; existing arrays omit
it in reads and streams while later valid records remain available. Reading
this metadata does not perform a native-session operation.
Provider records expose optional supportedRuntimeModes arrays using the
existing RuntimeMode literal set. Omission stays absent; empty arrays stay
empty. Known modes and unknown strings, including duplicates, retain order.
Malformed array entries are dropped. Non-array fields make a provider record
malformed; existing forward-compatible arrays omit it while later valid
records remain available. This metadata does not select a mode or change
runtime defaults or policy.
Provider records expose optional boolean configurableProviders: true
advertises that the provider accepts provider configuration. False and
omission are preserved; omission does not advertise support. Supplied
non-boolean values make the provider record malformed, and existing
forward-compatible arrays omit it in reads and streams. Reading this flag
does not add or call provider configuration operations.
Provider setup records expose optional documentationUrl: a trimmed nonempty
string of at most 2,048 characters. Setup and field omission stay absent.
Malformed provider records are omitted by existing forward-compatible arrays
in reads and streams; unknown setup metadata is preserved. Reading this
metadata does not fetch or open documentation.
Provider records expose optional iconUrl: a trimmed nonempty string of at
most 2,048 characters. Omission stays absent. Malformed provider records are
omitted by the existing forward-compatible arrays in config reads and streams.
Unknown provider metadata is preserved. This field does not fetch or render
an icon; consumers that display remote icons must validate the driver origin.
Published environment themes expose optional canvas: a seed color written
as #RGB or #RRGGBB, with either letter case preserved. Omission stays absent;
whitespace, other strings, null and non-string values fail decoding. Available
in configuration theme arrays and environmentThemesUpdated stream payloads.
Published themes also expose optional accent with the same #RGB/#RRGGBB
format, exact color and case preservation, omission and malformed-value rules
through configuration arrays and environmentThemesUpdated payloads.
Published themes expose optional version: the literal number 1. Omission
stays absent in configuration theme arrays and environmentThemesUpdated
stream payloads. This is theme-file metadata, not a server version check.
Published themes expose optional colors: a palette map whose keys match
/^[a-zA-Z][a-zA-Z0-9]{0,63}$/ and whose string values are trimmed, nonempty
and at most 64 characters after trimming. Empty maps are valid; omission stays
absent. Malformed maps fail decoding in config reads and snapshots; theme
streams report decode errors and continue. Values are not restricted to hex.
Published themes expose optional variants with independently optional light
and dark palette maps. Palette keys match /^[a-zA-Z][a-zA-Z0-9]{0,63}$/;
values are trimmed nonempty strings of at most 64 characters, including CSS
color forms beyond hex. Empty variants and empty palettes are valid. Omission
stays absent; malformed known palettes fail config decoding and produce
recoverable stream decode-errors. Unknown theme and variant metadata is preserved.
Reading these palette variants does not apply a theme.
Environment capabilities also include optional boolean usageLimitSources:
true advertises quota streaming from configured usage-limit sources. False
and omission are preserved; omission does not advertise support. Available
through environment reads, configuration reads and configuration snapshots.
Supplied non-boolean values fail decoding.
Usage-limit source accounts expose optional workspaceId: the workspace the
quota belongs to, as a trimmed nonempty string without a format or length
restriction. They reach watchConfig({ usageLimitSources: true }) updates and
configuration reads that carry usageLimitSources. Omission stays absent and
unknown account metadata is preserved. Malformed values invalidate their
account records; the existing compatible array decoder omits those accounts
and preserves later valid accounts, sources and stream chunks. Reading this
metadata does not select a workspace or change usage-limit polling.
Environment capabilities also include optional boolean usagePriceOverrides:
true advertises custom model rate persistence and application to usage summaries.
False and omission are preserved; omission does not advertise support. Available
through environment reads, configuration reads and configuration snapshots.
Supplied non-boolean values fail decoding. This flag does not configure rates.
Environment capabilities also include optional boolean usageModelAliases:
true advertises model-name mapping through configured usage aliases. False
and omission are preserved; omission does not advertise support. Available
through environment reads, configuration reads and configuration snapshots.
Supplied non-boolean values fail decoding. This flag does not configure aliases.
Environment capabilities also include optional boolean threadPinning:
true advertises support for pinning threads. False and omission are preserved;
omission does not advertise support. Available through environment reads,
configuration reads and configuration snapshots. Supplied non-boolean values
fail decoding. This metadata flag does not pin a thread.
Environment capabilities also include optional boolean threadPinReorder:
true advertises support for reordering pinned threads. False and omission are
preserved; omission does not advertise support. Available through environment
reads, configuration reads and configuration snapshots. Supplied non-boolean
values fail decoding. This metadata flag does not reorder a thread.
Environment capabilities also include optional boolean threadActiveReorder:
true advertises persistence of manual Active thread order. False and omission
are preserved; omission does not advertise support. Available through
environment reads, configuration reads and configuration snapshots. Supplied
non-boolean values fail decoding. This metadata flag does not reorder a thread.
Environment capabilities also include optional boolean threadAutoSettleOptOut:
true advertises support for disabling auto-settle per thread. False and omission
are preserved; omission does not advertise support. Available through
environment reads, configuration reads and configuration snapshots. Supplied
non-boolean values fail decoding. This metadata flag does not change auto-settle.
Environment capabilities also include optional boolean threadTitleRegeneration:
true advertises support for regenerating thread titles through thread metadata
updates. False and omission are preserved; omission does not advertise support.
Available through environment reads, configuration reads and configuration
snapshots. Supplied non-boolean values fail decoding. This metadata flag does
not regenerate a title.
Environment capabilities also include optional boolean threadPullRequestLinking:
true advertises support for linking pull requests to threads. False and omission
are preserved; omission does not advertise support. Available through environment
reads, configuration reads and configuration snapshots. Supplied non-boolean
values fail decoding. This metadata flag does not link a pull request.
Environment capabilities also include optional boolean threadPullRequests:
true advertises support for thread pull requests. False and omission are
preserved; omission does not advertise support. Available through environment
reads, configuration reads and configuration snapshots. Supplied non-boolean
values fail decoding.
Environment capabilities also include optional boolean pullRequestChecks:
true advertises support for pull request checks. False and omission are
preserved; omission does not advertise support. Available through environment
reads, configuration reads and configuration snapshots. Supplied non-boolean
values fail decoding. This metadata flag does not fetch or run checks.
Environment capabilities also include optional boolean threadSnooze:
true advertises support for snoozing threads. False and omission are preserved;
omission does not advertise support. Available through environment reads,
configuration reads and configuration snapshots. Supplied non-boolean values
fail decoding. This metadata flag does not snooze a thread.
Environment capabilities also include optional boolean threadRestartContinuation:
true advertises persistence of the opt-in for continuing interrupted threads
after restarts. False and omission are preserved; omission does not advertise
support. Available through environment reads, configuration reads and
configuration snapshots. Supplied non-boolean values fail decoding.
This metadata flag does not configure or trigger continuation.
Environment capabilities also include optional boolean projectSettingsOverrides:
true advertises support for resolving project settings overrides. False and
omission are preserved; omission does not advertise support. Available through
environment reads, configuration reads and configuration snapshots. Supplied
non-boolean values fail decoding. This metadata flag does not change settings.
Environment capabilities also include optional boolean projectProviderInstanceOverrides:
true advertises support for resolving a project’s provider instance overrides.
False and omission are preserved; omission does not advertise support. Available
through environment reads, configuration reads and configuration snapshots.
Supplied non-boolean values fail decoding. This metadata flag does not change
provider settings.
Environment capabilities also include optional boolean projectCloneTracking:
true advertises support for tracking project clones and streaming their progress.
False and omission are preserved; omission does not advertise support. Available
through environment reads, configuration reads and configuration snapshots.
Supplied non-boolean values fail decoding. This metadata flag does not start or
track a clone.
Environment capabilities also include optional boolean environmentIcon:
true advertises support for a custom environment icon. False and omission are
preserved; omission does not advertise support. Available through environment
reads, configuration reads and configuration snapshots. Supplied non-boolean
values fail decoding. This metadata flag does not select or change an icon.
Environment capabilities also include optional boolean threadAutoSettlement:
true advertises server evaluation of merge and inactivity settlement without a
client. False and omission are preserved; omission does not advertise support.
Available through environment reads, configuration reads and configuration
snapshots. Supplied non-boolean values fail decoding. This metadata flag does
not change settlement settings or settle a thread.
Environment capabilities also include optional boolean requiredWorktreeBootstrap:
true advertises support for required worktree bootstrap. False and omission are
preserved; omission does not advertise support. Available through environment
reads, configuration reads and configuration snapshots. Supplied non-boolean
values fail decoding. This metadata flag does not enforce bootstrap or change
policy.
Environment capabilities also include optional boolean commandOutputStreaming:
true advertises support for streaming command output. False and omission are
preserved; omission does not advertise support. Available through environment
reads, configuration reads and configuration snapshots. Supplied non-boolean
values fail decoding. This metadata flag does not subscribe to command output.
Environment capabilities also include optional boolean ignoredFileListing:
true advertises support for listing ignored files. False and omission are
preserved; omission does not advertise support. Available through environment
reads, configuration reads and configuration snapshots. Supplied non-boolean
values fail decoding. This metadata flag does not list ignored files.
Provider installedVersion is an optional nullable trimmed nonempty string:
the installed CLI version for a local provider with a separate server.
Null means unknown; omission leaves legacy snapshots on version.
This metadata is available through configuration reads, provider lists and
configuration streams; it does not enforce a provider version policy.
Provider workspace snapshots expose optional optionDescriptors arrays using
the existing boolean/select descriptor union. Omission means no descriptor
snapshot was supplied; an empty array supplies no options. Unknown descriptor
types decode to { unknown: true, raw }; malformed known types fail decoding.
Workspace slashCommandsPending is an optional boolean: true marks pending
slash-command discovery; false and omission are preserved without inference.
A pending snapshot can retain the previous slash commands.
Environment capabilities also include optional boolean databaseStorage:
true advertises streaming database size and reclaimable space. False and omission
are preserved; omission does not advertise support. Available through environment
reads, configuration reads and configuration snapshots. Supplied non-boolean
values fail decoding. This metadata flag does not read database storage.
Environment capabilities include optional boolean storageCleanup: true
advertises storage cleanup support. False and omission are preserved; omission
does not advertise support. Available through environment reads, configuration
reads and configuration snapshots. Supplied non-boolean values fail decoding.
This metadata flag does not perform storage cleanup.
Environment capabilities include optional boolean storageCleanupRun: true
advertises support for running storage cleanup. False and omission are preserved;
omission does not advertise support. Available through environment reads,
configuration reads and configuration snapshots. Supplied non-boolean values
fail decoding. This metadata flag does not run storage cleanup.
Environment capabilities also include optional boolean otlpEndpointCheck:
true advertises support for checking OTLP endpoints for telemetry export settings.
False and omission are preserved; omission does not advertise support. Available
through environment reads, configuration reads and configuration snapshots.
Supplied non-boolean values fail decoding. This metadata flag does not check an endpoint.
Environment capabilities also include optional boolean pullRequestStackActions:
true advertises support for pull request stack actions. False and omission are
preserved; omission does not advertise support. Available through environment
reads, configuration reads and configuration snapshots. Supplied non-boolean
values fail decoding. This metadata flag does not perform a pull request stack action.
Environment capabilities also include optional boolean pullRequests: true
advertises server pull request support. False and omission are preserved; omission
does not advertise support. Available through environment reads, configuration
reads and configuration snapshots. Supplied non-boolean values fail decoding.
This metadata flag performs no pull request operation.
Environment capabilities also include optional boolean threadStop:
true advertises support for the upstream thread-stop command. False and
omission are preserved; omission does not advertise support. Supplied
non-boolean values fail decoding. Available through environment reads,
configuration reads and configuration snapshots; unknown fields remain intact.
This metadata flag does not dispatch a command or change threads.stop.
Environment capabilities also include optional boolean serverUpdateThreadContinuation:
true advertises continuation of running provider turns after a server update.
False and omission are preserved; omission does not advertise support.
Supplied non-boolean values fail decoding. Unknown fields remain intact.
This metadata flag does not start an update, restart the server or continue a turn.
Environment capabilities also include optional serverSelfUpdate: boot-service,
respawn or desktop-managed identifies the advertised server update path.
Omission is preserved and advertises no update path. Unknown strings are preserved
for forward compatibility; supplied non-string values fail decoding. Available
through environment reads, configuration reads and configuration snapshots.
This metadata does not start an update or restart a server or desktop app.
Environment capabilities also include optional boolean serverSelfUpdateProgress:
true advertises streaming self-update progress before restart acknowledgement.
False and omission are preserved; omission does not advertise streaming support.
Available through environment reads, configuration reads and configuration snapshots.
Supplied non-boolean values fail decoding. This metadata flag does not start
an update, subscribe to progress or restart the server.
Environment capabilities also include optional boolean desktopAppUpdate:
true advertises a desktop app update through the supervising desktop app.
False and omission are preserved; omission does not advertise support. Available
through environment reads, configuration reads and configuration snapshots.
Supplied non-boolean values fail decoding. This metadata flag does not update
or restart the desktop app or server.
Environment capabilities also include optional boolean agentActivityPublishing:
true reports that agent activity publishing is enabled and relay link credentials
are configured. False and omission are preserved; older servers can omit this
field while still publishing. Available through environment reads, configuration
reads and configuration snapshots. Supplied non-boolean values fail decoding.
This metadata flag does not configure or publish agent activity.
watchDatabaseStorage follows server.getDatabaseStorage: each item is the
state database’s databaseBytes, reclaimableBytes, incrementalVacuumEnabled
and compactCommand, or null until the server first reads the file. The
numbers are finite without an integer or sign bound and compactCommand is a
plain string; all four fields are required and unknown fields are preserved.
A malformed item is delivered as a decode error and later items continue.
Returning early or aborting the signal ends the subscription. Watching does not
reclaim space or run the compact command.
Environment capabilities also include optional booleans sideChats,
threadForceStop, localServerStop and desktopAppChannelSwitch. Omission is
preserved and advertises no support. The descriptor exposes optional
databaseMigration, the highest migration that the server database holds.
Configuration reads expose optional secretProviderSettings and secretReferences,
and observability exposes the optional source and variable of each OTLP endpoint.
A settings endpoint has a null variable. These flags and fields do not change a setting.
Kind: global class